x402-mcp-demo

An MCP server whose tool invocations are metered and charged over x402, plus a paying-proxy reference client that lets any standard MCP client use the paid tool without knowing x402 exists. Settlement is real testnet USDC on Base Sepolia, landing in a Catena sandbox account.

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

How it works

The x402 challenge lives at the HTTP layer of the MCP Streamable HTTP transport, underneath the JSON-RPC framing, so the MCP protocol itself is untouched and standard clients stay compatible.

• initialize, tools/list, and the free pricing tool cost nothing.

• tools/call on premium_market_signal draws a 402 with an x402 v2 challenge (exact scheme). The proxy pays it, the facilitator settles into the configured payTo, and only then does a successful tool result return. Middleware order is the invariant: unpaid calls never reach the tool handler; MCP HTTP 4xx cancels settlement.

• The proxy refuses a paid call BEFORE paying when its running total would pass PROXY_SPEND_CAP_USD. The cap is configuration, never derived from tool arguments, so a prompt-injected tool call cannot raise it.

The call-by-call sequence, including where settlement is cancelled, is in docs/architecture.md.

Related MCP server: x402 MCP Proxy

Setup

Requires Node >= 22.13 (see .nvmrc) and 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.

Both entry points exit 2 when configuration is missing or invalid, and 1 when a dependency they need is unreachable (the facilitator for the server, the upstream MCP server for the proxy).

Demo: the whole loop in one command

pnpm demo

Boots the paid server against the public x402 facilitator, drives a standard MCP client through the paying proxy, and prints: free discovery, then the paid tool call settling $0.001 of testnet USDC into the Catena deposit address.

See the 402 yourself

Run pnpm server in one terminal, then ask for the paid tool without paying. The server answers /healthz with its price and paid-tool name, which is also what the proxy probes at startup:

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

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

The challenge itself travels in the PAYMENT-REQUIRED response header, not in the body (the body is {}), so decode the header to read it:

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"}}]}

Drop | grep ... to see the status line: HTTP/1.1 402 Payment Required. The tool never ran, so nothing settled.

Use it from Claude Code (standard client)

Run the paid server in one terminal (pnpm server), then register the proxy as an ordinary stdio MCP server in .mcp.json:

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

The proxy reads BUYER_EVM_PRIVATE_KEY and UPSTREAM_MCP_URL from this repo's own .env, so no secret goes into .mcp.json. (.mcp.json is gitignored here anyway; keep it that way if you copy this setup.)

Claude Code lists both tools and calls them normally; the proxy pays the 402 behind the scenes. MCP Inspector works the same way: npx @modelcontextprotocol/inspector pnpm proxy.

Tests

pnpm test runs the server and proxy suites against an in-process server with a recording fake facilitator: no network, no money. Each money-path invariant has a test that fails if it breaks.

Scope

Public surfaces only: the MCP TypeScript SDK, the public x402 packages and facilitator, and a Catena sandbox account as the receiving side. Versions and limits: docs/architecture.md.

License

MIT