Servidor MCP x402: configuración para Claude Code y Cursor
Un servidor MCP x402 le da a un agente de IA una herramienta que pide una URL y, cuando la URL responde 402 Payment Required, la paga en USDC y devuelve la respuesta pagada. Como es un servidor MCP, el mismo paquete funciona en Claude Code, Cursor, Claude Desktop y cualquier framework de agentes con un cliente MCP. Esta guía explica qué debería hacer un servidor así y configura @burnbound/mcp, un servidor MCP x402 que solo paga dentro de los límites que tú fijas, en Claude Code y Cursor. El mismo servidor también reembolsa cargos de Stripe a través de tu gateway de acciones, bajo la misma política.
Qué hace un servidor MCP x402
Sin uno, un agente que se encuentra un 402 se queda atascado: necesitaría una cartera, las cabeceras x402 y el código de firma. Un servidor MCP x402 lo resume todo en una llamada a una herramienta. El agente pide una URL; el servidor se ocupa del challenge, la firma y el reintento.
Esa comodidad también es el riesgo. Una herramienta que puede pagar es una herramienta que puede gastar de más, y es el modelo el que decide cuándo llamarla. Por eso una herramienta de pago debería comprobar cada pago contra reglas que el agente no puede cambiar, antes de firmar nada. @burnbound/mcp lo hace pidiendo a la API de Burnbound que evalúe la política del agente (hosts permitidos, un máximo por pago, un tope diario y, si quieres, aprobación humana) en cada 402. La cartera es tuya: Coinbase CDP o una clave en tu máquina.
Las ocho herramientas
@burnbound/mcp 0.10 ofrece ocho herramientas. Solo fetch_paid y stripe_refund pueden mover dinero. propose_rule escribe una regla que solo puede restringir al agente; las otras cinco son de solo lectura.
| Herramienta | Para qué la usa el agente |
|---|---|
fetch_paid |
Pedir una URL de un host permitido y pagar su challenge x402, o su tempo.charge de MPP si el agente lo tiene activado, dentro de la política. GET, POST y otros métodos, cabeceras, cuerpo y un maxAmountUsd por llamada. |
get_budget |
El gasto de hoy, el tope diario, lo que queda, el máximo por pago, el umbral de aprobación, los hosts permitidos y la red. |
list_payments |
Los pagos recientes, con estado, importe, host y hash de la transacción. |
get_approval_status |
Si una persona aprobó un pago que devolvió pending_approval. |
search_paid_apis |
Buscar en el catálogo de APIs x402 verificadas de Burnbound, con el precio y si la política permite cada una. |
diagnose_payment |
Averiguar, sin pagar, por qué no se puede pagar una URL: un 402 mal formado, una red o un token que Burnbound no puede pagar, USDC insuficiente o un vendedor caído. |
stripe_refund |
Reembolsar un cargo de Stripe bajo la política del agente, a través del gateway de acciones que corres tú con tu propia clave de Stripe (BURNBOUND_GATEWAY_URL). Los reembolsos grandes esperan a una persona, como los pagos. |
propose_rule |
Cuando se lo pides en el chat, añadir una regla que solo restringe los pagos del propio agente ("no más de 2 USD al día en este host"). Solo una persona puede quitarla. |
fetch_paid devuelve paid, ok (no hacía falta pagar) o pending_approval; cualquier otra cosa es un error con un código estable, como host_not_allowed o policy_denied. La referencia de las herramientas MCP documenta cada campo y cada error.
Antes de instalar
- Node.js 20 o posterior, con
npxen elPATHque ve tu cliente MCP. - Un agente de Burnbound con sus topes y sus hosts permitidos, y su clave del agente (
bb_agent_…). Entra en burnbound.dev y pulsa Crear cuenta: el onboarding crea las dos cosas y muestra la clave una sola vez. - Una cartera conectada al agente, con un saldo pequeño de USDC en su red (Base, o Base Sepolia para pruebas).
El servidor lee su configuración solo de variables de entorno. BURNBOUND_KEY es la única obligatoria.
Configuración en Claude Code
Un comando registra el servidor para todos los proyectos (--scope user):
claude mcp add burnbound --scope user -e BURNBOUND_KEY=bb_agent_… -- npx -y @burnbound/mcp@latest
Compruébalo con claude mcp list, o con /mcp dentro de una sesión. Para compartir el servidor con un equipo mediante un .mcp.json de proyecto sin hacer commit de la clave, y para fijar permisos para fetch_paid, consulta la integración con Claude Code.
Configuración en Cursor
Añade el servidor a ~/.cursor/mcp.json (todos los proyectos) o a .cursor/mcp.json (un proyecto):
{
"mcpServers": {
"burnbound": {
"command": "npx",
"args": ["-y", "@burnbound/mcp@latest"],
"env": {
"BURNBOUND_KEY": "bb_agent_…"
}
}
}
}
No hagas commit de un archivo que contenga la clave. La integración con Cursor explica cómo leer la clave de tu entorno y dónde ver los logs del servidor.
Comprueba la conexión
Pregúntale al agente: "¿Cuál es mi presupuesto de Burnbound?". Llamará a get_budget. Si el servidor no arranca, su stderr dice por qué:
BURNBOUND_KEY is required.: falta la clave en la configuración.BURNBOUND_KEY has an invalid format.: se pegó con caracteres de más.
Si arranca pero todas las herramientas responden unauthorized, la clave se revocó o está mal escrita.
Haz una primera llamada de pago
Elige un vendedor y añade su host a los hosts permitidos del agente. El catálogo de APIs x402 recoge vendedores verificados con su host y su precio, por ejemplo la búsqueda de You.com en api.you.com, que cobraba 0.005 USDC por llamada en Base la última vez que lo verificamos. Después:
Use fetch_paid to GET https://api.you.com/v1/search?query=x402&count=5 with maxAmountUsd "0.02".
O deja que el agente encuentre uno: Use search_paid_apis to find a web search API I can pay. Cada resultado dice si la política lo permite y, si no, por qué (host_not_allowed, network_not_allowed…).
Para una primera prueba sin dinero real, pon el agente en Base Sepolia y usa nuestro vendedor de demostración de testnet en https://demo.burnbound.dev/premium (0.01 USDC de prueba), como se explica en Primeros pasos.
De qué protege el servidor
Además de la política, el servidor añade protecciones en tu máquina:
- la clave del agente solo va a la API de Burnbound, nunca a las URL que pide, y nunca aparece en los resultados de las herramientas;
- solo pide hosts permitidos, y bloquea las direcciones privadas, de loopback y link-local;
- nunca sigue una redirección después de pagar, y rechaza un challenge para otro host;
- las respuestas del vendedor vuelven delimitadas y marcadas como no fiables, para que una API de pago no pueda hacer pasar su texto por instrucciones tuyas;
- falla en cerrado: si no puede contactar con Burnbound, no se paga nada.
Firmar con una clave en tu máquina es cooperativo: un agente que pueda ejecutar comandos de shell podría leerla. Carteras de agente: Coinbase CDP o una clave local explica cuándo usar CDP en su lugar.
Otros clientes y frameworks
El mismo servidor funciona con cualquier cliente MCP que ejecute servidores stdio: consulta la configuración de Claude Desktop, el Vercel AI SDK, LangChain.js y Mastra. ¿Empiezas de cero? Primeros pasos te lleva del registro al primer pago.