MCP-сервер и SKILL.md: Qut Pay для ИИ-агентов

Два способа дать ИИ-агенту (Claude Code, Cursor, Windsurf, Claude Desktop, VS Code Copilot, ChatGPT) работать с Qut Pay без ручного копирования документации:

Что	Для чего	Адрес
SKILL.md	Навык агента: короткая инструкция «как подключить Kaspi через Qut Pay» со ссылками на детали. Агент читает её сам, когда задача про оплату	https://api.qut.kz/SKILL.md
MCP-сервер `@qutpay/mcp`	Инструменты агента: создать счёт, проверить статус, вернуть деньги, симулировать оплату в песочнице — через ваш API-ключ	`npx -y @qutpay/mcp`

Оба не заменяют ваш код на сайте: счёт в продакшене создаёт ваш сервер, подтверждение приходит вебхуком. MCP нужен агенту, чтобы проверить интеграцию и помогать с операциями; SKILL.md — чтобы написать её правильно.

1. SKILL.md

Формат Agent Skills: папка qutpay/ с файлом SKILL.md (frontmatter name, description + инструкция) и папкой references/ (проверка подписи вебхука на Node/PHP/Python, коды ошибок и лимиты).

Установка в Claude Code (навык подхватывается автоматически, когда задача про оплату Kaspi):

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

Готовая папка есть и в открытом репозитории: skills/qutpay/ в https://github.com/kazprose/qutpay-docs. В Claude.ai навык загружается как zip этой папки (Settings → Capabilities → Skills).

Без установки: дайте агенту ссылку https://api.qut.kz/SKILL.md — он прочитает её как обычную страницу. Из кабинета (Интеграции → «ИИ-агент») копируется версия с названием вашей организации и текущим режимом.

Что внутри: три шага интеграции (счёт → payUrl → подписанный вебхук → подтверждение на странице успеха), цикл проверки в песочнице, чего делать нельзя (ключ в чате, «оплачено» по редиректу, выдуманные эндпоинты, маркетинговые обещания от имени Kaspi), чек-лист для передачи вам.

2. MCP-сервер

Установка

Нужен API-ключ: кабинет → Интеграции → API-ключи → Создать. Начните с ключа песочницы (qp_test_…) — деньги не движутся, оплата симулируется.

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_…" }
    }
  }
}

Ключ читается только из переменной окружения и никогда не печатается сервером; в ответах инструментов строки вида qp_…/whsec_… маскируются. Нужен Node.js 18+. Если npm-пакет недоступен, скачайте https://api.qut.kz/downloads/qutpay-mcp.zip, распакуйте и укажите "command": "node", "args": ["<папка>/bin/qutpay-mcp.js"].

Инструменты

Инструмент	Что делает
`qutpay_account`	Организация, режим (sandbox/live), тариф и лимиты, кассиры, статус провайдера. Агент вызывает первым
`qutpay_create_invoice`	Создать счёт (QR или `kind: "phone"` — счёт в приложение Kaspi.kz покупателя). Возвращает `payUrl`, `qrImageUrl`, `deepLink`, `expiresAt`. Всегда с `idempotencyKey` на заказ
`qutpay_get_invoice`	Статус счёта; `live: true` — спросить Kaspi прямо сейчас
`qutpay_list_invoices`	Список: статус, `externalOrderId`, период, до 50 штук
`qutpay_cancel_invoice`	Закрыть открытый счёт
`qutpay_refund_invoice`	Полный или частичный возврат (scope `refunds:write`). С боевым ключом требует `confirm: true`
`qutpay_simulate_payment`	Только песочница: пометить счёт как paid / failed / expired; вебхуки уходят по-настоящему. С боевым ключом отказывает
`qutpay_list_subscriptions`, `qutpay_get_subscription`	Чтение подписок (scope `subscriptions:manage`)

Ресурсы (агент читает как документы): qutpay://skill, qutpay://docs/integration, qutpay://docs/webhook-verify, qutpay://docs/errors, qutpay://docs/openapi. Подсказки (prompts): integrate-checkout — пошаговая задача на интеграцию, verify-sandbox — проверка цикла в песочнице.

Чего в MCP нет намеренно: создания API-ключей и вебхуков. Их создаёте вы в кабинете; агент попросит вставить их в .env.

Типичная сессия

«Подключи оплату Kaspi к моему магазину» → агент читает qutpay://skill, вызывает qutpay_account (песочница), пишет код.
Агент создаёт тестовый счёт qutpay_create_invoice, симулирует оплату qutpay_simulate_payment, проверяет, что ваш вебхук сработал, и показывает результат.
Вы переключаете организацию в live и меняете ключ на qp_live_…. Для операций («сколько оплат за сегодня», «верни 500 ₸ по заказу 1001») агент использует qutpay_list_invoices и qutpay_refund_invoice — возврат только после вашего явного подтверждения.

Безопасность

Давайте агенту ключ песочницы, пока интеграция не проверена. Боевой ключ — только с ограниченными scope (без refunds:write, если возвраты не нужны) и только в среде, которой вы доверяете.
Ключ привязывается к организации: агент видит счета только этой организации.
Лимиты — те же, что у API (200 записей и 600 чтений в минуту на ключ, лимит тарифа по счетам).
Отозвать ключ можно в любой момент: кабинет → Интеграции → API-ключи.

Вопросы и ответы

Это нужно, если я не разработчик? Нет. Для WooCommerce, OpenCart, Tilda есть готовые модули. MCP и SKILL.md — для тех, кто подключает Qut Pay через ИИ-агента или даёт агенту доступ к операциям.

Агент может списать деньги у покупателя? Нет. Счёт оплачивает покупатель сам в Kaspi.kz. Агент только создаёт счета и читает их статус; возврат с боевым ключом требует подтверждения.

Работает ли с ChatGPT? Да, в режиме разработчика (connectors / MCP). Без MCP дайте ChatGPT ссылку https://api.qut.kz/for-ai.

Где исходный код? https://github.com/kazprose/qutpay-docs (папка examples/mcp, MIT). Пакет: @qutpay/mcp в npm.

Нужна помощь? WhatsApp +77788813333 · kazprose@gmail.com · 09:00–21:00 (Алматы)
Можно написать и из кабинета: Поддержка.

Qut Pay — независимый сервис, не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки правообладателя.