mcp-server-enterprise-tools

Reference MCP server for regulated enterprises. Per-tool RBAC, redacted audit log, structured error envelope, and drop-in configs for Claude Desktop plus a plain HTTPS transport for internal agents.

Deployed URL: https://mcp-tools.internal.example (placeholder, replace in your fork; the terraform in terraform/ provisions an internal ALB you front with your own DNS).

The problem

MCP (Model Context Protocol, announced by Anthropic on 2024-11-25) standardizes how an LLM host discovers and calls tools. That is great for consumer laptops. For a bank it is not enough on its own:

• MCP has no first-class caller identity, and a regulator needs to know who called what
• tool arguments and results can carry PII (SSNs, PANs, account numbers), and those cannot land in cleartext in logs or audit tables
• error handling in the spec is thin; internal callers need something machine-readable to branch on

This repo is an opinionated take on filling those gaps while keeping the tool implementations small and readable.

What is exposed

Three bank tools:

Tool	Verb	Purpose
customer_360.lookup	read	profile, primary account summary, risk flags
statement_search.query	read	full-text with date and amount filters
dispute_resolution.open	mutating	open a dispute against a transaction
dispute_resolution.status	read	dispute state by id

Each is a real MCP tool with a JSON input schema. Adding a fourth is a single file under src/mcp_server/tools/ plus a line in app.build_registry.

Architecture

              +--------------------+          +------------------+
              |  Claude Desktop    |          |  Internal agent  |
              |  (stdio)           |          |  (http)          |
              +---------+----------+          +---------+--------+
                        |                               |
                        |               X-Bank-Identity |
                        v                               v
                    +---+-------------------------------+---+
                    |          MCP server (this repo)        |
                    |  transport -> registry.call -> handler |
                    |                    |                   |
                    |            rbac.check + audit.write    |
                    +----+-----------------+----------+------+
                         |                 |          |
                         v                 v          v
                +------------------+  +---------+  +------------------+
                | bank internal    |  | Postgres|  | Prometheus       |
                | APIs (customer,  |  | audit   |  | metrics scraped  |
                | statements,      |  | log     |  | at /metrics      |
                | disputes)        |  +---------+  +------------------+
                +------------------+

Longer version with request flow: docs/architecture.md.

Quick start

Local (stdio, what Claude Desktop uses):

uv pip install -e '.[dev]'         # or plain pip
export AUDIT_DB_URL=sqlite:///./audit.db
export MCP_IDENTITY=user:local
make run

Local (http + postgres via compose):

docker compose up --build
# server on :8080, prometheus on :9090, postgres on :5432
curl -s -X POST http://localhost:8080/mcp/call \
  -H "X-Bank-Identity: svc-analyst-01" \
  -H "Content-Type: application/json" \
  -d '{"tool":"customer_360.lookup","args":{"customer_id":"C-01234567"}}'

Point Claude Desktop at the server: copy examples/claude_desktop_config.json into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the Windows equivalent. Walkthrough in docs/claude_desktop_setup.md.

RBAC model

Deny by default. Policies in configs/rbac.yaml map identities to allowed tool names, with a trailing .* wildcard for grouping. Every call, allowed or denied, writes an audit row. Full spec in docs/rbac_model.md.

Audit log design

One row per tool call, in Postgres. Columns: request_id, identity, tool, outcome, args_redacted, error_code, duration_ms, created_at.

Every string in args is passed through Redactor before persistence: SSNs, PANs (Luhn-checked), email addresses, and long numeric IDs are replaced with marked tokens. The upstream response is also sanitized before it leaves the process. Details in src/mcp_server/redaction.py and the tests.

Structured errors

Every failure comes back as an ErrorEnvelope:

{
  "error": {
    "code": "forbidden",
    "message": "identity 'svc-analyst-01' is not permitted to call 'dispute_resolution.open'",
    "request_id": "0d3f4a...",
    "tool": "dispute_resolution.open",
    "retryable": false,
    "details": {}
  }
}

Codes: unauthenticated, forbidden, not_found, invalid_argument, upstream_unavailable, rate_limited, internal. Clients can branch on code without string-matching messages.

Deploy

Terraform under terraform/ provisions an internal ALB, ECS Fargate service, and RDS Postgres for the audit log. make tf-plan to review.

Prod checklist:

1. Populate a real configs/rbac.yaml. Prefer many narrow identities over a few broad ones.
2. Wire the X-Bank-Identity header to be set by a trusted upstream (mTLS terminator, OIDC proxy). The server does not authenticate; it only reads the resolved identity.
3. Ship the audit table to your SIEM nightly. The table is the source of truth.
4. Rotate the break-glass credential weekly and alert on every use.

Repo layout

src/
  mcp_server/       server, registry, rbac, audit, redaction, tools/
  mcp_client/       stdio + http client used for testing and examples
configs/            default.yaml, rbac.yaml, prometheus.yml
terraform/          aws vpc + ecs + rds
tests/              rbac, audit, redaction, tools, registry
examples/           claude_desktop_config.json, transcripts
docs/               mcp primer, architecture, rbac model, claude setup

Status

Early. MCP shipped two weeks ago; the SDK will move. Pinned versions in pyproject.toml reflect what shipped with the announcement. Bump as the SDK stabilizes.

License

MIT. See LICENSE.