# Bankemes MCP server

> Endpoint, transport, authentication (setup key, OAuth 2.1 with PKCE), tools and limits of the Bankemes Model Context Protocol server.

## Endpoint

- URL: `https://bankemes.kz/mcp` — Streamable HTTP, JSON responses, stateless (no SSE stream, no session id). `POST` only.
- Protocol versions: `2025-06-18`, `2025-03-26`, `2024-11-05`. Methods: `initialize`, `tools/list`, `tools/call`, `ping`.
- Errors of a tool come back as a result with `isError: true` and `{ error: { code, message } }`; results also carry `structuredContent`.

## Authentication

- MCP key (setup key): `Authorization: Bearer bms_agent_…` — created by the customer on the cabinet page “AI agents”, valid 1–30 days, revocable, rotatable and limited by scopes; the owner can view and copy it again after re-entering the password.
- OAuth 2.1 (public clients, PKCE S256): metadata at `https://bankemes.kz/.well-known/oauth-authorization-server` and `https://bankemes.kz/.well-known/oauth-protected-resource/mcp`; dynamic registration `POST https://bankemes.kz/api/oauth/register`; consent page `https://bankemes.kz/oauth/authorize`; token endpoint `POST https://bankemes.kz/api/oauth/token`. Access tokens (`bms_at_…`) live 1 hour; refresh tokens (`bms_rt_…`) rotate on every use, and reuse revokes the connection.
- Setup-key exchange: `grant_type=urn:bankemes:params:oauth:grant-type:setup-key&setup_key=bms_agent_…` at the token endpoint returns an access/refresh pair and retires the key.
- Unauthenticated calls get `401` with `WWW-Authenticate: Bearer resource_metadata="…"`.

## Scopes

- `onboarding:read` — read status, links, guides, customers and schedules (always granted).
- `onboarding:write` — subscription payment links, cashier connection links.
- `integration:write` — resources, Merchant API tokens, webhook, payment links, customer management and schedules. Live credentials and real recurring or bulk invoices need separate owner approval.
- `test:write` — test payments and their simulated outcomes.

## Tools

- `bankemes_get_next_setup_action` (`onboarding:read`) — Start here and call after every step: current state, who acts, the exact URL for the customer, instructions, what to call next.
- `bankemes_get_setup_status` (`onboarding:read`) — All onboarding steps with what is done (same data as the dashboard).
- `bankemes_get_account` (`onboarding:read`) — Account (masked phone), owner flag, trial, this connection’s scopes.
- `bankemes_get_dashboard_link` (`onboarding:read`) — Link to a cabinet section for the customer.
- `bankemes_get_subscription_status` (`onboarding:read`) — Subscription of every cashier, trial, open subscription invoices.
- `bankemes_get_subscription_payment_link` (`onboarding:write`) — Creates or reuses a Bankemes monthly Kaspi remote invoice, sent to the saved billing phone; the customer pays it manually in Kaspi. Returns the subscriptions page for status, not a checkout link.
- `bankemes_list_cashiers` (`onboarding:read`) — Kaspi cashiers with status; no session data.
- `bankemes_get_cashier_status` (`onboarding:read`) — Status of one cashier.
- `bankemes_start_cashier_connection` (`onboarding:write`) — The secure page where the customer connects Kaspi Pay (phone + SMS code entered only there).
- `bankemes_check_cashier_connection` (`onboarding:read`) — Whether the customer finished the Kaspi connection.
- `bankemes_create_resource` (`integration:write`) — Register the application URL bound to a cashier (idempotent by origin).
- `bankemes_list_resources` (`onboarding:read`) — Resources (applications) of the account.
- `bankemes_provision_integration` (`integration:write`) — Test and live Merchant API tokens, delivered once into the project .env. The live token is issued only after the account owner approved the request in the cabinet (status approval_required + approval_url until then).
- `bankemes_configure_webhook` (`integration:write`) — Webhook URL on the application’s domain; the signing secret is delivered once.
- `bankemes_get_integration_guide` (`onboarding:read`) — BANKEMES_INTEGRATION.md for the resource (no secrets).
- `bankemes_get_integration_status` (`onboarding:read`) — Tokens, webhook health, test/live payment counts, what is missing.
- `bankemes_create_test_payment` (`test:write`) — A test payment (livemode=false) that never reaches the bank.
- `bankemes_simulate_test_payment` (`test:write`) — Set a test payment’s outcome: paid / failed / expired / cancelled.
- `bankemes_get_test_payment` (`onboarding:read`) — A test payment with its webhook deliveries.
- `bankemes_verify_test_webhook` (`onboarding:read`) — Whether the application acknowledged the payment.paid webhook of a test payment.
- `bankemes_create_payment_link` (`integration:write`) — Short payment URL: one order or permanent, fixed or customer amount (live or test).
- `bankemes_list_payment_links` (`onboarding:read`) — Payment links with status and paid count.
- `bankemes_list_customers` (`onboarding:read`) — Billing customers with paid total, outstanding and overdue invoices.
- `bankemes_create_customer` (`integration:write`) — Create a billing customer with name, phone and optional contact details; returns a masked phone, never sends an invoice.
- `bankemes_get_customer` (`onboarding:read`) — Read one customer of this account with a masked phone and billing totals.
- `bankemes_update_customer` (`integration:write`) — Update a customer name and optional contact fields; a phone is set only on creation and can later be changed only by the owner in the cabinet. Does not create or pay invoices.
- `bankemes_archive_customer` (`integration:write`) — Archive a customer without deleting financial history. Active or paused recurring schedules must be cancelled first.
- `bankemes_list_recurring_invoices` (`onboarding:read`) — List this account’s recurring invoice schedules, optionally filtered by customer.
- `bankemes_get_recurring_invoice` (`onboarding:read`) — Read one recurring schedule with its parameters and recent invoices; other accounts are inaccessible.
- `bankemes_manage_recurring_invoice` (`integration:write`) — Create / pause / resume / cancel a recurring invoice. Creating one sends real invoices, so it runs only after the owner approved the exact request in the cabinet.
- `bankemes_create_bulk_invoices` (`integration:write`) — Many invoices at once, after the owner approved the exact rows in the cabinet; rejected rows returned; never issued twice.
- `bankemes_get_payment_analytics` (`onboarding:read`) — Methods, cashiers, resources, failure reasons, invoices, link funnel, webhook health for a period.
- `bankemes_diagnose_webhooks` (`onboarding:read`) — Why webhooks fail: endpoint state, dead letters, concrete fixes.
- `bankemes_configure_integration` (`integration:write`) — Connect amoCRM, Bitrix24, Tilda, WooCommerce, OpenCart, n8n, Make, 1C; inbound URL via one-time delivery.
- `bankemes_get_installation_status` (`onboarding:read`) — Whether integrations really work: connections, token use, webhook health, recent payments.
- `bankemes_get_sdk_guide` (`onboarding:read`) — Integration code for node, python, php, laravel, woocommerce, opencart, tilda, amocrm, bitrix24, n8n, make, onec, html.
- `bankemes_verify_sandbox_scenarios` (`onboarding:read`) — Which sandbox scenarios (paid, failed, expired, cancelled + webhook) are proven and what is missing.

## Owner approvals

Live Merchant API credentials (`bankemes_provision_integration` live, including rotation), recurring invoices (`bankemes_manage_recurring_invoice` create) and bulk invoices (`bankemes_create_bulk_invoices`) run only after the account owner approved that exact request in the cabinet. The first call answers `status: "approval_required"` with `approval_id`, `approval_url` and `expires_at` (24 h). After approval the same call with the same arguments runs once; a repeated identical call answers `already_executed`, a rejected one `rejected`. Any changed argument is a new request. `confirm_live` is accepted for compatibility but is not consent.

## What the server never returns

- Kaspi session data, cashier passwords or SMS codes.
- Raw Merchant API tokens or webhook secrets (one-time delivery links only).
- Other accounts’ data: every call is limited to the connected account.

## Limits and audit

Per connection: 300 reads and 60 writes per minute. Every write tool call is recorded in the account’s audit log (visible to the customer in the dashboard); the customer can revoke the agent at any time.

Source: https://bankemes.kz/docs/mcp
