Extending MCP Tools

Relevant source files

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

• mbbank_mcp/core.py
• mbbank_mcp/modals.py
• mbbank_mcp/main.py
• mbbank_mcp/init.py
• README.md
• pyproject.toml

The mbbank-mcp project provides a Model Context Protocol (MCP) server implementation that interfaces with the MBBank API. Extending the available tools involves leveraging the FastMCP framework to wrap asynchronous calls from the mbbank-lib into structured, executable tools that can be consumed by MCP clients like Claude Desktop.

Sources: pyproject.toml:1-20, README.md:1-10, mbbank_mcp/core.py:18-24

Tool Registration Architecture

The core of the extension system is the crate_mcp_server function, which initializes a FastMCP instance and registers various tools using the @fast_mcp.tool() decorator. Each tool is an asynchronous Python function that maps specific MBBank functionalities—such as balance checks, transaction history, or money transfers—to the MCP interface.

The diagram shows how the FastMCP instance serves as the central registry for decorated tool functions.
Sources: mbbank_mcp/core.py:18-25

Core Components for Tool Development

• FastMCP: The primary class used to define the server and its tools.
• MBBankAsync: The underlying client from mbbank-lib used to perform actual API operations.
• Pydantic Models: Used to ensure type-safe data exchange and to rename raw API fields into developer-friendly formats.

Sources: mbbank_mcp/core.py:11-16, mbbank_mcp/modals.py:1-10

Data Modeling and Proxies

To extend tools effectively, developers must use the models defined in modals.py. These models act as proxies to transform complex or inconsistently named MBBank API responses into clean, standardized structures.

Model Name	Description	Key Fields
AccountModel	Represents a single bank account.	accountNumber, balance, currency
TransactionModel	Details of a single financial movement.	amount, description, transferredTo
SavingModel	Information regarding a savings account.	principalAmount, maturityDate, ratePercentPerYear
CardModel	Details of associated credit/debit cards.	cardNumber, cardStatus, cardType

Sources: mbbank_mcp/modals.py:1-85

State-Managed Tools: The Transfer Flow

Extending tools that require state, such as money transfers, involves managing temporary session data. The project uses a transfer_manager dictionary to store TransferState objects, which include a TransferContextAsync and a timestamp for expiration.

This sequence illustrates the stateful interaction required for two-step verification processes.
Sources: mbbank_mcp/core.py:15-17, mbbank_mcp/core.py:27-72

Transfer Implementation Details

• SID Generation: Uses os.urandom(4).hex() to create unique session identifiers.
• Expiration Logic: An asynchronous task _remove_expired_transfers runs to clean up sessions older than 120 seconds to prevent memory leaks.
• Verification: The verify_transfer tool retrieves the state using the SID and completes the transaction with a user-provided OTP.

Sources: mbbank_mcp/core.py:48-52, mbbank_mcp/core.py:73-86, mbbank_mcp/core.py:88-103

Server Entry Point and Execution

New tools become available when the server is launched via mbbank_mcp.__main__. The server supports two communication modes which can be extended or configured:

1. Stdio Mode: Default mode for local integration (e.g., Claude Desktop).
2. SSE Mode: Enabled via the --sse flag, using uvicorn and Starlette to provide a web-based MCP interface.

# mbbank_mcp/__main__.py:44-46
mbbank_client = MBBankAsync(username=username, password=password)
mcp_server = crate_mcp_server(mbbank_client, port=port)
asyncio.run(mbbank_client._authenticate())

Sources: mbbank_mcp/main.py:21-65, README.md:43-52

Summary

Extending MCP tools in this repository requires defining new asynchronous functions within core.py, decorating them with @fast_mcp.tool(), and ensuring they return data structured by the Pydantic models in modals.py. The architecture supports both simple stateless queries (like balance checks) and complex stateful operations (like multi-factor authenticated transfers).