Demostración de la herramienta MCP x402: un 402 real, un rechazo real y una liquidación real

Una demostración minimalista del protocolo de pago x402 que protege un endpoint de herramienta de estilo MCP, ejecutada contra el paquete real de Python x402==2.16.0 y su facilitador público predeterminado (https://x402.org/facilitator) en la testnet de Base Sepolia. Nada de esto es JSON de protocolo escrito a mano: cada respuesta en captured_responses/ salió de la librería sin editar.

Complemento de: Cómo cobrar por una herramienta MCP: un endpoint x402 funcional en menos de una hora.

Qué hay aquí

Related MCP server: 402-mcp

Ejecútalo

pip install -r requirements.txt
python gen_wallets.py          # writes wallets.json (gitignored) -- two fresh, empty keys
python server.py               # starts on 127.0.0.1:8402
python client_probe.py         # in a second terminal

Lo que verás

Ronda 1 — sin pago. Un 402 con una cabecera payment-required (JSON en base64): esquema, red, contrato del activo, importe en la unidad más pequeña del token y la dirección a la que pagar.

Ronda 2 — un pago firmado real, saldo cero. El cliente construye y firma una autorización EIP-3009 real con la clave desechable, la adjunta como X-PAYMENT, y el facilitador la comprueba contra el estado real de la cadena Base Sepolia. Devuelve:

{ "error": "invalid_exact_evm_insufficient_balance" }

Esa cadena es el código de error real del facilitador, no una suposición: es lo que obtienes cuando el protocolo funciona exactamente como está diseñado y el pagador simplemente no tiene el dinero.

Ronda 3 — financiada y liquidada de verdad. La agent_address fue financiada con 20 USDC de testnet desde el faucet público de Circle, y luego se ejecutó client_probe.py de nuevo contra el mismo servidor. Esta vez la ronda 2 devuelve 200:

{
  "url": "https://example.com/mcp",
  "recommendation": "expose as a priced x402 tool at $0.01/call",
  "paid": true
}

con una cabecera payment-response que se decodifica como:

{ "success": true, "payer": "0x3214cB6C...E0E9", "transaction": "0x9530b663...0dd86", "network": "eip155:84532" }

Ese hash de transacción es real y verificable de forma independiente — míralo en Base Sepolia Blockscout: estado ok, enviado al contrato USDC, método transferWithAuthorization — el patrón exacto de transferencia sin gas EIP-3009 que firmó el pagador. Cualquiera puede comprobarlo sin fiarse de este README.

Por qué el viaje de ida y vuelta manual en client_probe.py

x402 2.16.0 incluye PaymentRoundTripper, pero es un callback (handle_response(...)) pensado para conectarse a un transporte personalizado de httpx/requests: no es un transporte listo para usar por sí solo, a pesar de lo que sugiere el docstring. client_probe.py llama directamente a las mismas tres primitivas que aquel usa internamente (get_payment_required_response → create_payment_payload → encode_payment_signature_header), lo que supone menos piezas móviles para una demo y produce una salida de red idéntica.

Notas de seguridad

• gen_wallets.py crea claves con eth_account.Account.create() — criptográficamente aleatorias, nunca financiadas, y que en esta demo no tocan mainnet.

• wallets.json está en gitignore. wallets.example.json muestra la forma con una dirección de quema conocida para que el repositorio se pueda ejecutar desde un clon limpio sin secretos en el historial de git.

• La URL del facilitador, la red y el contrato del activo son los valores predeterminados de testnet de la propia librería: nada de esto habla con la mainnet de Base ni mueve valor real.