MCP / AI-агенты

recv поставляет сервер Model Context Protocol (MCP), который предоставляет платежный шлюз AI-агентам в виде инструментов и ресурсов. Любой MCP-совместимый клиент — Claude Desktop, Cursor и другие — может использовать его для создания счетов, проверки статуса платежей, верификации вебхуков и получения списка поддерживаемых сетей на естественном языке.

Сервер называется recv-agent-mcp и работает локально через stdio. Под капотом он вызывает тот же API recv, что описан в остальной документации. Он также умеет создать новый workspace для агента, выписать checkout на подписку recv и после оплаты выпустить API credentials.

Конфигурация

Сервер читает эти переменные окружения:

Claude Desktop

Добавьте сервер в claude_desktop_config.json (пакет опубликован в npm как recv-mcp; чтобы запускать из исходников, соберите его через cd mcp-server && npm install и укажите node /path/to/recv/mcp-server/dist/index.js):

{
  "mcpServers": {
    "recv": {
      "command": "npx",
      "args": ["-y", "recv-mcp"],
      "env": {
        "RECV_ACCESS_TOKEN": "your_console_token_here",
        "RECV_API_KEY": "test_your_key_here",
        "RECV_WEBHOOK_SECRET": "whsec_your_secret_here"
      }
    }
  }
}

Cursor

Добавьте тот же блок mcpServers в настройки MCP в Cursor (Settings → MCP) и перезагрузите. Инструменты recv появятся у агента автоматически.

Локальная разработка

cd mcp-server
npm install   # also compiles dist/ via the prepare script
npm run dev   # or: npm start

Инструменты

Агент может вызывать эти инструменты.

bootstrap_agent_workspace

Создать trial workspace для полностью автономного агента. Инструмент возвращает обычный результат авторизации recv; сохраните token или access_token как RECV_ACCESS_TOKEN перед вызовом self-service инструментов.

get_account

Вернуть текущий workspace, активный тариф и доступные платные тарифы. Требует RECV_ACCESS_TOKEN.

create_subscription_checkout

Создать billing checkout recv для текущего workspace. Требует RECV_ACCESS_TOKEN.

get_checkout_invoice

Прочитать публичный checkout invoice по public_id. Используйте для polling подписочного checkout до status: paid.

create_api_key

Создать developer API key после активации тарифа с API. Требует RECV_ACCESS_TOKEN.

create_webhook_endpoint

Зарегистрировать webhook endpoint после активации тарифа с вебхуками. Требует RECV_ACCESS_TOKEN.

create_invoice

Создать новый платежный счет.

Инструмент отправляет аргументы напрямую методом POST на /v1/invoices. Окружение созданного счета зависит от переданного API-ключа (test_ → test). См. Инвойсы.

get_invoice

Получить статус и детали счета.

Вызывает GET /v1/invoices/{id}.

list_invoices

Список недавних счетов с пагинацией.

Вызывает GET /v1/invoices?page=&page_size=.

simulate_payment

Пометить тестовый счет оплаченным без перевода on-chain.

Вызывает POST /v1/test/invoices/{id}/simulate-payment. Требует ключ test_.

verify_webhook

Проверить подпись вебхука локально, используя RECV_WEBHOOK_SECRET. Инструмент в точности воспроизводит продакшен-схему подписи: он вычисляет v1= + HMAC-SHA256 от <timestamp>.<raw_body> и сравнивает результат с переданной подписью за постоянное время.

Передавайте байты тела дословно. Повторное кодирование JSON (которое может изменить порядок ключей или пробелы) меняет хеш, и проверка не пройдет. Если RECV_WEBHOOK_SECRET не задан, инструмент возвращает ошибку. См. Webhooks для полной схемы подписи.

list_supported_networks

Список поддерживаемых вариантов оплаты. Не принимает параметров и возвращает статичную сводку пар сеть/актив (TON/GRAM, TON/USDT, TRON/USDT, SOLANA/SOL, SOLANA/USDT, SOLANA/USDC, BASE/USDT, BASE/USDC, ARBITRUM/USDT, ARBITRUM/USDC, BSC/BNB, BSC/USDT). См. Поддерживаемые сети для авторитетного списка.

Ресурсы

Сервер также предоставляет документацию как MCP-ресурсы, которые агент может читать для контекста. Каждый загружается из ${RECV_DOCS_URL}/raw/<slug>:

Сценарий: AI-агент принимает крипто-платеж

Для нового автономного агента:

1. Вызовите bootstrap_agent_workspace и сохраните возвращенный access token как RECV_ACCESS_TOKEN.
2. Вызовите create_subscription_checkout с plan_code: "developer".
3. Откройте или верните checkout URL, затем опрашивайте get_checkout_invoice, пока subscription invoice не станет paid.
4. Вызовите create_api_key и сохраните возвращенный secret как RECV_API_KEY.
5. Опционально вызовите create_webhook_endpoint и сохраните webhook secret как RECV_WEBHOOK_SECRET.

С сервером, настроенным на ключ test_ или live_, весь customer payment flow можно вести в диалоге:

1. Вы: «Создай счет на $25 USDT в TRON для заказа #5512.» Агент вызывает create_invoice и зачитывает public_id, destination_address и checkout_url.
2. Вы: «Он уже оплачен?» Агент вызывает get_invoice с полученным id и сообщает status: awaiting_payment.
3. Вы: «Симулируй оплату, чтобы я протестировал выполнение заказа.» Агент вызывает simulate_payment; счет переходит в paid, и отправляется вебхук.
4. Вы: «Проверь этот вебхук — вот сырое тело, timestamp и заголовок с подписью.» Агент вызывает verify_webhook с raw_body, timestamp и signature и сообщает, действительна ли подпись.
5. Вы: «В каких сетях я могу принимать оплату?» Агент вызывает list_supported_networks.

Поскольку каждый инструмент в итоге обращается к тому же API /v1, действия агента подчиняются тем же scopes, лимитам и правилам идемпотентности, что и любая другая интеграция.