Kiddie22/bm-mcp

NestJS Banking MCP Server

A Model Context Protocol (MCP) server that provides banking functionality through a NestJS backend API with personal access token authentication and support for multiple currencies.

Features

• Secure Authentication: Personal access tokens ensure users can only access their own accounts
• Multi-Currency Support: View balances and transfer funds between any supported currencies (AUD, USD, JPY, and more)
• Dynamic FX Rate Management: Real-time exchange rates for any currency pair with conditional transfers
• Agentic Pre-condition Checking: Automatic validation of transfer eligibility
• User Elicitation: Interactive prompts for missing information
• Complete Data Privacy: All user data requires authentication - nothing is publicly accessible

Security Model

This banking system implements a secure authentication model where:

• Each user has a unique personal access token
• Users can only view and modify their own accounts
• All user data requires authentication - no public access
• Exchange rates are publicly accessible for any currency pair
• Access token is configured in environment variables
• Backend automatically identifies users by token

Available Users

The system comes with two demo users with hard-coded access tokens:

• Alice - Access Token: alice_token_12345
• Bob - Access Token: bob_token_67890

Environment Configuration

Create a .env file in the root directory with the following variables:

BASE_URL=http://localhost:3000
ACCESS_TOKEN=alice_token_12345

To switch between users, simply change the ACCESS_TOKEN value in your .env file.

API Endpoints

Public Endpoints (No Authentication Required)

• GET /fx?from={currency}&to={currency} - Get current exchange rate for any currency pair
• PUT /fx - Update exchange rate for a currency pair

Authenticated Endpoints (Require Bearer Token)

• GET /me - Get your own account information
• POST /transfer - Transfer funds between your accounts

MCP Tools

Public Tools

• get-fx-rate - Get current exchange rate between any two currencies
• get-access-token-info - Get information about the current access token

Authenticated Tools

• get-my-balance - View your own account balances
• check-transfer-eligibility - Verify transfer conditions
• transfer-funds - Transfer funds between your accounts

MCP Resources

• fx-rate - Exchange rate data as a resource

Usage Example

1. Check your balance:

   Use tool: get-my-balance
   

2. Get FX rate for any pair:

   Use tool: get-fx-rate with fromCurrency: "AUD", toCurrency: "JPY"
   

3. Transfer funds:

   Use tool: transfer-funds with amount: 100, fromCurrency: "AUD", toCurrency: "USD", fxRateCondition: {operator: "above", value: 0.65}
   

4. Get token information:

   Use tool: get-access-token-info
   

Supported Currencies

The system supports multiple currencies with configurable exchange rates:

• AUD (Australian Dollar)
• USD (US Dollar)
• JPY (Japanese Yen)
• And more - easily extensible for additional currencies

Exchange rates are stored as currency pairs (e.g., AUDUSD, AUDJPY) and can be updated via the API.

Setup

1. Install dependencies:

   npm install
   cd server && npm install
   

2. Create .env file with your configuration:

   cp .env.example .env
   # Edit .env with your preferred access token
   

3. Start the NestJS server:

   cd server
   npm run start:dev
   

4. Start the MCP server:

   npm start
   

Environment Variables

• BASE_URL - NestJS API base URL (default: http://localhost:3000)
• ACCESS_TOKEN - Your access token (default: alice_token_12345)

Switching Between Users

To switch between users, simply update your .env file:

# To use Alice's account
ACCESS_TOKEN=alice_token_12345

# To use Bob's account
ACCESS_TOKEN=bob_token_67890

Then restart the MCP server for the changes to take effect.

Adding New Currencies

To add support for new currencies:

1. Update the backend fxRates mapping in server/src/app.service.ts
2. Add demo accounts for the new currency in the users array
3. The MCP tools will automatically support the new currency

Example:

let fxRates: Record<string, number> = {
  AUDUSD: 0.68,
  USDAUD: 1 / 0.68,
  AUDJPY: 100,
  JPYAUD: 1 / 100,
  EURUSD: 1.08, // New currency
  USDEUR: 1 / 1.08,
};

Security Notes

• This is a mock system using hard-coded access tokens for demonstration
• Access token is configured in environment variables for security
• No token input required in tools - authentication is automatic
• Backend automatically identifies users by matching tokens
• In production, implement proper token generation, storage, and expiration
• Consider adding rate limiting and additional security measures
• All user data is completely private and requires authentication