Mono Banking MCP Server
A comprehensive Model Context Protocol (MCP) server for Nigerian banking operations using the Mono Open Banking API. Features integrated webhook support for real-time banking events and seamless deployment on FastMCP Cloud.
Table of Contents
- Key Features
- Architecture
- Technologies Used
- Project Structure
- Webhook Integration
- Quick Start
- Usage
- Available Banking Tools
- Contributing
Key Features
- Complete Banking Operations - Account management, payments, BVN verification
- Real-time Webhooks - Integrated webhook endpoints for live banking events
- AI Assistant Ready - Seamless integration with Claude, ChatGPT, and other AI assistants
- Cloud Deployment - Ready for FastMCP Cloud with automatic scaling
- Enterprise Security - HMAC signature verification and secure API handling
- Event Monitoring - Built-in webhook event storage and debugging tools
Architecture
sequenceDiagram
participant User as 👤 User
participant AI as 🤖 AI Assistant<br/>(Claude/ChatGPT)
participant MCP as ⚡ MCP Server<br/>(FastMCP + Webhooks)
participant Client as 🔗 Mono Client<br/>(httpx)
participant API as 🏦 Mono API<br/>(Nigerian Banks)
participant Webhook as 📡 Webhook Events
User->>AI: "Check my account balance"
AI->>MCP: list_tools()
MCP-->>AI: 12 banking tools + webhook monitoring
AI->>MCP: get_account_balance(account_id)
MCP->>Client: get_account_balance(account_id)
Client->>API: GET /accounts/{id}/balance
API-->>Client: {"balance": 50000, "currency": "NGN"}
Client-->>MCP: Account balance data
MCP-->>AI: {"success": true, "balance": "₦500.00"}
AI-->>User: "Your account balance is ₦500.00"
Note over Webhook,MCP: Real-time Events
API->>MCP: POST /mono/webhook (account.updated)
MCP->>MCP: Verify HMAC signature
MCP->>MCP: Store event in database
Technologies Used
- Python 3.12+ - Modern Python with async/await support
- FastMCP 2.12+ - Simplified MCP server with custom route support
- Starlette - ASGI framework for webhook endpoints
- httpx - Modern async HTTP client for API communication
- SQLAlchemy - Database ORM for webhook event storage
- Mono Open Banking API v2 - Nigerian banking infrastructure
- python-dotenv - Environment variable management
- uv - Fast Python package manager (recommended)
Project Structure
mono-banking-mcp/
├── mono_banking_mcp/ # Main package
│ ├── server.py # FastMCP server with 12 tools + webhook endpoints
│ ├── mono_client.py # Mono API client with async httpx
│ └── database.py # SQLAlchemy database for webhook events storage
├── tests/ # Comprehensive test suite with webhook integration tests
│ ├── conftest.py # Test configuration and fixtures
│ └── test_mono_banking.py # Unit and integration tests
├── pyproject.toml # Modern Python project configuration (uv-based)
├── uv.lock # Dependency lock file with FastMCP 2.12+
├── pytest.ini # Test configuration and markers
├── Makefile # Development workflow automation with webhook commands
├── README.md # This comprehensive documentation
└── .env.example # Environment variables template
Webhook Integration
Real-time Event Processing
The server includes integrated webhook support for real-time banking events:
graph LR
A[Mono API] -->|POST /mono/webhook| B[FastMCP Server]
B -->|HMAC Verify| C[Signature Check]
C -->|✅ Valid| D[Store Event]
C -->|❌ Invalid| E[Reject]
D --> F[SQLite Database]
F --> G[get_webhook_events Tool]
G --> H[AI Assistant]
Key Integration Points
/mono/webhook- Webhook endpoint for real-time Mono events/health- Health check endpoint for monitoring
Supported Webhook Events
account.connected- New account linkedaccount.updated- Account information changedaccount.unlinked- Account disconnectedjob.completed- Data sync completedjob.failed- Data sync failed
Security Features
- HMAC-SHA256 Signature Verification - Ensures webhook authenticity
- Environment-based Secrets - Secure credential management
- Request Validation - Malformed request rejection
- Event Storage - Audit trail for all webhook events
Quick Start
Ready to use immediately! Connect your AI assistant to:
https://mono-banking-mcp.fastmcp.app/mcp
Available Endpoints
- MCP Server:
https://mono-banking-mcp.fastmcp.app/mcp - Webhook Endpoint:
https://mono-banking-mcp.fastmcp.app/mono/webhook - Health Check:
https://mono-banking-mcp.fastmcp.app/health
Usage
Claude Desktop Integration
Add to your Claude Desktop configuration (~/.config/claude-desktop/config.json):
{
"mcpServers": {
"mono-banking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-fetch", "https://mono-banking-mcp.fastmcp.app/mcp"]
}
}
}
Usage Examples
Once connected to an AI assistant (Claude, Gemini, etc.), you can use natural language commands:
Account Management
- "List all my linked bank accounts"
- "Show me the balance for account abc123"
- "Get detailed information for my GTBank account"
- "Show me the last 20 transactions for account xyz789"
Payment Operations
- "Verify the account name for 0123456789 at GTBank (code 058)"
- "Initiate a payment of ₦5000 to account 1234567890 at Access Bank for John Doe"
- "Check the status of payment reference PAY_ABC123"
Banking Information
- "Show me all supported Nigerian banks and their codes"
- "Look up BVN 12345678901 for identity verification"
- "Help a new customer link their bank account"
Complete Workflow Example
- "Show me all Nigerian banks" - Get bank codes
- "Verify account 1234567890 at Access Bank" - Confirm recipient
- "Initiate payment of ₦10000 to verified account for rent payment" - Start payment
- "Check payment status for the reference you just gave me" - Verify completion
Available Banking Tools
The server provides these comprehensive banking tools (12 total):
Core Banking Operations
Contributing
Contributions to the Mono Banking MCP Server are welcome! For questions or help getting started, please open an issue.
Development Workflow
Quick Start for Contributors:
# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/mono-banking-mcp.git
cd mono-banking-mcp
# Set up development environment
uv sync
uv pip install -e .
# Verify installation with webhook support
python -c "from mono_banking_mcp.server import mcp; print('✅ Package installed successfully')"
# Run comprehensive tests
make test-all
# Create feature branch and start developing
git checkout -b feature/your-feature-name
# Test your changes
make test-webhook # Test webhook functionality
make tools # Verify all 12 tools are working