# Qut Pay MCP сервері: ЖИ-агентке счёт құрып, төлемді тексеруге рұқсат беру

> @qutpay/mcp-ті Claude Code, Cursor немесе Claude Desktop-қа қалай қосу, агент қандай құралдар алады, не істей алмайды және неге sandbox кілтінен бастау керек.

## Қысқаша

`@qutpay/mcp` — Qut Pay үшін [Model Context Protocol](https://modelcontextprotocol.io) сервері. Бір командадан кейін ЖИ-агент құралдар алады: Kaspi счётын құру, күйін оқу, ақша қайтару, sandbox-та төлемді имитациялау, тариф пен шектерді көру. Агент сіздің API кілтіңізбен жұмыс істейді және тек сіздің ұйымыңызды көреді. Sandbox кілтінен (`qp_test_…`) бастаңыз.

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

Толық нұсқаулық: https://api.qut.kz/docs/guide/kk/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 | developer mode → 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` | толық немесе ішінара қайтару; `refunds:write` scope керек |
| `qutpay_simulate_payment` | тек sandbox: счётты төленді деп белгілеу, webhook шын жіберіледі |
| `qutpay_list_subscriptions`, `qutpay_get_subscription` | жазылымдарды оқу |

Құралдардан бөлек агент құжаттар (`qutpay://skill`, `qutpay://docs/integration`, `qutpay://docs/errors`) және екі дайын тапсырма алады: `integrate-checkout` (жобаға төлем қосу) және `verify-sandbox` (счёт → төлем → webhook циклін жүргізу).

## Агент не істей алмайды

- API кілті немесе webhook жасау — оны кабинетте өзіңіз жасайсыз.
- Сатып алушыдан ақша шешу — счётты әрқашан сатып алушы Kaspi.kz-те өзі төлейді.
- Live кілтпен төлемді имитациялау — құрал бас тартады.
- Live кілтпен нақты `confirm: true`-сіз қайтару жасау — сервер растауды талап етеді, агент сізден сұрауға міндетті.
- Кілтті көру: сервер оны ортадан оқиды, жауаптардағы ұқсас жолдарды маскалайды.

## Қауіпсіздік: қандай кілт беру

1. **Sandbox** (`qp_test_…`) — интеграция тексерілгенше. Ақша қозғалмайды, Kaspi қатыспайды.
2. **Live кілт** — агент операцияларға көмектескенде ғана, тек керек scope-пен. `refunds:write`-сіз агент қайтару жасай алмайды.
3. Кілтті кабинетте кез келген сәтте қайтарып алуға болады; API шектері (минутына 200 жазу, 600 оқу) агентке де қолданылады.

Тәуекелдер мен шектеулі кілттер туралы толығырақ: [Интеграцияны ЖИ-агентке тапсыру](/kb/ai-agent-setup), [Қауіпсіздік чек-листі](/kb/security-checklist).

## Жиі қойылатын сұрақтар

**Агент интеграцияны жазуы үшін MCP керек пе?** Жоқ. Код жазуға https://api.qut.kz/SKILL.md немесе https://api.qut.kz/for-ai жеткілікті. MCP агентке нәтижені сіздің қолыңызсыз тексеруге және операцияларға көмектесуге керек.

**Агент sandbox-та счёт құрды — сатып алушы оны көре ме?** Жоқ. Sandbox счёттары тек Qut Pay-де болады; төлем құралмен немесе төлем бетіндегі батырмамен имитацияланады.

**Бір агентті бірнеше дүкенге қосуға бола ма?** Иә: әр ұйымға өз кілтімен бір MCP сервер, мысалы `qutpay-shop1`, `qutpay-shop2`.

**Бастапқы коды қайда?** Ашық репозиторийде https://github.com/kazprose/qutpay-docs, `examples/mcp` қалтасы, MIT лицензиясы.