MCP server and SKILL.md: Qut Pay for AI agents

Two ways to let an AI agent (Claude Code, Cursor, Windsurf, Claude Desktop, VS Code Copilot, ChatGPT) work with Qut Pay without pasting documentation by hand:

What	For	Where
SKILL.md	An agent skill: a short "how to add Kaspi payments through Qut Pay" procedure with links to the details. The agent reads it on its own when the task is about payments	https://api.qut.kz/SKILL.md
MCP server `@qutpay/mcp`	Tools for the agent: create an invoice, check status, refund, simulate a payment in sandbox — through your API key	`npx -y @qutpay/mcp`

Neither replaces the code on your site: in production your server creates the invoice and the confirmation arrives by webhook. MCP lets the agent verify the integration and help with operations; SKILL.md lets it write the integration correctly.

1. SKILL.md

Format: Agent Skills — a qutpay/ folder with SKILL.md (frontmatter name, description + the procedure) and references/ (webhook signature verification for Node/PHP/Python, error codes and limits).

Install into Claude Code (the skill is picked up automatically when a task is about Kaspi payments):

mkdir -p .claude/skills/qutpay/references
curl -sSL https://api.qut.kz/SKILL.md -o .claude/skills/qutpay/SKILL.md
curl -sSL https://api.qut.kz/skill/references/webhook-verify.md -o .claude/skills/qutpay/references/webhook-verify.md
curl -sSL https://api.qut.kz/skill/references/errors.md -o .claude/skills/qutpay/references/errors.md

The ready-made folder also lives in the public repository: skills/qutpay/ in https://github.com/kazprose/qutpay-docs. In Claude.ai upload the folder as a zip (Settings → Capabilities → Skills).

Without installing: give the agent the link https://api.qut.kz/SKILL.md — it reads it like any page. The cabinet (Integrations → "AI agent") copies a version with your organization's name and current mode filled in.

Inside: the three integration steps (invoice → payUrl → signed webhook → confirmation on the success page), the sandbox verification loop, what not to do (keys in chat, "paid" from a redirect, invented endpoints, marketing claims on Kaspi's behalf), and a hand-over checklist for you.

2. MCP server

Install

You need an API key: cabinet → Integrations → API keys → Create. Start with a sandbox key (qp_test_…) — no money moves, payments are simulated.

Claude Code:

claude mcp add qutpay -e QUTPAY_API_KEY=qp_test_… -- npx -y @qutpay/mcp

Cursor (.cursor/mcp.json), Windsurf, Claude Desktop (claude_desktop_config.json), VS Code (.vscode/mcp.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; qp_…/whsec_…-looking strings in tool output are masked. Node.js 18+ required. If the npm package is unreachable, download https://api.qut.kz/downloads/qutpay-mcp.zip, unpack it and use "command": "node", "args": ["<folder>/bin/qutpay-mcp.js"].

Tools

Tool	What it does
`qutpay_account`	Organization, mode (sandbox/live), tariff and limits, cashiers, provider status. The agent calls it first
`qutpay_create_invoice`	Create an invoice (QR, or `kind: "phone"` — pushed into the customer's Kaspi.kz app). Returns `payUrl`, `qrImageUrl`, `deepLink`, `expiresAt`. Always with an `idempotencyKey` per order
`qutpay_get_invoice`	Invoice status; `live: true` asks Kaspi right now
`qutpay_list_invoices`	List: status, `externalOrderId`, period, up to 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. Refuses with a live key
`qutpay_list_subscriptions`, `qutpay_get_subscription`	Read recurring schedules (scope `subscriptions:manage`)

Resources (read by the agent as documents): qutpay://skill, qutpay://docs/integration, qutpay://docs/webhook-verify, qutpay://docs/errors, qutpay://docs/openapi. Prompts: integrate-checkout — step-by-step integration task, verify-sandbox — sandbox loop check.

Deliberately not in MCP: creating API keys and webhooks. You create them in the cabinet; the agent asks you to put them into .env.

A typical session

"Add Kaspi payments to my store" → the agent reads qutpay://skill, calls qutpay_account (sandbox), writes the code.
The agent creates a test invoice with qutpay_create_invoice, simulates the payment with qutpay_simulate_payment, checks that your webhook fired, and shows the result.
You switch the organization to live and replace the key with qp_live_…. For operations ("how many payments today", "refund 500 ₸ on order 1001") the agent uses qutpay_list_invoices and qutpay_refund_invoice — a refund only after your explicit confirmation.

Security

Give the agent a sandbox key until the integration is verified. A live key only with limited scopes (without refunds:write unless refunds are needed) and only in an environment you trust.
The key is bound to one organization: the agent sees only its invoices.
Limits are the API's (200 writes and 600 reads per minute per key, the tariff's invoice limit).
Revoke the key any time: cabinet → Integrations → API keys.

FAQ

Do I need this if I am not a developer? No. WooCommerce, OpenCart and Tilda have ready modules. MCP and SKILL.md are for people who connect Qut Pay through an AI agent or give an agent access to operations.

Can the agent charge a customer? No. The customer pays the invoice in Kaspi.kz themselves. The agent only creates invoices and reads their status; a refund with a live key requires confirmation.

Does it work with ChatGPT? Yes, in developer mode (connectors / MCP). Without MCP, give ChatGPT the link https://api.qut.kz/for-ai.

Where is the source? https://github.com/kazprose/qutpay-docs (folder examples/mcp, MIT). Package: @qutpay/mcp on npm.

Need help? WhatsApp +77788813333 · kazprose@gmail.com · 09:00–21:00 (Алматы)
You can also write from the dashboard: Support.

Qut Pay is an independent service, not affiliated with Kaspi Bank JSC. Kaspi and Kaspi Pay are trademarks of their owner.