@qutpay/mcp β Qut Pay MCP server
Model Context Protocol server for Qut Pay: lets an AI agent (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, ChatGPT developer modeβ¦) create Kaspi QR invoices, read their status, refund, and test the whole flow in sandbox through the Qut Pay API. Kazakhstan only, KZT only. Qut Pay is an independent service, not affiliated with Kaspi Bank.
Install
You need an API key from the Qut Pay cabinet (https://qut.kz/app β Integrations β API keys). Start with a sandbox key (qp_test_β¦) β no real money moves, payments are simulated.
Claude Code:
claude mcp add qutpay -e QUTPAY_API_KEY=qp_test_β¦ -- npx -y @qutpay/mcp
Cursor one-click: Add to Cursor (then set your key). Cursor / Windsurf / Claude Desktop / VS Code (mcp.json, claude_desktop_config.json):
{
"mcpServers": {
"qutpay": {
"command": "npx",
"args": ["-y", "@qutpay/mcp"],
"env": { "QUTPAY_API_KEY": "qp_test_β¦" }
}
}
}
The key is read only from the environment and is never printed by the server. Optional QUTPAY_BASE_URL (default https://api.qut.kz).
Remote (hosted) endpoint
No install: https://api.qut.kz/mcp (Streamable HTTP), key in Authorization: Bearer qp_β¦. Claude Code: claude mcp add --transport http qutpay https://api.qut.kz/mcp --header "Authorization: Bearer qp_test_β¦"; Cursor/VS Code mcp.json: { "url": "https://api.qut.kz/mcp", "headers": { "Authorization": "Bearer qp_test_β¦" } }. Without a key the endpoint lists tools and serves docs; tool calls answer unauthorized.
| Tool | What it does |
|---|
qutpay_account | Organization, mode (sandbox/live), tariff and limits, cashiers, provider status β call first |
qutpay_create_invoice | Create an invoice (QR, or pushed to the customer's Kaspi.kz app with kind: "phone"); returns payUrl, qrImageUrl, deepLink, expiresAt. Pass idempotencyKey per order |
qutpay_get_invoice | Status of one invoice (live: true asks Kaspi right now) |
qutpay_list_invoices | List with filters: status, externalOrderId, from/to, limit β€ 50 |
qutpay_cancel_invoice | Close an open invoice |
qutpay_refund_invoice | Full or partial refund (scope refunds:write); with a live key requires confirm: true |
qutpay_simulate_payment | Sandbox only: mark an invoice paid / failed / expired, webhooks are delivered for real |
qutpay_list_subscriptions, qutpay_get_subscription | Read recurring invoice schedules (scope subscriptions:manage) |
Resources: qutpay://skill (agent skill β the integration procedure), qutpay://docs/integration, qutpay://docs/webhook-verify, qutpay://docs/errors, qutpay://docs/openapi. Prompts: integrate-checkout (stack), verify-sandbox (amount).
API keys and webhook endpoints are deliberately not manageable from the MCP server: the merchant creates them in the cabinet, and the agent asks for them.
Typical session
qutpay_account β mode is sandbox.
qutpay_create_invoice { amount: 100, externalOrderId: "test-1", idempotencyKey: "test-1" } β payUrl.
qutpay_simulate_payment { id } β paid; the merchant's webhook receives invoice.paid.
qutpay_get_invoice { id } β paid.
Docs
MIT.