Meridian Bank MCP Server

A production-grade remote Model Context Protocol (MCP) server for a fictional digital bank ("Meridian"). It exposes the tools an AI ops/support copilot would use to service customers, spanning the full risk spectrum from read-only lookups to money movement and destructive admin actions.

It is a realistic customer artifact built to validate LLM Shield's guardrails + agentic IDP. It stands on its own as a real OAuth 2.1-protected MCP server.

Transport: Streamable HTTP (POST /mcp), stateless.
Auth: OAuth 2.1 — the server is a resource server (RFC 9728 protected-resource metadata, RFC 8707 audience-bound tokens) with a co-located minimal authorization server (RFC 8414 metadata, PKCE S256, authorization_code + refresh_token + client_credentials, Ed25519-signed JWTs). Conforms to the MCP 2025-11-25 auth spec.
Storage: PostgreSQL via Drizzle ORM, seeded with a realistic dataset.
SDK: @modelcontextprotocol/sdk v1.x (TypeScript).

See docs/specs and docs/plans for the design and plan.

Tool catalog

Tool	Risk	Required scope
`search_customers`, `get_customer`, `list_accounts`, `get_account`, `get_balance`, `list_transactions`, `get_transaction`, `list_cards`	read (PII in output)	`banking:read`
`freeze_card`, `unfreeze_card`, `freeze_account`, `unfreeze_account`, `create_payee`, `open_dispute`	reversible write	`banking:write`
`create_transfer`, `initiate_ach_payment`	money movement	`payments:write`
`initiate_wire`	money movement	`payments:write` and `wire:write`
`reverse_transaction`, `close_account`, `adjust_balance`	destructive / admin	`admin:write`

Money movement is atomic and idempotent (row-locked source, unique idempotency_key, no negative balances). Every mutation writes an audit_log row. Insufficient scope is returned as an MCP tool error (isError), not an HTTP 403, because Streamable HTTP multiplexes all tool calls over one POST /mcp.

Run locally

Prerequisites: Node 22+, Docker (for Postgres).

# 1. Postgres
docker run -d --name meridian-pg -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=meridian -p 5433:5432 postgres:16

# 2. Env
cp .env.example .env.local   # edit if needed; SEED_ON_BOOT=true for demo data

# 3. Install + run (migrates, seeds, listens on :8080)
npm install
npm run dev            # or: npm run build && npm start

Scripts: npm run build, npm start, npm run dev, npm test, npm run db:generate, npm run db:migrate, npm run db:seed.

Dev operator credentials (seeded; NOT for production)

Username	Password	Role
`alice.admin`	`meridian-dev-1`	admin
`bob.ops`	`meridian-dev-1`	ops
`carol.support`	`meridian-dev-1`	support

Try it

Machine-to-machine (client_credentials):

B=http://localhost:8080
TOKEN=$(curl -s -X POST $B/token \
  -d grant_type=client_credentials \
  -d client_id=meridian-copilot -d client_secret=dev-client-secret-change-me \
  -d 'scope=banking:read payments:write' -d resource=$B/mcp | jq -r .access_token)

# discovery
curl -s $B/.well-known/oauth-protected-resource/mcp | jq
curl -s $B/.well-known/oauth-authorization-server | jq

# unauthorized → 401 + WWW-Authenticate
curl -i -X POST $B/mcp -H 'content-type: application/json' -d '{}'

Full end-to-end smoke (MCP handshake, scope enforcement, transfer, idempotency):

OAUTH_CLIENT_SECRET=dev-client-secret-change-me npx tsx scripts/mcp-smoke.ts
npx tsx scripts/authcode-smoke.ts   # browser-style authorization_code + PKCE

MCP Inspector (interactive): point it at http://localhost:8080/mcp (Streamable HTTP). It will run OAuth discovery; complete the operator login/consent with a dev credential above.

Deploy to Railway

The server is deploy-ready (Dockerfile + railway.json, /healthz health check).

railway login
railway init                       # or link an existing project
railway add -d postgres            # provision managed Postgres
# In the service Variables, set:
#   DATABASE_URL   = ${{Postgres.DATABASE_URL}}
#   PUBLIC_URL     = https://<your-service>.up.railway.app   (set after the domain exists)
#   AUTH_SIGNING_KEY = <a stable Ed25519 private JWK>         (so tokens survive restarts)
#   COOKIE_SECRET, OAUTH_CLIENT_SECRET = <secrets>
#   SEED_ON_BOOT = true                                       (first deploy, to seed demo data)
railway up                         # build + deploy from the Dockerfile
railway domain                     # generate the public URL

The MCP endpoint is then https://<your-service>.up.railway.app/mcp. Set PUBLIC_URL to that origin so the token audience and metadata are correct, then redeploy.

Note: railway.com/mcp is Railway's own site; your server lives at your Railway-assigned domain (or a custom domain you attach), not on railway.com itself.

Putting LLM Shield in front (later)

Meridian is designed to sit behind Shield's MCP proxy (a Policy Enforcement Point). When that phase starts:

Isolate Meridian on the network so Shield's proxy is the only path to it.
AUTH_ISSUER is env-driven, so Shield's OAuth authorization server can replace the co-located AS without code changes.

Configuration

See .env.example for all variables. Key ones: PUBLIC_URL (drives the token audience PUBLIC_URL/mcp), AUTH_ISSUER, AUTH_SIGNING_KEY, DATABASE_URL, OAUTH_CLIENT_*, SEED_ON_BOOT.