# MCP з ключем — покупки ШІ-агентом

> Як підключити MCP-сервер ZRAZU з ключем API: агент реєструє й продовжує домени, замовляє SSL з балансу і дає людині посилання на доплату.

URL: https://zrazu.com/docs/api-mcp-account/

Цей MCP-сервер працює від імені вашої організації за [ключем API](https://zrazu.com/docs/api-keys.md). Агент бачить лише ті інструменти, на які в ключа є права, і платить лише з балансу. Правила ті самі, що в [покупках через API](https://zrazu.com/docs/api-orders.md): список IP, ліміти, денний ліміт ключа й журнал дій.

Відкритий сервер паспорта домену без ключа описано в [MCP для ШІ-агентів](https://zrazu.com/docs/api-mcp.md).

## Підключити

Адреса сервера: `https://api.zrazu.com/v1/mcp`. Ключ передається в заголовку `Authorization: Bearer`.

**Claude Code:**

```sh
claude mcp add --transport http zrazu-account https://api.zrazu.com/v1/mcp --header "Authorization: Bearer zr_live_..."
```

**Cursor, VS Code та інші клієнти з конфігурацією JSON:**

```json
{ "mcpServers": { "zrazu-account": { "type": "http", "url": "https://api.zrazu.com/v1/mcp", "headers": { "Authorization": "Bearer zr_live_..." } } } }
```

Ключ, що витрачає гроші, працює лише з адрес зі свого списку. Тому підключайте сервер в агенті, який працює на вашому комп'ютері чи сервері. Хмарні асистенти ходять з адрес свого провайдера, і такий ключ їм відмовить.

## Інструменти

| Інструмент | Що робить | Право |
|---|---|---|
| `whoami` | права ключа, його домени, адреси й строк | будь-яке |
| `balance_get` | баланс організації | `billing.read` |
| `domains_list` | домени організації | `domain.read` |
| `owners_list` | кого можна записати власником нового домену | `domain.register` |
| `domain_register` | зареєструвати домен | `domain.register` |
| `domain_renew` | продовжити домен; `expires_at` з `domains_list` обов'язковий — другого продовження не буде | `domain.renew` |
| `ssl_catalog` | сертифікати й ціни | `ssl.read` |
| `ssl_order` | замовити сертифікат | `ssl.order` |
| `order_get` | стан замовлення, з очікуванням `wait` до 60 с | будь-яке з прав замовлень |
| `order_payment_link` | нове посилання на доплату | право покупок |
| `order_pay` | оплатити замовлення з балансу | право покупок |

Відповідь інструмента — та сама, що в API: код і тіло. Помилки мають ті самі коди, див. [покупки через API](https://zrazu.com/docs/api-orders.md).

## Як агент купує

1. Кожна покупка має `idempotency_key` — будь-який унікальний рядок. Повторюючи ту саму покупку після обриву, агент передає той самий рядок, і другого списання не буде.
2. Якщо грошей бракує, відповідь містить `payment_url`. Це не помилка: агент передає посилання людині, а потім чекає через `order_get` з `wait`, доки замовлення не стане `paid` і `fulfilled`.
3. Для реєстрації агент бере власника з `owners_list`. Перший виклик повертає `documents_required` з документами реєстру й `documents_hash`. Агент показує документи людині. Якщо ваша організація дозволила агентові погоджуватися без людини, повторний виклик із цим відбитком — згода самої організації, як галочка в кабінеті.

## Якщо не вийшло

- **Інструментів майже немає.** Агент бачить лише те, на що в ключа є права. Подивіться права через `whoami`.
- **`403 ip_not_allowed`.** Агент ходить не з адреси зі списку ключа. Перевірте, де він працює.
- **`400` або `413`.** У запиті більше 10 повідомлень JSON-RPC або тіло більше 256 КБ. Надсилайте менше.
- **`401`.** Ключ не передано, він відкликаний або прострочений.
- **Відповідь `403` без JSON-RPC.** Запит прийшов зі сторінки в браузері. Ключ працює лише з програм.