# AI-асистенти (MCP)

> Продавайте з Claude Code, Cursor чи Codex одним запитом: товари, ціни, платіжні посилання й тестові оплати через локальний MCP-сервер із вашим ключем.

`perly-pay-mcp` дає вашому асистентові налаштувати Perly Pay за вас: створити товар і ціну, поділитися платіжним посиланням, сплатити його в [тестовому режимі](https://pay.perly.io/docs/test-mode.md) і показати, що надійшло. Він працює на вашому комп'ютері й говорить лише з API Perly Pay, з вашим ключем. Нічого нашого посередині немає.

> **Примітка:** `perly-pay-mcp` незабаром з'явиться в npm; рядки нижче запрацюють того ж дня. А поки що — [API](https://pay.perly.io/docs/api.md) або [SDK](https://pay.perly.io/docs/sdks.md).

## Налаштування

1. **Візьміть тестовий ключ** — Dashboard → Developers → API keys: `sk_test_…`. Будуйте з ним — справжні гроші не рухаються.
2. **Додайте сервер** — Один рядок у Claude Code або кілька в конфігурації Cursor чи Codex. Потрібен Node 20 або новіший.
3. **Попросіть** — «Продай годинну консультацію за $49 через платіжне посилання, потім сплати її в тестовому режимі й покажи оплату».

**Claude Code**

```bash
claude mcp add perly-pay --env PERLY_PAY_SECRET_KEY=sk_test_… -- npx -y perly-pay-mcp
```

**Cursor**

```json
// ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
  "mcpServers": {
    "perly-pay": {
      "command": "npx",
      "args": ["-y", "perly-pay-mcp"],
      "env": { "PERLY_PAY_SECRET_KEY": "sk_test_…" }
    }
  }
}
```

**Codex**

```toml
# ~/.codex/config.toml
[mcp_servers.perly-pay]
command = "npx"
args = ["-y", "perly-pay-mcp"]
env = { PERLY_PAY_SECRET_KEY = "sk_test_…" }
```

> **Увага:** Не кладіть ключ у git: файл конфігурації в проєкті часто комітять.

| Змінна | Що це |
| --- | --- |
| `PERLY_PAY_SECRET_KEY` | `sk_test_…`, поки будуєте. `sk_live_…` теж працює, з обмеженнями нижче. |
| `PERLY_PAY_API` | Типово `https://pay.perly.io`. |
| `PERLY_PAY_WEBHOOK_SECRET` | Необов'язково: `whsec_…` для `verify_webhook_signature`. |

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

Згенеровані з опису самого [API](https://pay.perly.io/docs/api.md), тож кожен аргумент — той, що приймає API. Суми — цілі числа в центах: `4900` — це $49.00.

| Інструменти | Для чого |
| --- | --- |
| `create_product`, `list_products`, `update_product`, `create_price`, `list_prices`, `update_price` | товари й ціни |
| `create_payment_link`, `list_payment_links`, `update_payment_link` | платіжні посилання |
| `create_invoice`, `list_invoices`, `retrieve_invoice`, `cancel_invoice`, `create_checkout_session`, `retrieve_checkout_session` | рахунки й оплата |
| `create_customer`, `list_customers`, `retrieve_customer` | клієнти |
| `create_subscription`, `list_subscriptions`, `retrieve_subscription` | підписки |
| `check_entitlement`, `list_entitlements`, `consume_entitlement_credits`, `list_credit_usage` | доступ і кредити |
| `list_payments`, `retrieve_payment`, `list_receipts`, `retrieve_receipt`, `list_events` | оплати, квитанції, події |
| `create_refund`, `list_refunds` | повернення |
| `create_webhook_endpoint`, `list_webhook_endpoints`, `delete_webhook_endpoint` | вебхуки |
| `simulate_payment` | тестовий режим |
| `verify_webhook_signature`, `pay_links` | на вашому комп'ютері |

`simulate_payment` сплачує рахунок або купує через платіжне посилання й сплачує його, тож виконання, квитанції й [вебхуки](https://pay.perly.io/docs/webhooks.md) спрацьовують, як для справжнього покупця. `pay_links` дає сторінки кабінету для того, що можете зробити лише ви.

## Чого він не робить

- **З живим ключем** — нічого, що рухає чи перенаправляє гроші, витрачає кредити покупця або видаляє: жодних тестових оплат, повернень, витрати кредитів, нових чи видалених вебхуків. Інструмент пояснює чому і де це зробити. Читати, створювати товари, ціни, посилання й рахунки можна, як і в тесті.
- **Гаманці, API-ключі, тариф, перехід у живий режим і двофакторний вхід** — без інструментів. Це робите ви в кабінеті; `pay_links` дає сторінки.
- **Те, що не скасувати** — скасування рахунку, відкриття повернення, видалення вебхука — чекає на `confirm: true`, який асистент надсилає лише після вашої згоди.
- **Ваш секретний ключ ніколи не повторюється** ні у відповіді, ні в журналі.

## Перехід у живий режим

1. **Підключіть гаманець** — Його публічний ключ чи адресу, у кабінеті. Ми ніколи не просимо сід-фразу чи приватний ключ. Див. [Гаманці](https://pay.perly.io/docs/wallets.md).
2. **Увімкніть живий режим** — У кабінеті, щойно гаманець підключено.
3. **Замініть ключ** — Поставте `sk_live_…` замість `sk_test_…` на сервері вашого застосунку. Асистентові можна лишити тестовий ключ.