🏦 MCP Banking Server

A production-ready banking server built with FastMCP (Model Context Protocol) featuring modern API design patterns, real-time updates, and enterprise-grade features.

✨ Features

Quick Start

Prerequisites

• Python 3.10+
• pip or uv package manager

Installation

# Clone or navigate to the project directory
cd mcp

# Install dependencies
pip install -r requirements.txt

Run the Server

# Start the server
python server.py

# Or use uvicorn directly
uvicorn server:app --reload --port 8000

The server will start and display:

• 🔑 Your default API key (save this!)
• 📚 API documentation URL

Access the API

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• Health Check: http://localhost:8000/health

🔑 Authentication

All endpoints (except health check and root) require an API key.

Include the X-API-Key header in your requests:

curl -H "X-API-Key: YOUR_API_KEY" http://localhost:8000/accounts/1234567890

The default API key is displayed when the server starts.

Disabling Authentication (for Demo/Testing)

To run the server without authentication (useful for demos or when being scanned by other services):

# Windows PowerShell
$env:DISABLE_AUTH="true"; python server.py

# Windows CMD
set DISABLE_AUTH=true && python server.py

# Linux/Mac
DISABLE_AUTH=true python server.py

When disabled, all endpoints become publicly accessible without needing the X-API-Key header.

📖 API Reference

Accounts

Create Account

curl -X POST http://localhost:8000/accounts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"holder_name": "John Doe"}'

Get Account Details

curl http://localhost:8000/accounts/1234567890 \
  -H "X-API-Key: YOUR_API_KEY"

Transactions

Deposit (with idempotency)

curl -X POST http://localhost:8000/accounts/1234567890/deposit \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"amount": 100.00}'

Withdraw

curl -X POST http://localhost:8000/accounts/1234567890/withdraw \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50.00}'

Get Transaction History

curl "http://localhost:8000/accounts/1234567890/transactions?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

Export Transactions as CSV

curl http://localhost:8000/accounts/1234567890/transactions/export \
  -H "X-API-Key: YOUR_API_KEY" \
  -o transactions.csv

📡 WebSocket Live Updates

Connect to receive real-time transaction notifications:

// Browser JavaScript example
const ws = new WebSocket('ws://localhost:8000/ws/transactions/1234567890');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Transaction update:', data);
};

ws.onopen = () => {
  console.log('Connected to transaction updates');
};

WebSocket Message Types

// Connection established
{"type": "connected", "message": "Connected to transaction updates", "account_number": "1234567890"}

// Transaction notification
{"type": "transaction", "data": {"id": 1, "type": "DEPOSIT", "amount": 100.0, ...}}

// Ping response
{"type": "pong"}

MCP Tools

For LLM integration, the following MCP tools are available:

Using with FastMCP CLI

# Run in MCP mode
fastmcp run server.py:mcp --transport http --port 8000

# Development mode with inspector
fastmcp dev server.py:mcp

Docker Deployment

Build and Run

# Build the image
docker build -t mcp-banking-server .

# Run the container
docker run -d -p 8000:8000 --name banking-server mcp-banking-server

Docker Compose (optional)

version: '3.8'
services:
  banking-server:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    restart: unless-stopped

📁 Project Structure

mcp/
├── server.py              # Main FastMCP server with MCP tools & REST API
├── database.py            # SQLite database operations
├── auth.py                # API key authentication
├── websocket_manager.py   # WebSocket connection management
├── requirements.txt       # Python dependencies
├── Dockerfile             # Container configuration
├── README.md              # This file
└── bank.db                # SQLite database (created at runtime)

Idempotency

The deposit and withdraw endpoints support idempotency to prevent duplicate transactions:

1. Include an Idempotency-Key header with a unique identifier
2. If the same key is used again within 24 hours, the original response is returned
3. The idempotent_replay: true flag indicates a cached response

# First request - processes the transaction
curl -X POST ... -H "Idempotency-Key: txn-abc-123" -d '{"amount": 100}'

# Second request with same key - returns cached response
curl -X POST ... -H "Idempotency-Key: txn-abc-123" -d '{"amount": 100}'
# Response includes: "idempotent_replay": true