Bank API Integration

Bank API Integration (MCP)

This is the central routing hub for all bank API operations. Two Ukrainian banks are supported via MCP (Model Context Protocol) servers — each with its own data formats, rate limits, and quirks.

Which Skill to Use? (Decision Tree)

Before diving into API calls, pick the right skill for the job. This skill covers core account and transaction operations. Specialized domains have dedicated skills because their APIs, workflows, and error handling differ significantly from basic data fetching.

If the user's request spans multiple skills, start here to fetch the raw data, then hand off to the specialized skill for processing.

Supported Banks

MCP Configuration

Banks are configured in .mcp.json at the plugin root:

{
  "mcpServers": {
    "monobank": {
      "type": "http",
      "url": "https://your-mcp-server.example.com/mcp/monobank"
    },
    "privatbank": {
      "type": "http",
      "url": "https://your-mcp-server.example.com/mcp/privatbank"
    }
  }
}

Users replace placeholder URLs with their actual MCP server endpoints.

Tool Discovery

Discover available tools at runtime before executing any bank operation. Tool names vary by MCP server implementation, so hardcoding names would break when servers update their APIs.

1. List all available tools matching the bank's prefix pattern
2. Identify tool names by action suffix (e.g., get_balance, get_statements)
3. Check tool parameter schemas before calling — parameter names and types differ between banks

Available tools might look like:
  mcp__monobank__get_client_info
  mcp__monobank__get_accounts
  mcp__monobank__get_statement
  mcp__monobank__get_currency_rates

  mcp__privatbank__get_balance
  mcp__privatbank__get_statements
  mcp__privatbank__get_card_info

Bank-Specific API Details

Each bank has a detailed reference document. Read these when working with that bank's API — they contain exact field names, parameter formats, and edge cases.

Monobank

Accounts use id, currencyCode (980=UAH), balance in kopiykas, iban. Statements use Unix timestamps, max 31 days per request, 1 req/60s rate limit. For full API details, read references/monobank-api.md.

PrivatBank

Multiple balance types (historical, interim, final). Dates in DD-MM-YYYY format, amounts as decimal strings (not kopiykas). Cursor-based pagination via followId. For full API details, read references/privatbank-api.md.

Amount Formatting

Banks return amounts in different formats because they evolved independently — Monobank uses integer kopiykas (common in fintech APIs for precision), while PrivatBank uses decimal strings (legacy banking convention). Mixing them up produces 100x errors, so always check the tool schema.

// Monobank: amount is in KOPIYKAS (integer)
const amountUAH = monoAmount / 100;  // 1523400 → 15234.00

// PrivatBank: amount is a DECIMAL STRING
const amountUAH = parseFloat(privatAmount);  // "15234.50" → 15234.50

// Display format: ₴15 234,00
function formatUAH(amount) {
  return '₴' + amount.toLocaleString('uk-UA', {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
  });
}

Date Format Differences

Different banks, different eras of API design. Convert dates before calling — passing the wrong format silently returns empty results rather than an error.

Rate Limits

Rate limits exist because bank APIs protect against abuse and infrastructure overload. Monobank is especially strict on statement endpoints — violating the limit returns 429 and temporarily blocks the token.

Error Handling

Retry with exponential backoff for transient errors (429, timeout). Non-transient errors (403, connection refused) need user intervention — retrying won't help.

async function mcpCallWithRetry(toolCall, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await toolCall();
    } catch (error) {
      if (error.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
}

Multi-Bank Sync Strategy

Users typically have accounts at both banks and expect a unified view. Fetch in parallel where possible, but respect per-bank rate limits. Emit events progressively so the user sees results as they arrive rather than waiting for everything to finish.

1. Fetch Monobank and PrivatBank accounts in parallel
2. For statements: respect Monobank's 60s rate limit per account
3. Emit balance_updated events as each account completes
4. Emit transaction_added events in batches of 50
5. Emit sync_complete only after all banks finish
6. Track failed banks separately — one bank failing should not block sync for the other

Pagination Differences

Currency Codes (ISO 4217)

Bank MCP tools return numeric ISO 4217 codes. Map to symbols for user-facing display.

Input/Output Example

User says: "Покажи мій баланс по всіх банках"

What happens:

1. Discover available MCP tools for both banks
2. Call balance endpoints in parallel (Monobank + PrivatBank)
3. Convert Monobank kopiykas to UAH, parse PrivatBank decimal strings
4. Present unified view:

Monobank — Чорна картка ****1234:  ₴15 234,00
Monobank — Біла картка ****5678:   ₴3 100,50
PrivatBank — ФОП ****9012:          ₴48 920,33
─────────────────────────────────────────────
Загалом:                            ₴67 254,83