x402-mcp-demo

Un servidor MCP cuyas invocaciones de herramientas se miden y cobran mediante x402, junto con un cliente de referencia de proxy de pago que permite a cualquier cliente MCP estándar usar la herramienta de pago sin saber que x402 existe. La liquidación es en USDC real de testnet en Base Sepolia, depositada en una cuenta sandbox de 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

Cómo funciona

El desafío x402 reside en la capa HTTP del transporte HTTP transmisible de MCP, debajo del marco JSON-RPC, por lo que el protocolo MCP en sí no se modifica y los clientes estándar siguen siendo compatibles.

• initialize, tools/list y la herramienta gratuita pricing no cuestan nada.

• tools/call en premium_market_signal genera un 402 con un desafío x402 v2 (esquema exacto). El proxy lo paga, el facilitador liquida en el payTo configurado, y solo entonces se devuelve un resultado exitoso de la herramienta. El orden del middleware es el invariante: las llamadas no pagadas nunca llegan al manejador de la herramienta; MCP HTTP 4xx cancela la liquidación.

• El proxy rechaza una llamada de pago ANTES de pagar cuando su total acumulado superaría PROXY_SPEND_CAP_USD. El límite es configuración, nunca se deriva de los argumentos de la herramienta, por lo que una llamada de herramienta inyectada mediante prompt no puede aumentarlo.

La secuencia llamada por llamada, incluido dónde se cancela la liquidación, está en docs/architecture.md.

Related MCP server: x402 MCP Proxy

Configuración

Requiere Node >= 22.13 (ver .nvmrc) y 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.

Ambos puntos de entrada salen con código 2 cuando falta la configuración o es inválida, y con 1 cuando una dependencia que necesitan es inalcanzable (el facilitador para el servidor, el servidor MCP upstream para el proxy).

Demo: el ciclo completo en un comando

pnpm demo

Inicia el servidor de pago contra el facilitador público x402, dirige un cliente MCP estándar a través del proxy de pago, e imprime: descubrimiento gratuito, luego la llamada de herramienta de pago que liquida $0.001 de USDC testnet en la dirección de depósito de Catena.

Ver el 402 usted mismo

Ejecute pnpm server en una terminal, luego solicite la herramienta de pago sin pagar. El servidor responde a /healthz con su precio y el nombre de la herramienta de pago, que es también lo que el proxy consulta al iniciar:

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

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

El desafío en sí viaja en el encabezado de respuesta PAYMENT-REQUIRED, no en el cuerpo (el cuerpo es {}), así que decodifique el encabezado para leerlo:

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

Elimine | grep ... para ver la línea de estado: HTTP/1.1 402 Payment Required. La herramienta nunca se ejecutó, por lo que no se liquidó nada.

Usarlo desde Claude Code (cliente estándar)

Ejecute el servidor de pago en una terminal (pnpm server), luego registre el proxy como un servidor MCP stdio ordinario en .mcp.json:

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

El proxy lee BUYER_EVM_PRIVATE_KEY y UPSTREAM_MCP_URL del propio .env de este repositorio, por lo que ningún secreto va a .mcp.json. (.mcp.json está en gitignore aquí de todos modos; manténgalo así si copia esta configuración).

Claude Code lista ambas herramientas y las llama normalmente; el proxy paga el 402 en segundo plano. MCP Inspector funciona de la misma manera: npx @modelcontextprotocol/inspector pnpm proxy.

Pruebas

pnpm test ejecuta las suites del servidor y del proxy contra un servidor en proceso con un facilitador falso que graba: sin red, sin dinero. Cada invariante de la ruta de dinero tiene una prueba que falla si se rompe.

Alcance

Solo superficies públicas: el SDK de MCP TypeScript, los paquetes públicos x402 y el facilitador, y una cuenta sandbox de Catena como lado receptor. Versiones y límites: docs/architecture.md.

Licencia

MIT