Common Errors and Diagnostics

Relevant source files

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

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

This page outlines the common error scenarios, diagnostic procedures, and validation logic within the MBBank MCP server. It covers authentication failures, transfer session management, and data validation during tool execution.

The server operates by wrapping the mbbank-lib and providing a Model Context Protocol (MCP) interface. Understanding the lifecycle of requests and the specific error states of the bank's asynchronous client is critical for troubleshooting deployment and runtime issues.

Authentication and Startup Diagnostics

The server performs an initial authentication check during the startup sequence. Failure at this stage prevents the server from entering its operational loop, whether in Stdio or SSE mode.

Credential Validation Logic

The application requires username and password to be provided either via command-line arguments or environment variables. If these are missing, the server exits immediately with a diagnostic message to stderr.

Common Initialization Errors

Error Condition	Symptom	Resolution
Missing Credentials	"Username and password must be provided"	Provide --username and --password or set MBBANK_USERNAME and MBBANK_PASSWORD.
Auth Failure	Exception during _authenticate()	Verify credentials and network connectivity to MBBank API.
Python Runtime Error	Environment variables error	Avoid setting credentials in env blocks for certain Python runtimes as noted in documentation.

Sources: README.md:16-18, mbbank_mcp/__main__.py:36-40

Transfer Session Diagnostics

The start_transfer and verify_transfer tools manage a stateful transaction flow. Errors in this flow are primarily related to session expiration or invalid security tokens (OTP).

Transfer State Lifecycle

Transfer sessions are stored in an in-memory transfer_manager. Each session is assigned a unique 8-character hex Session ID (SID) and has a hard-coded expiration of 120 seconds.

Diagnostic Error Messages

The server returns specific strings when a transfer cannot be completed:

• Invalid SID: "The transfer session has expired or is invalid. Please start a new transfer."
• Expired Session: "The transfer session has expired. Please start a new transfer."
• API/Logic Failure: "Transfer failed: {error_message}"

Sources: mbbank_mcp/core.py:92-105

Data Integrity and Validation

Data returned from the MBBank API is validated and transformed into local Pydantic models. Diagnostics here often involve identifying missing or incorrectly formatted data from the upstream bank response.

Model Transformation

The server uses modals.py to define the expected structure for various banking entities. If the upstream API response does not match these schemas, Pydantic validation errors may occur.

Model	Key Fields	Purpose
AccountModel	accountNumber, balance	Ensures balance data is present.
TransactionModel	transactionId, amount	Validates historical transaction records.
SavingDetailsModel	detailSaving, error	Specifically includes an error field for diagnostic feedback.

Sources: mbbank_mcp/modals.py:7-111

Tool-Specific Validation

• Date Formatting: Tools like get_transactions and get_card_transactions expect dates in dd-mm-yyyy format. Providing a different format will trigger a strptime ValueError.
• Card Activation: The get_cards tool filters out cards with a status of "New Card" to prevent diagnostics related to unactivated hardware.

Sources: mbbank_mcp/core.py:141-143, mbbank_mcp/core.py:183

Summary

Diagnostics in the MBBank MCP server are handled through a combination of early-exit credential checks, explicit error strings for stateful transfer operations, and structured Pydantic models for data validation. Developers should prioritize checking the stderr output (via eprint) for authentication issues and session timeouts for transfer failures.

Sources: mbbank_mcp/__main__.py:20-24, mbbank_mcp/core.py:105