x402-mcp-demo

Ein MCP-Server, dessen Tool-Aufrufe über x402 gemessen und abgerechnet werden, plus ein Paying-Proxy-Referenzclient, der es jedem Standard-MCP-Client ermöglicht, das kostenpflichtige Tool zu nutzen, ohne von x402 zu wissen. Die Abrechnung erfolgt in echtem Testnetz-USDC auf Base Sepolia und landet auf einem Catena-Sandbox-Konto.

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

So funktioniert es

Die x402-Challenge befindet sich auf der HTTP-Ebene des MCP Streamable HTTP-Transports, unterhalb des JSON-RPC-Rahmens, sodass das MCP-Protokoll selbst unberührt bleibt und Standard-Clients kompatibel bleiben.

• initialize, tools/list und das kostenlose pricing-Tool kosten nichts.

• tools/call auf premium_market_signal zieht eine 402 mit einer x402 v2-Challenge (genaues Schema). Der Proxy bezahlt sie, der Facilitator führt die Abrechnung auf das konfigurierte payTo durch, und erst dann wird ein erfolgreiches Tool-Ergebnis zurückgegeben. Die Reihenfolge der Middleware ist die Invariante: unbezahlte Aufrufe erreichen nie den Tool-Handler; MCP HTTP 4xx bricht die Abrechnung ab.

• Der Proxy lehnt einen bezahlten Aufruf VOR der Bezahlung ab, wenn sein laufender Gesamtbetrag PROXY_SPEND_CAP_USD überschreiten würde. Das Limit ist Konfiguration, wird niemals aus Tool-Argumenten abgeleitet, sodass ein prompt-injizierter Tool-Aufruf es nicht erhöhen kann.

Die aufrufweise Abfolge, einschließlich wo die Abrechnung abgebrochen wird, finden Sie in docs/architecture.md.

Related MCP server: x402 MCP Proxy

Einrichtung

Erfordert Node >= 22.13 (siehe .nvmrc) und 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.

Beide Einstiegspunkte beenden mit Exit-Code 2, wenn die Konfiguration fehlt oder ungültig ist, und mit 1, wenn eine benötigte Abhängigkeit nicht erreichbar ist (der Facilitator für den Server, der vorgelagerte MCP-Server für den Proxy).

Demo: Der gesamte Kreislauf in einem Befehl

pnpm demo

Startet den kostenpflichtigen Server gegen den öffentlichen x402-Facilitator, treibt einen Standard-MCP-Client durch den Paying Proxy und gibt Folgendes aus: kostenlose Erkennung, dann den bezahlten Tool-Aufruf, der $0,001 Testnetz-USDC auf die Catena-Einzahlungsadresse abrechnet.

Sehen Sie die 402 selbst

Führen Sie pnpm server in einem Terminal aus und fragen Sie dann nach dem kostenpflichtigen Tool, ohne zu bezahlen. Der Server antwortet auf /healthz mit seinem Preis und dem Namen des kostenpflichtigen Tools, was der Proxy auch beim Start abfragt:

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

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

Die Challenge selbst wird im PAYMENT-REQUIRED-Antwort-Header übertragen, nicht im Body (der Body ist {}), daher dekodieren Sie den Header, um sie zu lesen:

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

Entfernen Sie | grep ..., um die Statuszeile zu sehen: HTTP/1.1 402 Payment Required. Das Tool wurde nie ausgeführt, also wurde nichts abgerechnet.

Verwendung mit Claude Code (Standard-Client)

Führen Sie den kostenpflichtigen Server in einem Terminal aus (pnpm server), registrieren Sie dann den Proxy als normalen stdio MCP-Server in .mcp.json:

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

Der Proxy liest BUYER_EVM_PRIVATE_KEY und UPSTREAM_MCP_URL aus der eigenen .env dieses Repos, sodass kein Geheimnis in .mcp.json gelangt. (.mcp.json ist hier ohnehin gitignoriert; behalten Sie das so bei, wenn Sie dieses Setup kopieren.)

Claude Code listet beide Tools auf und ruft sie normal auf; der Proxy bezahlt die 402 im Hintergrund. MCP Inspector funktioniert auf die gleiche Weise: npx @modelcontextprotocol/inspector pnpm proxy.

Tests

pnpm test führt die Server- und Proxy-Suiten gegen einen prozessinternen Server mit einem aufzeichnenden Fake-Facilitator aus: kein Netzwerk, kein Geld. Jede Geldpfad-Invariante hat einen Test, der fehlschlägt, wenn sie verletzt wird.

Umfang

Nur öffentliche Oberflächen: das MCP TypeScript SDK, die öffentlichen x402-Pakete und der Facilitator sowie ein Catena-Sandbox-Konto als Empfängerseite. Versionen und Grenzen: docs/architecture.md.

Lizenz

MIT