Read-Only Design Principles

Relevant source files

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

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

The MBBank MCP server is primarily designed as a monitoring and analytics tool for MB Bank accounts. The core philosophy centers on providing secure, read-only access to sensitive financial data such as account balances, transaction histories, card details, and savings information. While the server includes a mechanism for initiating transfers, this action is strictly gated behind external multi-factor authentication (D-OTP) and QR code verification, ensuring that the MCP server itself does not possess autonomous authority to move funds.

Sources: README.md:47-51, mbbank_mcp/core.py:32-108

Data Retrieval Architecture

The system utilizes a structured data model to abstract raw API responses into developer-friendly objects. This architecture ensures that data consumed by the Model Context Protocol (MCP) client is consistent and sanitized.

Information Flow for Monitoring

The following diagram illustrates how the server fetches and transforms data for read-only tools like get_balances and get_transactions.

The server implements several tools dedicated to data observation:

• get_balances: Retrieves current balances for standard and international accounts.
• get_transactions: Fetches historical transaction data for a specific account.
• get_cards: Lists all associated cards and their statuses.
• get_savings: Provides overview of Online Savings Accounts (OSA) and Branch Saving Accounts (SBA).

Sources: mbbank_mcp/core.py:118-223, mbbank_mcp/modals.py:1-85

Security Controls and Limitations

The project explicitly defines its scope to prevent unauthorized financial actions. It is marketed as a tool for "monitoring and analytics transactions and balances" rather than a transactional banking client.

Read-Only Constraints

Feature	Supported	Description
Balance Checking	Yes	Views currentBalance and ccyCd for all accounts.
Transaction History	Yes	Views description, amount, and transferredTo details.
Savings Details	Yes	Views interestRate, maturityDate, and principalAmount.
Automated Transfers	No	Requires manual QR scan and D-OTP via the official MBBank mobile app.
Withdrawal	No	The MCP server provides no interface for money withdrawal.

Sources: README.md:47-51, mbbank_mcp/core.py:118-245

The Transfer Safeguard (Out-of-Band Verification)

Even though a start_transfer tool exists, it adheres to secure design principles by offloading the actual authorization to the user's physical device. The MCP server generates a session and a QR code but cannot complete the transaction without an OTP generated by the MBBank app's "Xác Thực D-OTP" feature.

Implementation of Data Models

Data models defined in modals.py serve as a proxy layer, renaming raw API fields to more descriptive, standardized names for the MCP environment. This ensures that the sensitive data returned is structured and type-safe.

Key Read-Only Data Structures

• AccountModel: Tracks accountNumber, accountName, currency, and balance.
• TransactionModel: Includes transactionDate, amount (prefixed with +/-), and transferredTo details.
• SavingModel: Details savings information including ratePercentPerYear and maturityInstructions.

Sources: mbbank_mcp/modals.py:5-85, mbbank_mcp/core.py:123-134

Execution and Authentication

The server requires explicit credentials (MBBANK_USERNAME and MBBANK_PASSWORD) to initialize the MBBankAsync client. Authentication is verified at startup before the server begins listening for requests, ensuring that only valid sessions are exposed via Stdio or SSE modes.

# mbbank_mcp/__main__.py:36-41
mbbank_client = MBBankAsync(
    username=username,
    password=password
)
mcp_server = crate_mcp_server(mbbank_client, port=port)
# check if the client is valid
asyncio.run(mbbank_client._authenticate())

Sources: mbbank_mcp/main.py:36-42, README.md:16-41

Conclusion

The Read-Only Design Principles of the MBBank MCP server prioritize user safety by focusing on information retrieval and analytics. By enforcing out-of-band multi-factor authentication for sensitive operations and providing structured models for data observation, the server functions as a secure bridge for financial monitoring without introducing risks of automated or unauthorized fund movement.