Посібники

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

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

Відкрити як Markdown

Агенти не мають платити самі. Людина купує пакет кредитів у браузері, а далі кожен виклик інструмента перевіряє баланс, списує кредити з ключем ідемпотентності й працює. Коли кредитів немає, інструмент відповідає посиланням на поповнення, яке агент показує людині. Без 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-кредитах. Дайте кожному інструменту ціну й напишіть її в його описі.
2
Хто викликає
Розміщений сервер зіставляє API-ключ кожного абонента з external_id клієнта. PERLY_PAY_SECRET_KEY є лише на вашому сервері.
3
Спершу списати, потім працювати
credits.consume з назвою інструмента як action і ключем з ідентифікатора сесії та запиту (ідентифікатори JSON-RPC щосесії починаються знову), далі робота.
4
Бракує?
Поверніть результат інструмента з isError: true і посиланням на поповнення, а не помилку протоколу: клієнти його показують.
5
Безплатні помічники
Інструменти balance і top_up, щоб агент міг пояснити, що відбувається.

A paid tool

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: нова сесія повторить його й відтворить старе списання.