x402-mcp-demo

MCP-сервер, вызовы инструментов которого тарифицируются и оплачиваются через x402, а также эталонный клиент-платежный прокси, позволяющий любому стандартному MCP-клиенту использовать платный инструмент, не зная о существовании x402. Расчеты производятся в реальном тестовом USDC в сети Base Sepolia и поступают на счет в песочнице Catena.

flowchart LR
  CL["Standard MCP client<br/>Claude Code, Inspector"] -->|stdio JSON-RPC| PX["Paying proxy<br/>holds the wallet, spend cap"]
  PX -->|Streamable HTTP + x402| SV["Paid MCP server<br/>gate in front of the handler"]
  SV -->|verify then settle| F[Facilitator]
  F -->|USDC| CA[(Catena sandbox account)]

  classDef pay stroke-width:2px
  class PX,SV pay

Как это работает

Запрос x402 находится на HTTP-уровне транспорта MCP Streamable HTTP, под обрамлением JSON-RPC, поэтому сам протокол MCP не изменяется, а стандартные клиенты остаются совместимыми.

• initialize, tools/list и бесплатный инструмент pricing ничего не стоят.

• tools/call для premium_market_signal вызывает 402 с запросом x402 v2 (точная схема). Прокси оплачивает его, фасилитатор переводит средства на настроенный payTo, и только после этого возвращается успешный результат работы инструмента. Порядок промежуточного ПО неизменен: неоплаченные вызовы никогда не доходят до обработчика инструмента; MCP HTTP 4xx отменяет расчет.

• Прокси отказывает в платном вызове ДО оплаты, если его текущая сумма превысит PROXY_SPEND_CAP_USD. Лимит задается конфигурацией и никогда не вычисляется из аргументов инструмента, поэтому вызов инструмента, внедренный через подсказку, не может его увеличить.

Последовательность вызовов, включая моменты отмены расчета, описана в docs/architecture.md.

Related MCP server: x402 MCP Proxy

Настройка

Требуется Node >= 22.13 (см. .nvmrc) и pnpm.

corepack enable
pnpm install
cp .env.example .env
# SELLER_PAY_TO_ADDRESS: your Catena sandbox account's base-sepolia USDC
#   deposit address, from app.catena.com
# BUYER_EVM_PRIVATE_KEY: a testnet wallet the proxy pays from. Fund it with
#   Base Sepolia USDC at https://faucet.circle.com (select Base Sepolia).
#   USDC only; no ETH is needed, transfers are gasless EIP-3009.

Обе точки входа завершаются с кодом 2, когда конфигурация отсутствует или недействительна, и с кодом 1, когда необходимая зависимость недоступна (фасилитатор для сервера, вышестоящий MCP-сервер для прокси).

Демонстрация: полный цикл одной командой

pnpm demo

Запускает платный сервер с публичным фасилитатором x402, управляет стандартным MCP-клиентом через платежный прокси и выводит: бесплатное обнаружение, а затем оплаченный вызов инструмента, переводящий $0.001 тестового USDC на депозитный адрес Catena.

Увидеть 402 самостоятельно

Запустите pnpm server в одном терминале, затем запросите платный инструмент без оплаты. Сервер отвечает на /healthz своей ценой и именем платного инструмента, что также проверяет прокси при запуске:

curl -s http://localhost:4040/healthz

{"status":"ok","paidTool":"premium_market_signal","price":"$0.001"}

Сам запрос передается в заголовке ответа PAYMENT-REQUIRED, а не в теле (тело — {}), поэтому декодируйте заголовок, чтобы прочитать его:

curl -si -X POST http://localhost:4040/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"premium_market_signal","arguments":{"topic":"usdc"}}}' \
  | grep -i '^payment-required:' | tr -d '\r' | cut -d' ' -f2 | base64 -d

{"x402Version":2,"error":"Payment required","resource":{"url":"http://localhost:4040/mcp","description":"One invocation of the premium_market_signal MCP tool","mimeType":""},"accepts":[{"scheme":"exact","network":"eip155:84532","amount":"1000","asset":"0x036CbD53842c5426634e7929541eC2318f3dCF7e","payTo":"0x000000000000000000000000000000000000dEaD","maxTimeoutSeconds":300,"extra":{"name":"USDC","version":"2"}}]}

Уберите | grep ..., чтобы увидеть строку состояния: HTTP/1.1 402 Payment Required. Инструмент не запускался, поэтому ничего не было оплачено.

Использование с Claude Code (стандартный клиент)

Запустите платный сервер в одном терминале (pnpm server), затем зарегистрируйте прокси как обычный stdio MCP-сервер в .mcp.json:

{
  "mcpServers": {
    "paid-market-signal": {
      "command": "pnpm",
      "args": ["--dir", "/path/to/x402-mcp-demo", "proxy"]
    }
  }
}

Прокси считывает BUYER_EVM_PRIVATE_KEY и UPSTREAM_MCP_URL из собственного .env этого репозитория, поэтому никакие секреты не попадают в .mcp.json. (.mcp.json в любом случае игнорируется git; сохраните это так, если скопируете данную настройку.)

Claude Code выводит оба инструмента и вызывает их обычным образом; прокси оплачивает 402 за кулисами. MCP Inspector работает аналогично: npx @modelcontextprotocol/inspector pnpm proxy.

Тесты

pnpm test запускает наборы тестов сервера и прокси с внутрипроцессным сервером и записывающим фиктивным фасилитатором: без сети, без денег. Каждый инвариант денежного пути имеет тест, который проваливается при его нарушении.

Область применения

Только публичные поверхности: MCP TypeScript SDK, публичные пакеты и фасилитатор x402, а также счет в песочнице Catena в качестве принимающей стороны. Версии и ограничения: docs/architecture.md.

Лицензия

MIT