BankGuard MCP

A fraud detection engine that AI assistants can operate directly.

BankGuard is an MCP (Model Context Protocol) server. Connect it to Claude Desktop, Claude Code, or any MCP-capable agent, and the AI gets a set of typed tools for running a banking fraud system: submitting transactions, reading alerts, checking portfolio risk, and freezing or unfreezing accounts. You can literally ask Claude "scan the accounts and freeze anything that looks compromised" and watch it work.

The fraud rules themselves live inside the database as SQLite triggers, so they're enforced no matter who writes - the AI, a script, or a human with a sqlite shell. The AI operates the system; it can't bypass the rules.

Why This Design

Most AI integrations bolt a chatbot onto an app. MCP inverts that: the system exposes a safe operating surface, and any AI client can drive it. This project demonstrates both halves:

• The engine - six fraud rules implemented as in-database triggers (invalid amounts, frozen-account blocks, daily limits, velocity detection, risk scoring with auto-freeze, and event emission)
• The AI surface - eight MCP tools with docstrings the model reads to decide when and how to act. Destructive actions (freeze/unfreeze) require a reason, which is recorded as an audit alert.

Claude Desktop / Claude Code / any agent
        |  MCP (stdio)
        v
   server.py        eight typed tools
        |
        v
   bankguard.db     SQLite + trigger-enforced fraud rules

Tools

Tool	What it does
list_accounts	All accounts with owner, status, risk score
get_account_activity	Recent transactions for one account
submit_transaction	Insert a transaction; fraud rules may reject or flag it
get_fraud_alerts	Recent alerts raised by the rules
get_notifications	Queued events for downstream systems
freeze_account	Analyst freeze, reason required and audited
unfreeze_account	Reactivate and reset risk, reason audited
risk_summary	Portfolio totals, alerts by rule, riskiest accounts

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python database.py       # creates bankguard.db with 5 seeded accounts
python test_server.py    # end-to-end test through a real MCP client

Connect to Claude Code

claude mcp add bankguard -- /path/to/bankguard-mcp/.venv/bin/python /path/to/bankguard-mcp/server.py

Connect to Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bankguard": {
      "command": "/path/to/bankguard-mcp/.venv/bin/python",
      "args": ["/path/to/bankguard-mcp/server.py"]
    }
  }
}

Then try prompts like:

• "Give me a risk summary of the bank"
• "Submit five $100 transactions to account 102 and tell me what happens"
• "Which account is riskiest? Show its recent activity and freeze it if warranted"

The Fraud Rules

1. Amount validation - zero/negative transactions rejected before insert
2. Status validation - frozen accounts reject all transactions, even direct DB writes
3. Daily limit - per-day spend cap enforced per account
4. Velocity detection - 3+ transactions inside 60 seconds raises an alert and +20 risk
5. Auto-freeze - account freezes itself when risk reaches 60
6. Event emission - velocity and freeze events queue notifications for downstream consumers

test_server.py proves all six by driving the server over stdio the same way a real client does.

Project Structure

bankguard-mcp/
    server.py        MCP server - the AI-facing tool surface
    database.py      SQLite engine with trigger-enforced fraud rules
    test_server.py   end-to-end test through the MCP protocol
    requirements.txt

Ideas for Later

• Postgres backend for the same tool surface
• MCP resources exposing the schema and rule documentation
• Human-in-the-loop: mark freeze/unfreeze as requiring client-side approval
• Streamable HTTP transport for remote deployment