Communication Protocols
Relevant source files
The following files were used as context for generating this wiki page:
The mbbank-mcp project implements the Model Context Protocol (MCP) to facilitate secure and structured communication between a Large Language Model (LLM) and the Military Commercial Joint Stock Bank (MBBank) banking systems. By acting as an intermediary server, it abstracts complex banking API interactions into standardized tools that can be consumed by MCP clients.
The server supports two primary transport layers for communication: Standard Input/Output (stdio) for local process integration and Server-Sent Events (SSE) for web-based or remote streaming communication. This flexibility allows it to integrate seamlessly into desktop environments like Claude Desktop or standalone server deployments.
Sources: README.md:1-10, mbbank_mcp/main.py:42-51, pyproject.toml:13-22
Server Transport Mechanisms
The application utilizes the mcp and fastmcp libraries to provide a robust communication interface. Depending on the execution flags provided at runtime, the server initializes one of two transport protocols.
Standard I/O (stdio)
By default, the server operates using the stdio protocol. This is the preferred method for local integration where a host application (like Claude Desktop) launches the server as a child process and communicates via system pipes.
Sources: README.md:14-25, mbbank_mcp/main.py:75-76
Server-Sent Events (SSE)
When the --sse flag is provided, the server switches to a web-based protocol using uvicorn and starlette. This mode enables:
- SSE Endpoint: A unidirectional stream from the server to the client located at
/sse. - Streamable HTTP: A POST-based command interface located at
/mcp.
Sources: mbbank_mcp/main.py:53-73, README.md:46-52
The diagram above illustrates how different transport layers converge on the central FastMCP server instance to reach the banking backend.
Sources: mbbank_mcp/core.py:20-25, mbbank_mcp/main.py:53-76
Protocol Implementation and Data Flow
The core communication logic is encapsulated in the crate_mcp_server function, which maps banking operations to MCP tools. Each tool follows a request-response cycle where the client sends parameters, and the server returns structured JSON data or media content.
Connection Configuration
The server requires authentication credentials to establish a session with the MBBank backend. These can be passed via command-line arguments or environment variables.
| Option | Environment Variable | Description |
|---|---|---|
--username | MBBANK_USERNAME | The user's MBBank account identifier |
--password | MBBANK_PASSWORD | The user's MBBank password |
--host | N/A | Host address for SSE mode (default: localhost) |
--port | N/A | Port for SSE mode (default: 3000) |
Sources: mbbank_mcp/main.py:26-38, README.md:46-52
Multi-Step Transaction Flow
One of the most complex communication patterns in the project is the money transfer sequence. This requires a two-stage protocol to ensure security through out-of-band authentication (D-OTP).
This sequence ensures that sensitive operations like transfers are not fully automated and require human intervention via the bank's official mobile application.
Sources: mbbank_mcp/core.py:38-120
Data Modeling and Serialization
The server uses Pydantic models to define the communication schema between the banking API and the MCP client. This ensures that the LLM receives clean, predictable, and typed data.
Key Response Models
- BalancesModel: Contains lists of
AccountModelobjects for standard and international accounts. - TransactionsModel: A list of
TransactionModelobjects including dates, amounts, and recipient details. - SavingsModel: Categorizes savings into Online Savings (OSA) and Branch Savings (SBA).
Sources: mbbank_mcp/modals.py:7-92
Media Handling
For the start_transfer tool, the protocol extends beyond text. The server generates a QR code using the qrcode and Pillow libraries, which is then wrapped in an ImageContent object for the MCP client to render.
Sources: mbbank_mcp/core.py:76-88, pyproject.toml:19-20
Security and Session Management
The protocol includes built-in safeguards for sensitive operations:
- Session IDs (SID): A 4-byte hex string (8 characters) is generated for transfer sessions to prevent collisions and track state.
- Expiration: Transfer states are stored in a
transfer_managerdictionary and automatically purged after 120 seconds. - Authentication Validation: The server validates credentials via
mbbank_client._authenticate()before starting any transport listener.
Sources: mbbank_mcp/core.py:36-37, mbbank_mcp/core.py:59-67, mbbank_mcp/main.py:51-52
The mbbank-mcp server provides a structured bridge between banking systems and AI models. By utilizing MCP's standard transport layers and enforcing a strict two-step verification process for transfers, it enables safe monitoring and analysis of financial data within an AI-assisted environment.