Коротко
@qutpay/mcp — сервер Model Context Protocol для Qut Pay. После одной команды ИИ-агент получает инструменты: создать счёт Kaspi, прочитать его статус, вернуть деньги, симулировать оплату в песочнице, посмотреть тариф и лимиты. Агент работает через ваш API-ключ и видит только вашу организацию. Начинайте с ключа песочницы (qp_test_…).
claude mcp add qutpay -e QUTPAY_API_KEY=qp_test_… -- npx -y @qutpay/mcpПолное руководство: https://api.qut.kz/docs/guide/mcp. Навык для агента (инструкция по интеграции): https://api.qut.kz/SKILL.md.
Установка
| Клиент | Как |
|---|---|
| Claude Code | команда выше; ключ передаётся через -e, в конфиг он попадает как переменная окружения |
| Cursor, Windsurf, VS Code, Claude Desktop | в файл mcp.json / claude_desktop_config.json: "qutpay": { "command": "npx", "args": ["-y", "@qutpay/mcp"], "env": { "QUTPAY_API_KEY": "qp_test_…" } } |
| ChatGPT | режим разработчика → коннектор MCP; без него дайте ссылку https://api.qut.kz/for-ai |
| Без npm | скачайте https://api.qut.kz/downloads/qutpay-mcp.zip и запускайте node bin/qutpay-mcp.js |
Ключ создаётся в кабинете: Интеграции → API-ключи. Он показывается один раз. Нужен Node.js 18 или новее.
Что умеет агент
| Инструмент | Действие |
|---|---|
qutpay_account | режим организации (sandbox/live), тариф, лимиты, кассиры |
qutpay_create_invoice | создать счёт: сумма, описание, номер заказа, kind: "phone" для счёта в приложение покупателя; возвращает payUrl и QR |
qutpay_get_invoice, qutpay_list_invoices | статус одного счёта или список по фильтрам |
qutpay_cancel_invoice | закрыть открытый счёт |
qutpay_refund_invoice | возврат, полный или частичный; нужен scope refunds:write |
qutpay_simulate_payment | только песочница: пометить счёт оплаченным, вебхук уйдёт по-настоящему |
qutpay_list_subscriptions, qutpay_get_subscription | чтение подписок |
Кроме инструментов агент получает документы (qutpay://skill, qutpay://docs/integration, qutpay://docs/errors) и две готовые задачи: integrate-checkout (подключить оплату к проекту) и verify-sandbox (прогнать цикл счёт → оплата → вебхук).
Что агент сделать не может
- Создать API-ключ или вебхук — это делаете вы в кабинете.
- Списать деньги с покупателя — счёт всегда оплачивает покупатель сам в Kaspi.kz.
- Симулировать оплату с боевым ключом — инструмент откажет.
- Сделать возврат с боевым ключом без явного
confirm: true— сервер требует подтверждения, а агент обязан спросить вас. - Увидеть ключ: сервер читает его из окружения и маскирует похожие строки в ответах.
Безопасность: какой ключ давать
- Песочница (
qp_test_…) — пока интеграция не проверена. Деньги не движутся, Kaspi не задействован. - Боевой ключ — только когда агент помогает с операциями, и только с нужными scope. Без
refunds:writeагент не сможет сделать возврат вообще. - Ключ можно отозвать в любой момент в кабинете; лимиты API (200 записей и 600 чтений в минуту) действуют и на агента.
Подробнее о рисках и ограниченных ключах: Поручить интеграцию ИИ-агенту, Чек-лист безопасности.
Вопросы и ответы
Нужен ли MCP, чтобы агент написал интеграцию? Нет. Для написания кода достаточно https://api.qut.kz/SKILL.md или https://api.qut.kz/for-ai. MCP нужен, чтобы агент мог проверить результат без ваших рук и помогать с операциями.
Агент создал счёт в песочнице — покупатель его увидит? Нет. Счета песочницы существуют только в Qut Pay; оплата симулируется инструментом или кнопкой на странице оплаты.
Можно ли подключить одного агента к нескольким магазинам? Да: по одному MCP-серверу на организацию с её ключом, например qutpay-shop1, qutpay-shop2.
Где исходный код? В открытом репозитории https://github.com/kazprose/qutpay-docs, папка examples/mcp, лицензия MIT.