# Secure Banking MCP

This is a working demonstration of an AI assistant accessing mock banking data without being trusted to decide who the user is.

The assistant may ask for an account by its account number. It cannot supply a user, company, role, or tenant. Those facts come from a signed access token carried outside the conversation. Every database lookup combines the requested account with that verified identity.

> This project contains fictional data and development tokens. It is an educational reference, not a deployable bank.

## Quickstart

Requirements: Python 3.12+ and [uv](https://docs.astral.sh/uv/).

```bash
uv sync --extra dev
uv run secure-banking-mcp

```

The MCP endpoint is `http://127.0.0.1:8000/mcp`. In VS Code, start the server and connect using the included `.vscode/mcp.json`. Enter `demo-alice-token` when prompted.

Run the security evidence suite:

```bash
uv run pytest

```

This produces both raw Allure evidence in `allure-results/` and a self-contained HTML report at `allure-report/index.html`. Open the HTML file directly in a browser; no Allure CLI, Java installation, or report server is required.

The HTML is a portable pytest report rather than the official Allure dashboard. The raw evidence remains compatible with the official Allure CLI if that richer dashboard is needed later.

## What Protects The Data

Think of the language model as an untrusted person filling in a request form. It can choose an account number and an amount, but it cannot fill in the "who am I?" field because that field does not exist on the form.

1. The MCP client sends a bearer token outside the prompt and tool arguments.
2. FastMCP verifies the token signature, issuer, audience, and expiry in production mode.
3. A dependency converts verified claims into an internal `Principal`.
4. A scope check decides whether that person may use the requested capability.
5. SQLite queries require the account, tenant, and owner to match together.
6. Failure messages do not reveal whether another customer's account exists.

```mermaid
flowchart LR
    U[Person] --> C[MCP client]
    L[Untrusted model] -->|account and amount only| C
    C -->|tool arguments| M[FastMCP]
    C -->|bearer token, outside prompt| V[Token verifier]
    V --> P[Trusted principal]
    M --> A[Scope guard]
    P --> A
    A --> S[Banking service]
    S -->|account + verified tenant + verified owner| D[(SQLite mock data)]

```

## Demonstrated Attacks

The tests prove that:

* Prompt instructions cannot change the authenticated identity.
* Replacing Alice's account number with Mallory's returns a generic denial.
* Adding `user_id`, `tenant_id`, or `role` to tool input is rejected by the schema.
* Read-only users cannot call money-moving services.
* A transfer cannot cross an ownership or tenant boundary.

## Production Boundary

Set all three variables to replace the local static-token verifier with asymmetric JWT verification:

```bash
export BANKING_JWKS_URI=https://identity.example/.well-known/jwks.json
export BANKING_JWT_ISSUER=https://identity.example/
export BANKING_JWT_AUDIENCE=secure-banking-mcp

```

Production should also use TLS, a managed database with row-level security, short-lived tokens, key rotation, immutable audit logs, rate limits, and a policy engine for richer rules. Never enable shared response caching for identity-derived financial results.

See [docs/architecture.md](docs/architecture.md) for the component decisions and trust boundaries.