Credential Management
Relevant source files
The following files were used as context for generating this wiki page:
Credential Management in the MBBank MCP server facilitates the secure handling and application of user authentication data required to interact with the Military Commercial Joint Stock Bank (MB Bank) API. The system focuses on obtaining user credentials (username and password) through various interfaces—CLI arguments, environment variables, or configuration files—and utilizing them to establish an authenticated session via the mbbank-lib underlying library.
The scope of this module includes initial credential ingestion, the authentication lifecycle during server startup, and the management of sensitive session-related data such as OTP codes for transactional operations.
Credential Ingestion and Storage
The server supports multiple methods for providing credentials. These are processed during the initialization of the application to ensure that the MBBankAsync client has the necessary data to perform authentication.
Configuration Methods
Credentials can be provided through three primary channels:
- Command Line Arguments: Using the
--usernameand--passwordflags. - Environment Variables: Setting
MBBANK_USERNAMEandMBBANK_PASSWORD. - JSON Configuration: Used when deploying via Claude Desktop or Docker, where environment variables or arguments are defined in a configuration schema.
Sources: mbbank_mcp/main.py:26-38, README.md:15-53
| Method | Source Parameter / Variable | Description |
|---|---|---|
| CLI Flag | --username | Direct username input via terminal. |
| CLI Flag | --password | Direct password input via terminal. |
| Env Var | MBBANK_USERNAME | Environment variable fallback for username. |
| Env Var | MBBANK_PASSWORD | Environment variable fallback for password. |
Authentication Logic Flow
Upon startup, the server validates the presence of credentials and attempts to authenticate with the MB Bank backend.
The diagram shows how the system prioritizes CLI arguments over environment variables before attempting to initialize the MBBankAsync client.
Sources: mbbank_mcp/main.py:31-48
Session and Transaction Security
Beyond initial login, the system manages "soft" credentials and stateful session identifiers for sensitive operations like money transfers.
OTP and Session IDs (SID)
For transfers, the system does not store permanent credentials for the transaction but generates a temporary sid (Session ID). This ID is mapped to a TransferContextAsync object and an expiration timer.
- SID Generation: Uses
os.urandom(4).hex()to create a unique 8-character identifier to prevent collisions. - Expiration: Transfer sessions are strictly limited to 120 seconds.
- Verification: Requires a One-Time Password (OTP) generated by the user's MB Bank app via a QR code scan.
Sources: mbbank_mcp/core.py:53-112
Transfer State Management
The transfer_manager dictionary serves as a volatile store for active transfer sessions.
The sequence diagram illustrates the lifecycle of a credentialed transaction, highlighting the requirement for user-provided OTPs to complete the authentication loop.
Sources: mbbank_mcp/core.py:34-112
Implementation Details
The implementation relies on MBBankAsync from the mbbank-lib dependency to handle the actual transmission of credentials.
Authentication Initialization
In the main entry point, the client is explicitly authenticated before the MCP server starts listening for requests. This ensures that invalid credentials result in an immediate failure rather than runtime errors during tool execution.
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())
eprint("Authenticated successfully.")
Sources: mbbank_mcp/main.py:39-48
Dependency and Runtime Requirements
Credential management is influenced by the project's runtime configuration, specifically the requirement for Python 3.10+ and the use of the mbbank-lib and qrcode packages for secure session handling.
Sources: pyproject.toml:11-20, README.md:5-7
Conclusion
Credential management in the MBBank MCP server is designed around a "fail-fast" startup mechanism that validates primary credentials (username/password) via CLI or environment variables. Secondary credentials, such as transaction OTPs, are handled through a time-limited state management system that ensures sensitive operations are verified through the official MB Bank mobile application via QR codes and ephemeral session IDs.