# MCP-сервер Qut Pay: дать ИИ-агенту создавать счета и проверять оплату

> Как подключить @qutpay/mcp к Claude Code, Cursor или Claude Desktop, какие инструменты получает агент, что он не может сделать, и почему начинать нужно с ключа песочницы.

## Коротко

`@qutpay/mcp` — сервер [Model Context Protocol](https://modelcontextprotocol.io) для Qut Pay. После одной команды ИИ-агент получает инструменты: создать счёт Kaspi, прочитать его статус, вернуть деньги, симулировать оплату в песочнице, посмотреть тариф и лимиты. Агент работает через ваш API-ключ и видит только вашу организацию. Начинайте с ключа песочницы (`qp_test_…`).

```bash
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-ключи](https://qut.kz/app/integrations/). Он показывается один раз. Нужен 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` — сервер требует подтверждения, а агент обязан спросить вас.
- Увидеть ключ: сервер читает его из окружения и маскирует похожие строки в ответах.

## Безопасность: какой ключ давать

1. **Песочница** (`qp_test_…`) — пока интеграция не проверена. Деньги не движутся, Kaspi не задействован.
2. **Боевой ключ** — только когда агент помогает с операциями, и только с нужными scope. Без `refunds:write` агент не сможет сделать возврат вообще.
3. Ключ можно отозвать в любой момент в кабинете; лимиты API (200 записей и 600 чтений в минуту) действуют и на агента.

Подробнее о рисках и ограниченных ключах: [Поручить интеграцию ИИ-агенту](/kb/ru/ai-agent-setup), [Чек-лист безопасности](/kb/ru/security-checklist).

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

**Нужен ли 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.