Core Server Logic

Relevant source files

The following files were used as context for generating this wiki page:

• mbbank_mcp/core.py
• mbbank_mcp/__init__.py
• mbbank_mcp/__main__.py
• mbbank_mcp/modals.py
• pyproject.toml
• README.md

The Core Server Logic of the mbbank-mcp project facilitates the integration between the Model Context Protocol (MCP) and the MB Bank API. Its primary purpose is to expose banking functionalities—such as balance inquiries, transaction history, and fund transfers—as structured tools that can be consumed by MCP-compatible clients like Claude Desktop.

The system acts as a bridge, utilizing the mbbank-lib to communicate with bank services and the FastMCP framework to handle the server-side protocol requirements. It supports multiple transport modes, including standard input/output (stdio) and Server-Sent Events (SSE), ensuring flexibility in deployment.

Sources: mbbank_mcp/core.py:1-26, mbbank_mcp/__main__.py:33-50, README.md:1-10

Initialization and Bootstrap

The server's entry point is located in __main__.py, which utilizes the click library to handle command-line arguments. During startup, the server authenticates with MB Bank using provided credentials and initializes the FastMCP instance.

Execution Flow

1. Argument Parsing: Collects username, password, and server configuration (host, port, transport mode).
2. Authentication: Validates credentials via mbbank_client._authenticate().
3. Server Creation: Calls crate_mcp_server to register all available tools and resources.
4. Transport Selection: Starts the server in either Stdio mode (standard) or SSE mode (using Starlette and Uvicorn).

Tooling and Functionality

The core logic defines several tools registered to the FastMCP instance. These tools allow the MCP client to perform specific banking actions.

Financial Monitoring Tools

These tools are read-only and provide insights into account states and history.

Tool Name	Purpose	Return Type
get_balances	Fetches balances for all accounts.	BalancesModel
get_transactions	Retrieves history for a specific account.	TransactionsModel
get_cards	Lists all associated credit/debit cards.	CardsModel
get_savings	Lists online and branch savings accounts.	SavingsModel
get_interest_rates	Fetches current bank interest rates.	InterestRateResponseModal

Sources: mbbank_mcp/core.py:117-251, mbbank_mcp/modals.py:7-92

Transfer Logic and State Management

The transfer process is a multi-step workflow involving session management and QR code generation.

1. Initiation: start_transfer creates a TransferContextAsync and generates a unique Session ID (sid).
2. QR Generation: A QR code is generated for the user to scan via the MB Bank mobile app to obtain a Digital OTP (D-OTP).
3. Verification: verify_transfer uses the sid and the user-provided otp to finalize the transaction.

Session Management

The server maintains an in-memory transfer_manager dictionary to track active transfer attempts. To prevent memory leaks and ensure security, a background task automatically purges expired sessions.

• Storage: dict[str, TransferState] where TransferState contains the create_time and the library's state object.
• Expiration: Sessions expire after 120 seconds (2 minutes).
• Cleanup: An asynchronous task (_remove_expired_transfers) runs with a buffer to delete stale entries.

Sources: mbbank_mcp/core.py:21-24, mbbank_mcp/core.py:33-35, mbbank_mcp/core.py:80-91

Data Transformation Layer

The server uses a set of Pydantic models in modals.py to act as a proxy between raw MB Bank API responses and the MCP interface. This ensures that the data returned to the LLM or user is clean and uses descriptive field names.

Key Models

• AccountModel: Normalizes account details (number, name, currency, balance).
• TransactionModel: Handles formatting of amounts (adding '+' or '-' prefixes based on credit/debit status) and maps beneficiary details.
• SavingDetailModel: Provides a comprehensive view of a single savings account including maturity instructions and accrued interest.

Sources: mbbank_mcp/modals.py:1-92, mbbank_mcp/core.py:145-156

Configuration and Environment

The server's behavior is influenced by environment variables and CLI flags defined in pyproject.toml and __main__.py.

Option	Env Variable	Default	Description
--username	MBBANK_USERNAME	None	MB Bank Login ID
--password	MBBANK_PASSWORD	None	MB Bank Password
--sse	N/A	False	Enables SSE transport mode
--port	N/A	3000	Port for SSE/HTTP
--host	N/A	localhost	Bind address for SSE/HTTP

Sources: mbbank_mcp/__main__.py:26-31, pyproject.toml:22-30

Conclusion

The Core Server Logic is designed with a focus on modularity and security. By encapsulating complex banking state machines (like multi-factor transfer verification) into simple MCP tools, it enables LLMs to interact with financial data safely. The inclusion of an automated cleanup mechanism for transfer sessions and a robust data normalization layer makes the server both reliable and easy to integrate into larger AI workflows.