Referencia de las herramientas MCP

@burnbound/mcp es el servidor MCP que permite a un agente pagar APIs x402 bajo su política de Burnbound. Funciona por stdio con npx -y @burnbound/mcp@latest, expone siete herramientas (fetch_paid, get_budget, propose_rule, list_payments, get_approval_status, search_paid_apis y diagnose_payment) e incluye una CLI wallet para la firma en el cliente y una CLI doctor que explica por qué falla un pago. Esta página documenta la versión 0.7.0.

¿Cómo configuro el servidor?

El servidor se configura solo con variables de entorno en la configuración de tu cliente MCP. BURNBOUND_KEY es la única obligatoria. El servidor comprueba la configuración antes de arrancar y, si falta algo o algo no es seguro, se cierra con un mensaje en stderr.

El servidor no arranca si alguna variable BURNBOUND_* parece una clave privada: las claves de cartera nunca van en la configuración MCP. Una clave de organización sigue funcionando junto con BURNBOUND_AGENT_ID, con un aviso en stderr: las claves de organización tienen alcance de administrador, así que usa una clave de agente.

¿Qué hace fetch_paid?

fetch_paid pide una URL de uno de los hosts permitidos del agente y, si la URL responde HTTP 402 con un challenge x402, la paga bajo la política del agente y devuelve la respuesta pagada. Es la única herramienta que puede gastar dinero, y se declara al cliente MCP como no de solo lectura y de mundo abierto.

origin solo sirve para la auditoría. Burnbound lo guarda en el registro de auditoría y con la aprobación, pero nunca lo usa para decidir: un pago declarado user pasa exactamente por las mismas reglas que uno declarado web, y un agente que no lo indica o lo declara mal no gana nada.

maxAmountUsd se compara con el challenge del vendedor antes de autorizar nada, y de nuevo con lo que se firma. Se aplica al precio que Burnbound puede pagar: USDC exact en Base o Base Sepolia. Los precios en otras cadenas, en otros tokens o en otros esquemas se ignoran, porque nunca se pagan.

¿Qué resultados puede devolver fetch_paid?

fetch_paid devuelve uno de tres estados. Todo lo demás (una denegación, un límite, un problema de red) vuelve como error de herramienta con un código.

body es { untrusted: true, contentType, encoding, bytes, truncated, text }. Los tipos de contenido binarios vuelven codificados en base64. En el resultado de la herramienta, el cuerpo va en un bloque de texto aparte, delimitado y etiquetado como contenido de terceros no fiable, nunca mezclado con los metadatos. Las cabeceras de la respuesta nunca se devuelven.

status solo es paid cuando el vendedor respondió a la petición pagada con un 2xx y no informó de que la liquidación hubiera fallado. Cualquier otra respuesta después de pagar (otro 402, una redirección, un error) es un error de herramienta, payment_rejected_by_seller o payment_not_completed, nunca paid. fetch_paid envía un pago firmado una sola vez por llamada y nunca vuelve a firmar por su cuenta.

receipt.state es unknown cuando no se pudo registrar el recibo; el pago se hizo igualmente si status es paid. Si no se pudo leer el cuerpo de la respuesta pagada, bodyError dice por qué, y el pago se informa igual.

¿Por qué un pago espera una aprobación?

reason, en un resultado pending_approval, dice por qué una persona tiene que aprobar este pago. Un pago que incumple una regla se deniega, nunca se manda a aprobación; estas retenciones llegan después de que pasen todas las reglas.

Un pago retenido tiene un único motivo: el primero que aplica, en el orden de la tabla. thresholdUsd es null para todos los motivos menos threshold. new_pay_to e instruction_like_description se aplican a todos los agentes y no necesitan ajuste; el umbral, la regla de hosts del catálogo y las reglas propias se configuran en el panel. Las versiones de @burnbound/mcp anteriores a la 0.4.0 informan new_pay_to e instruction_like_description como threshold.

¿Puede el usuario aprobar desde el chat?

En parte: el chat puede abrir la página de aprobación, pero la decisión la toma siempre una persona con sesión iniciada en el panel de Burnbound.

Cuando el servidor conoce la dirección del panel (BURNBOUND_APP_URL, o el origen de BURNBOUND_API cuando es https://), un resultado pending_approval lleva approvalUrl, la página de esa aprobación en el panel. El enlace solo lleva el id de la aprobación; sin una sesión de la organización no muestra nada. El agente debe dárselo al usuario y nunca abrirlo él mismo.

Si el cliente MCP admite la elicitación en modo URL (protocolo MCP 2025-11-25 o 2026-07-28), fetch_paid también pide al cliente que ofrezca esa página al usuario, como mucho una vez por llamada:

1. El usuario acepta abrir la página. Aceptar solo la abre; no aprueba nada.
2. fetch_paid espera hasta BURNBOUND_APPROVAL_WAIT_MS (40 segundos por defecto) y consulta la aprobación cada 2 segundos.
3. Si una persona aprueba a tiempo, la misma llamada paga, con la misma idempotencyKey y después de repetir todas las comprobaciones: hosts permitidos, maxAmountUsd, el 402 del vendedor y la cartera. Si la persona lo rechaza, o la aprobación caduca, la llamada termina en approval_denied o approval_expired.
4. Si nadie decide a tiempo, la llamada devuelve pending_approval y el agente consulta get_approval_status como siempre.

approvalPrompt dice qué pasó con la página:

El servidor nunca envía un formulario y nunca aprueba ni rechaza: nada de lo que responda el cliente puede decidir un pago, y la clave del agente no puede aprobar. Con el protocolo 2026-07-28, el cliente reintenta la llamada con los mismos argumentos después de la página; un reintento con otros argumentos falla con invalid_input (approval_state_mismatch).

Qué clientes abren la página, a 7 de octubre de 2026:

En todos los clientes, el agente puede mostrar approvalUrl al usuario y consultar get_approval_status. Algunos clientes cortan una llamada a una herramienta al cabo de un minuto más o menos, así que mantén BURNBOUND_APPROVAL_WAIT_MS por debajo del límite de tu cliente.

¿Cómo gestiona fetch_paid las redirecciones?

Antes del 402 se siguen las redirecciones al mismo origen, hasta 3. Una redirección a otro origen se devuelve tal cual, con redirectNotFollowed: true. Una redirección después de pagar tampoco se sigue: termina en un error payment_not_completed con redirectNotFollowed: true. Un pago nunca se envía a ningún sitio que no sea la URL que lo pidió.

¿Qué devuelve get_budget?

get_budget devuelve el presupuesto del agente para hoy. No recibe entrada y es de solo lectura; los agentes deberían llamarla antes de pagar algo.

Desde @burnbound/mcp 0.7.0, una organización puede fijar reglas de gasto para un subequipo (un grupo de sus agentes, ver Conceptos) o para toda la organización, y se aplican al agente además de las suyas: gana la más restrictiva. Entonces effectiveCap también las cuenta y, cuando una de ellas lo marca, effectiveCap.scope es team u org (limitedBy sigue siendo rule). scopeLimits enumera esas reglas con la misma forma que ruleLimits, más scope, con las cifras del grupo en el que caen los pagos del agente (su subequipo, su persona, él mismo o todo el ámbito); no aparece cuando no hay ninguna. El agente nunca recibe el id ni el nombre del subequipo. Solo un owner o un admin de la organización puede cambiar una regla de subequipo o de organización, en el panel.

Los agentes nuevos empiezan con una regla de este tipo, tope-semanal: el gasto total del agente por semana UTC (de lunes a domingo) no puede pasar de 5 veces su tope diario. Es una regla normal que una persona puede cambiar o borrar en el panel, y no sigue los cambios posteriores del tope diario.

¿Qué hace propose_rule?

propose_rule añade una regla de gasto que solo restringe los pagos del propio agente, cuando el usuario la pide en la conversación, por ejemplo "no gastes más de 2 USD al día en api.dune.com". No es de solo lectura, pero nunca puede ampliar lo que el agente puede pagar. Disponible desde @burnbound/mcp 0.5.0.

El resultado tiene ruleId (chat- y 8 caracteres hexadecimales), expiresAt y un message fijo. Burnbound lo decide todo por su lado: la regla está en vigor, es solo de este agente y nunca pide una aprobación; un deny necesita una condición; como mucho se aplican a la vez 10 reglas propuestas desde el chat, y un agente puede proponer 20 por hora. Una regla idéntica a otra activa no se vuelve a añadir. No hay forma de cambiar, alargar ni borrar una regla desde el chat, ni siquiera una que haya propuesto el agente: solo puede hacerlo una persona, en el panel de Burnbound, y cada regla añadida así queda en la auditoría (policy.chat_rule_added). Los errores son los de cualquier herramienta, más rule_rejected (reason, fields) y rule_limit_reached (max).

¿Qué devuelve list_payments?

list_payments devuelve los pagos más recientes del agente, del más nuevo al más antiguo. Es de solo lectura.

El resultado es { agentId, payments }. Cada pago tiene intentId, status, amountUsd, network, asset, host, transactionHash (una vez liquidado) y createdAt. Devuelve el host al que se pagó, no la URL completa.

¿Qué devuelve get_approval_status?

get_approval_status le dice al agente si una persona ha decidido sobre un pago que necesitaba aprobación. Recibe el approvalId de un resultado pending_approval y es de solo lectura.

Devuelve approvalId, status (pending, approved, denied o expired), intentId (presente cuando ya se hizo el pago aprobado), amountUsd, host, createdAt, decidedAt y expiresAt. Una clave de agente solo ve las aprobaciones de su propio agente; cualquier otro id da approval_not_found.

¿Qué devuelve search_paid_apis?

search_paid_apis busca en el catálogo de APIs x402 verificadas de Burnbound y dice, para cada una, si fetch_paid la pagaría bajo la política del agente. Es de solo lectura. Disponible desde @burnbound/mcp 0.3.0. Las personas pueden explorar el mismo catálogo en /apis (en inglés), con una página por API.

El resultado es { agentId, query, total, results }. Cada resultado tiene:

El catálogo nunca amplía por sí solo lo que un agente puede pagar. Un agente sin política también recibe resultados, cada uno con policyBlockers: ["no_policy"]: no puede pagar a nadie hasta que se configure su política en el panel. Un resultado con host_not_allowed sigue bloqueado en fetch_paid hasta que una persona añada el host a los hosts permitidos del agente o active su regla de hosts del catálogo (allowCatalogHosts): entonces un vendedor listado queda permitido con requiresApproval: true, porque su primer pago siempre espera a una persona. Con la regla de solo vendedores verificados (verifiedSellersOnly), policyBlockers también lleva seller_not_verified o pay_to_not_verified (ver Conceptos). El orden de los resultados solo usa el texto propio de Burnbound, la política del agente, la fiabilidad medida, la frescura y el precio; no hay posiciones de pago.

¿Qué devuelve diagnose_payment?

diagnose_payment explica por qué falla el pago de una URL: una frase con la causa y qué hacer, el error que devolvería fetch_paid y un informe que una persona puede pegar en un reporte de errores. Nunca firma ni paga, no toca el presupuesto del agente y se declara al cliente MCP como de solo lectura. Disponible desde @burnbound/mcp 0.4.0. El agente debería llamarla cuando fetch_paid falla con invalid_payment_required, no_payable_entry, resource_mismatch, insufficient_funds o payment_rejected_by_seller.

Pide la URL una vez, sin cabecera de pago y con las mismas protecciones que fetch_paid (solo https://, direcciones privadas bloqueadas, solo redirecciones al mismo origen). Lee el 402 y, cuando conoce una cartera, su saldo en USDC desde el RPC de la red del pago (BURNBOUND_BASE_RPC_URL, BURNBOUND_BASE_SEPOLIA_RPC_URL). La URL solo va al vendedor y la dirección de la cartera solo al RPC. A la API de Burnbound solo se le pide la cartera registrada del agente y sus reglas (una lectura de su presupuesto), y nunca se le dice la URL.

Las comprobaciones se hacen en el orden en que las aplica fetch_paid, así que la causa es el primer error con el que se toparía un intento real:

El resultado tiene status (problem o no_problem_found), summary (la causa y qué hacer), explanation, action, cause (code, reasons, fetchPaidError; null cuando no se encontró ningún problema), warnings, request (método, URL sin la query string, estado HTTP, versión de x402), resourceHost, accepts (cada opción de pago y si Burnbound puede pagarla), wallet (dirección, de dónde salió, saldo, importe necesario, host del RPC), chatRules (reglas propuestas desde el chat que pueden bloquear o limitar un pago a ese host), ruleBlocks (desde la 0.5.0: las reglas de límite del agente que rechazarían ahora este pago, porque dejan menos que su precio o ningún pago; cada una identificada por ruleId, con limit, lo que deja y resetsAt) e issueReport, un informe en Markdown sin la query string y con la cartera abreviada. Una regla en ruleBlocks hace que status sea problem aunque el 402 en sí esté bien, y entonces doctor sale con 2.

Los warnings nunca bloquean un pago: no_wallet, balance_not_checked, instruction_like_text (el texto del 402 parece dar instrucciones a un agente), mixed_mainnet_testnet, x402_version_mismatch y some_entries_unpayable.

No vuelve ningún texto del vendedor: la descripción y el error del 402 se descartan, y cualquier campo del vendedor que no sea un token simple aparece como [unreadable]. Los errores son los de cualquier herramienta, más invalid_input (https_required, invalid_url, contains_credential, invalid_wallet) y private_address_blocked.

¿Qué errores puede devolver una herramienta?

Los errores vuelven como un error de herramienta MCP cuyo contenido es {"error": {"code", "message", …}}. El código es estable; el mensaje es un texto fijo escrito por el servidor, nunca copiado de la API de Burnbound ni del vendedor. Los campos adicionales son solo ids, importes y códigos que el servidor ha validado, y texto que el servidor escribe a partir de ellos (summary). La única excepción es sellerReason, las palabras del propio vendedor, que siempre llega delimitado y etiquetado como no fiable (igual que las descripciones de los vendedores en search_paid_apis).

{
  "error": {
    "code": "policy_denied",
    "message": "The agent's spending policy denied this payment, so nothing was paid. See reasons.",
    "reasons": ["daily_cap_exceeded"],
    "policyVersion": 4
  }
}

Cualquier herramienta:

Entre los motivos de invalid_input de fetch_paid están https_required, invalid_url, url_credentials, burnbound_api_url (la URL es la propia API de Burnbound), contains_credential (la entrada contiene la clave de Burnbound o una clave de cartera), body_not_allowed, body_too_large, too_many_headers, invalid_header, reserved_header, invalid_max_amount, y approval_state_mismatch o invalid_approval_state (un reintento después de la página de aprobación que no coincide con la llamada retenida).

fetch_paid, no se envió nada:

fetch_paid, no se pagó nada:

hint es un texto fijo junto a reasons, para una denegación que solo puede resolver una persona. member_cap_exceeded: el agente pertenece a una persona de la organización, y esa persona alcanzó su subtope diario sumando todos sus agentes, o todavía no tiene ninguno. El agente no debería reintentarlo hoy; una persona le pide a un admin de la organización que fije o suba el subtope. get_budget muestra el subtope en member. rule_denied y rule_limit_exceeded: una regla de gasto que se aplica al agente, nombrada en rules, rechazó el pago. Desde la 0.7.0, ruleScopes dice de quién es cada regla (agent, team para su subequipo, u org) cuando la API la nombra; un pending_approval retenido por una regla (reason: "rule") lleva los mismos dos campos. get_budget muestra lo que deja cada regla de límite (ruleLimits, y scopeLimits para el subequipo y la organización) y cuándo se reinicia; solo una persona puede cambiar una regla, en el panel.

Con una regla del catálogo activada, la API lee el catálogo antes de decidir. Si no puede, no decide nada y responde catalog_unavailable, que fetch_paid informa como api_unavailable: reintenta más tarde. Sin ninguna regla del catálogo, la API sigue adelante sin el catálogo cuando no puede leerlo, y una dirección de cobro a la que la organización no ha pagado antes espera aprobación (new_pay_to).

insufficient_funds sale de una comprobación de saldo que la API de Burnbound hace antes de reservar o firmar nada, cuando tiene un RPC para la red del pago y conoce la dirección de la cartera que paga. summary dice, por ejemplo, Wallet 0x1234…5678 has 0.00 USDC on Base; this payment needs 0.01 USDC. Nothing was signed or paid. Añade USDC a esa cartera en esa red y vuelve a llamar a fetch_paid. La comprobación es orientativa: el saldo puede cambiar entre la comprobación y la liquidación del vendedor, así que un pago que la pasa todavía puede ser rechazado por el vendedor. Si el RPC falla, la API se salta la comprobación y sigue adelante.

fetch_paid con firma en el cliente, no se pagó nada:

fetch_paid, después de pagar:

sellerReason es la explicación del propio vendedor, leída de su cabecera PAYMENT-RESPONSE o PAYMENT-REQUIRED o de su cuerpo de error JSON, por ejemplo Facilitator validation failed: Invalid payment. Es texto de terceros: en el resultado de la herramienta llega en un bloque aparte, delimitado y etiquetado como no fiable, nunca en message, y structuredContent lo lleva como sellerReason: { untrusted: true, text }. En ambos casos, fetch_paid informa a Burnbound del recibo como fallido, con el estado y el motivo del vendedor, así que el registro del pago y el registro de auditoría guardan lo que salió mal. Un recibo fallido no libera el tope diario: el pago cuenta hasta que caduca sin liquidarse.

¿Qué comandos de cartera hay?

La CLI wallet gestiona la cartera local que se usa para la firma en el cliente. Ejecútala con npx -y @burnbound/mcp@latest wallet <command>; nunca arranca el servidor MCP. La clave privada se guarda en el llavero de macOS, en el Secret Service de Linux (GNOME Keyring, KWallet) cuando hay un bus de sesión disponible o, si no, en un fichero dentro de ~/.burnbound/wallets/ (directorio 0700, fichero 0600).

Opciones:

• --profile <name>: perfil de la cartera. Por defecto, BURNBOUND_WALLET_PROFILE o, si no, default. Usa un perfil por agente.
• --backend <kind>: para init e import, el almacenamiento: macos-keychain, secret-service o file. El almacenamiento se elige una vez, en init; las ejecuciones siguientes nunca recurren a otro. En Windows solo está disponible file, y es experimental.

npx -y @burnbound/mcp@latest wallet init
npx -y @burnbound/mcp@latest wallet address

¿Cómo compruebo desde una terminal un pago que falla?

doctor hace las mismas comprobaciones que diagnose_payment desde una terminal. No necesita cuenta de Burnbound, ni clave, ni cliente MCP, nunca llama a la API de Burnbound y nunca firma ni paga.

npx -y @burnbound/mcp@latest doctor https://api.example.com/paid --wallet 0xYourWallet

Imprime la causa, qué hacer, los avisos que haya y un informe para pegar en una incidencia, sin la query string y con la cartera abreviada.