Primeros pasos: Claude Code y Cursor

Esta guía te lleva desde una cuenta nueva de Burnbound hasta la primera llamada a fetch_paid de tu agente. Creas un agente con reglas de gasto, conectas la cartera que firma sus pagos, añades el servidor MCP de Burnbound a Claude Code o Cursor y haces una primera petición.

¿Qué necesito antes de empezar?

Necesitas Node.js 20 o posterior (con npx en el PATH de tu cliente MCP), Claude Code o Cursor y una cuenta de Burnbound. Para pagar algo, también necesitas una cartera con un saldo pequeño de USDC en la red del agente: Base para pagos reales, o Base Sepolia para probar con USDC de prueba gratuito. Burnbound nunca custodia fondos: los pagos salen de tu propia cartera.

Node.js 20 o posterior: compruébalo con node --version.
Un cliente MCP: Claude Code o Cursor. Cualquier otro cliente MCP que ejecute servidores stdio funciona igual.
Una cuenta de Burnbound: créala en app.burnbound.dev.

Paso 1: ¿Cómo creo un agente y su clave?

Crea el agente en el panel de Burnbound; el onboarding empieza justo después de registrarte. Un agente tiene un nombre, un tope diario, un máximo por pago, una lista de hosts permitidos y la red en la que paga. Al principio, mantén los topes bajos: las llamadas x402 suelen costar céntimos.

Abre el onboarding en el panel y crea el agente.
Fija el tope diario, el máximo por pago y los hosts a los que el agente puede pagar, por ejemplo api.example.com o *.example.com.
Elige la red: Base para pagos reales (la opción por defecto) o Base Sepolia para probar con USDC de prueba. Consulta ¿Qué red debería usar mi agente?.
Continúa al paso de la cartera (paso 2). La clave se crea en el paso siguiente.

La clave del agente empieza por bb_agent_. El panel la muestra una sola vez, dentro de un comando de instalación listo para pegar. Burnbound guarda solo un hash, así que una clave perdida no se puede volver a mostrar: revócala y crea una nueva.

¿Qué red debería usar mi agente?

Cada agente paga USDC en una sola red. La API x402 del vendedor tiene que cobrar en esa misma red; si pide otra, el pago se deniega con network_not_allowed y no se firma nada.

Red	Id	Úsala para
Base	`eip155:8453`	Pagos reales en USDC. La opción por defecto para agentes nuevos.
Base Sepolia	`eip155:84532`	Pruebas. El USDC no tiene valor; consíguelo en el faucet de Circle. Una red de prueba.

Eliges la red al crear el agente en el onboarding. Para cambiarla después, abre el agente en el panel y usa su pestaña Red. El cambio se aplica al siguiente pago del agente. Recarga la cartera en la red que elegiste: el USDC de Base Sepolia no sirve para pagar a un vendedor en Base, ni al revés.

Paso 2: ¿Cómo conecto la cartera que firma?

Cada agente necesita una cartera que firme sus pagos. Burnbound decide si un pago está permitido; la cartera lo firma. En el panel eliges uno de dos modos. Consulta Conceptos para ver las ventajas e inconvenientes de cada uno.

Coinbase CDP. Pega tus credenciales de Coinbase Developer Platform (API key ID, API key secret, wallet secret) y la dirección de la cartera. La clave privada se queda en Coinbase.

Cartera en tu máquina (firma en el cliente). Crea la cartera en local y registra solo su dirección pública:

npx -y @burnbound/mcp@latest wallet init

El comando imprime la dirección. Pégala en el panel. La clave privada se queda en el llavero de tu sistema operativo (o en un archivo que solo puede leer tu usuario) y nunca se envía a Burnbound.

Después, recarga la cartera con un saldo pequeño de USDC en la red del agente: USDC real en Base, o USDC de prueba del faucet de Circle en Base Sepolia. No necesita ETH: en x402, el facilitador del vendedor envía la transferencia y paga el gas.

Paso 3: ¿Cómo añado Burnbound a Claude Code?

Ejecuta claude mcp add con la clave de tu agente en BURNBOUND_KEY. El panel muestra esta misma línea con tu clave ya rellenada; cópiala desde ahí.

claude mcp add burnbound --scope user -e BURNBOUND_KEY=bb_agent_… -- npx -y @burnbound/mcp@latest

Comprueba que el servidor está registrado:

claude mcp list

¿Cómo añado Burnbound a Cursor?

Añade el servidor a .cursor/mcp.json en tu proyecto, o a ~/.cursor/mcp.json para todos los proyectos, con la clave de tu agente en env:

{
  "mcpServers": {
    "burnbound": {
      "command": "npx",
      "args": ["-y", "@burnbound/mcp@latest"],
      "env": {
        "BURNBOUND_KEY": "bb_agent_…"
      }
    }
  }
}

No hagas commit de un archivo que contenga la clave. Reinicia Cursor o recarga sus servidores MCP después de editar el archivo.

¿Usas Claude Desktop, el Vercel AI SDK, LangChain.js o Mastra? Las integraciones (en inglés) tienen la configuración exacta de cada uno, y las páginas de Claude Code y Cursor cubren la configuración por proyecto, los permisos y la resolución de problemas.

Paso 4: ¿Cómo compruebo que el agente está conectado?

Pregúntale a tu agente: "¿Cuál es mi presupuesto de Burnbound?". Llamará a get_budget, que devuelve lo que el agente ha gastado hoy, su tope diario, lo que le queda, el máximo por pago, su umbral de aprobación, cuándo se reinicia el gasto diario, su red y sus hosts permitidos. Si funciona, la clave y la conexión con Burnbound están bien.

Si el servidor no arranca, lee su log en stderr (en Claude Code, claude mcp list lo muestra como fallido):

BURNBOUND_KEY is required.: falta la clave en la configuración MCP.
BURNBOUND_KEY has an invalid format.: el valor se pegó con caracteres de más.

Si arranca pero todas las herramientas responden unauthorized, la clave se revocó o está mal escrita. Crea una nueva en el panel.

Paso 5: ¿Cómo hago la primera petición de pago?

Pide al agente que obtenga una URL de una API x402 en uno de sus hosts permitidos, con un maxAmountUsd pequeño. La API tiene que cobrar en la red del agente: para una primera prueba sin dinero real, usa un agente en Base Sepolia y una API x402 que cobre en Base Sepolia. El agente llama a fetch_paid; si la URL responde HTTP 402, Burnbound comprueba el pago contra tus reglas, la cartera lo firma y el agente recibe la respuesta pagada.

Basta con un prompt como este:

Use fetch_paid to GET https://api.example.com/v1/report with maxAmountUsd "0.05".

El resultado te dice qué ha pasado:

paid: el pago se firmó y se envió. Incluye amountUsd, intentId y un receipt. El pago aparece en el panel.
ok: la URL no pidió ningún pago, así que no se pagó nada.
pending_approval: primero tiene que aprobarlo una persona, por ejemplo porque es el primer pago a la dirección de cobro de este vendedor (reason: "new_pay_to") o porque el importe iguala o supera el umbral de aprobación del agente. Una persona lo aprueba en el panel y después el agente lo reintenta (consulta Conceptos).
Un error de la herramienta con un código, como policy_denied o host_not_allowed: no se pagó nada. Una denegación también es una buena primera prueba: demuestra que las reglas se aplican. Las denegaciones aparecen en la auditoría del panel con su motivo.

Pruébalo con nuestro vendedor de demostración (Base Sepolia)

Para probar el flujo completo sin un vendedor real, usa nuestro vendedor x402 de demostración en https://demo.burnbound.dev. Solo funciona en testnet: vende en Base Sepolia (eip155:84532) a cambio de USDC de prueba, y nada de lo que sirve tiene valor real. No le pagues nunca desde una cartera con fondos reales.

URL	Precio	Qué muestra con los valores por defecto del onboarding (1 USD por pago, 10 USD al día)
`https://demo.burnbound.dev/premium`	0.01 USDC	Una petición pagada.
`https://demo.burnbound.dev/report`	0.50 USDC	`pending_approval` si el umbral de aprobación del agente es de 0.50 USD o menos; si no, se paga.
`https://demo.burnbound.dev/dataset`	2.00 USDC	`policy_denied` con `amount_exceeds_per_transaction`.

Antes de empezar, añade demo.burnbound.dev a los hosts permitidos del agente y recarga su cartera con USDC de Base Sepolia del faucet de Circle. La política del agente tiene que permitir Base Sepolia: un agente que solo permite Base mainnet, la opción por defecto para agentes nuevos, recibe policy_denied con network_not_allowed y no se paga nada. Pasa a fetch_paid un maxAmountUsd igual o superior al precio, por ejemplo:

Use fetch_paid to GET https://demo.burnbound.dev/premium with maxAmountUsd "0.05".

El vendedor de demostración está en el catálogo de Burnbound con su dirección de cobro fijada, así que su primer pago no espera ninguna aprobación: /premium se paga al momento. Si alguna vez pidiera cobrar en otra dirección, el pago se denegaría con pay_to_not_verified. Con otros vendedores es distinto: el primer pago de tu organización a una dirección de cobro a la que no ha pagado antes espera una vez tu aprobación (pending_approval con reason: "new_pay_to"), salvo que el vendedor esté en el catálogo y pida cobrar en una dirección que Burnbound le tiene fijada.

¿Qué puede fallar en la primera llamada?

La mayoría de los errores de la primera llamada vienen de las reglas del agente o de su cartera, y todos significan que no se pagó nada. La tabla recoge los más comunes; la referencia de las herramientas MCP tiene la lista completa.

Error	Qué hacer
`host_not_allowed`	Añade el host de la URL a los hosts permitidos del agente en el panel. No se hizo ninguna petición.
`policy_denied` con `daily_cap_exceeded`	El pago superaría el tope de hoy (día UTC). Sube el tope o espera al día siguiente.
`policy_denied` con `amount_exceeds_per_transaction`	El precio supera el máximo por pago. Súbelo si te fías del vendedor.
`policy_denied` con `rule_limit_exceeded` o `rule_denied`	Una regla propia rechazó el pago: la del agente (como el tope semanal `tope-semanal`), la de su subequipo o la de la organización. `rules` indica cuál. Cámbiala en el panel o espera a que se reinicie su ventana.
`policy_denied` con `network_not_allowed`	El vendedor cobra en una red que el agente no usa. Cambia la red del agente en su pestaña Red, o paga a un vendedor de la red del agente.
`amount_exceeds_max`	El precio supera el `maxAmountUsd` de esa llamada.
`client_wallet_not_initialized`	Firma en el cliente: ejecuta `npx -y @burnbound/mcp@latest wallet init` y registra la dirección.
`client_wallet_mismatch`	Firma en el cliente: la cartera local no es la registrada para el agente. Registra `localAddress` o define `BURNBOUND_WALLET_PROFILE`.
`plan_limit_reached`	Has llegado al límite de tu plan (por ejemplo, el gasto gestionado del plan Free). Una persona puede mejorar el plan en `upgradeUrl`.

¿Y ahora qué?

Añade reglas propias al agente: un tope semanal, un tope por host o una aprobación para payees nuevos. Pruébalas primero en modo observación.
¿Tienes varios agentes, o un agente con subagentes? Dale a cada uno su propia clave y ponlos en un subequipo con un presupuesto compartido.
Lee el modelo de seguridad antes de recargar una cartera con dinero real.