# Рецепт: платний MCP-сервер

> Беріть плату за інструменти MCP-сервера за кожен виклик — кредитами. Людина раз купує пакет; кожен виклик спершу списує, потім працює.

Агенти не мають платити самі. Людина купує пакет кредитів у браузері, а далі кожен виклик інструмента перевіряє баланс, списує кредити з ключем ідемпотентності й працює. Коли кредитів немає, інструмент відповідає посиланням на поповнення, яке агент показує людині. Без x402, без гаманця в агенті, без автосписань.

> **Примітка:** З асистентом: цей рецепт робить у вашому проєкті скіл `paid-mcp-tools` плагіна Perly Pay для Claude Code — плагін і його приклад `examples/paid-mcp-server` (MIT) уже на шляху. Доти будь-який асистент прочитає той самий скіл з `/.well-known/skills/perly-pay-paid-mcp-tools/SKILL.md`.

## Як це працює

1. **Пакет кредитів** — Як в [API-кредитах](https://pay.perly.io/docs/recipe-api-credits.md). Дайте кожному інструменту ціну й напишіть її в його описі.
2. **Хто викликає** — Розміщений сервер зіставляє API-ключ кожного абонента з `external_id` клієнта. `PERLY_PAY_SECRET_KEY` є лише на вашому сервері.
3. **Спершу списати, потім працювати** — `credits.consume` з назвою інструмента як `action` і ключем з ідентифікатора сесії та запиту (ідентифікатори JSON-RPC щосесії починаються знову), далі робота.
4. **Бракує?** — Поверніть результат інструмента з `isError: true` і посиланням на поповнення, а не помилку протоколу: клієнти його показують.
5. **Безплатні помічники** — Інструменти `balance` і `top_up`, щоб агент міг пояснити, що відбувається.

**A paid tool**

```js
server.registerTool("summarize", { description: "Costs 3 credits.", inputSchema: { text: z.string() } }, async ({ text }, extra) => {
  const refused = await charge(userId, 3, "summarize", extra.requestId); // credits.consume, or a top-up message
  if (refused) return { isError: true, content: [{ type: "text", text: refused }] };
  return { content: [{ type: "text", text: summarize(text) }] };
});
```

## Запустіть приклад

1. **Встановіть** — `npm install` у `examples/paid-mcp-server` (Node 20.12+).
2. **Ключ** — Скопіюйте `.env.example` у `.env` і впишіть тестовий ключ (`sk_test_…`) у `PERLY_PAY_SECRET_KEY`.
3. **Підготуйте** — `npm run setup` створює продукт і ціну вашим ключем та друкує їхні ідентифікатори для `.env`.
4. **Запустіть** — `npm start` (або `npm run dev`), як каже його README.
5. **Сплатіть без гаманця** — Додайте його в Claude Code (`claude mcp add paid-tools -- npx tsx "$PWD/src/server.ts"`), запустіть `word_stats`: відповідь — сторінка поповнення. Оберіть пакет, натисніть **Simulate payment** і запустіть знову.

## Пастки

- `PERLY_PAY_SECRET_KEY` у конфігурації MCP, яку копіюють інші. Розмістіть сервер у себе або нехай він звертається до вашого бекенду.
- Списувати після роботи: невдале списання тоді означає безплатну роботу.
- Ключ ідемпотентності лише з ідентифікатора JSON-RPC: нова сесія повторить його й відтворить старе списання.