Bitroad

Mercado para agentes de IA: compra bienes y servicios bajo límites de gasto, con devoluciones y disputas.

Documentación

Servidor MCP de Bitroad

Bitroad es un mercado construido para agentes de IA. Tu agente busca en un catálogo de bienes y servicios, realiza pedidos bajo los límites de gasto que tú estableces, rastrea la entrega, y gestiona devoluciones y disputas, todo a través del Protocolo de Contexto de Modelos (MCP).

Endpoint: https://app.bitroad.ai/api/v1/mcp

El transporte es HTTP Streamable compatible con la especificación y JSON-RPC 2.0. La autenticación es OAuth 2.1 con registro dinámico de clientes y PKCE, por lo que la mayoría de los clientes solo necesitan la URL anterior.

Sitio web: https://bitroad.ai
Documentación: https://bitroad.ai/docs
Registro: https://buy.bitroad.ai/sign-up

Cómo funciona

Crea una cuenta de comprador en buy.bitroad.ai.
Añade el endpoint a tu cliente MCP y aprueba la pantalla de consentimiento.
Tu agente ahora puede navegar y leer pedidos de inmediato.
Para permitirle gastar, añade una tarjeta y establece límites de delegación en tu panel de control. Hasta que lo hagas, no existe ninguna vía de compra.

El gasto está limitado por tres topes que tú controlas: por transacción, por día y total. Una compra que supere cualquier tope se rechaza de plano, con un motivo de per_tx_cap_exceeded, daily_cap_exceeded o total_cap_exceeded. Por separado, puedes establecer un umbral de confirmación: una compra igual o superior a él se permite pero devuelve confirmation_required con un token, y necesita tu aprobación explícita antes de continuar. Los agentes nunca ven los datos de la tarjeta; una tarjeta solo puede ser añadida por ti a través del pago alojado de Stripe.

Conecta tu cliente

Hay tres formatos. Elige el que coincida con tu cliente.

Clientes CLI

# Claude Code
claude mcp add --transport http bitroad https://app.bitroad.ai/api/v1/mcp

# Gemini CLI
gemini mcp add --transport http bitroad https://app.bitroad.ai/api/v1/mcp

Ejecuta el cliente y activa el flujo OAuth (/mcp en Claude Code, automático en Gemini CLI), luego aprueba en la pantalla de consentimiento de Bitroad.

Clientes con archivo de configuración

Cursor, Claude Desktop, Cline, Windsurf, LibreChat y la mayoría de los otros clientes MCP aceptan un bloque JSON:

{
  "mcpServers": {
    "bitroad": {
      "url": "https://app.bitroad.ai/api/v1/mcp"
    }
  }
}

El cliente descubre OAuth en el primer uso.

Clientes con interfaz de conectores

Claude.ai (Configuración, luego Conectores), ChatGPT (conectores personalizados en modo desarrollador) y Copilot aceptan el endpoint como una URL pegada:

Abre la configuración de conectores del cliente.
Añade un conector con la URL https://app.bitroad.ai/api/v1/mcp.
Aprueba la pantalla de consentimiento de Bitroad cuando se te solicite.

Clave Bearer en lugar de OAuth

Para clientes sin interfaz y tu propio código de agente, genera una clave de agente en /buyer/instances/new y envíala como encabezado:

curl https://app.bitroad.ai/api/v1/mcp \
  -H "Authorization: Bearer br_ik_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Las claves se muestran una sola vez. Revócalas desde la misma página.

Catálogo de herramientas

Llama a tools/list para obtener el catálogo en vivo con el JSON Schema completo. tools/list devuelve el catálogo completo a cada llamador; tu tipo de cuenta se aplica cuando se llama a una herramienta, no cuando se lista. Comprador y vendedor son tipos de cuenta separados y un correo electrónico solo puede ser uno de ellos, por lo que un comprador que llame a una herramienta seller_* es rechazado.

Herramientas de comprador

Grupo	Herramientas
Catálogo	`catalog_search_products`, `catalog_get_product`, `catalog_list_categories`, `catalog_describe_category`
Compra	`purchase_create_intent`, `purchase_confirm_intent`, `purchase_cancel_intent`
Pedidos	`orders_list`, `orders_get`
Devoluciones	`returns_initiate`, `returns_get`, `returns_list`, `returns_get_label`
Disputas	`disputes_file`, `disputes_list`, `disputes_get`, `disputes_add_evidence`, `disputes_withdraw`, `disputes_respond`
Reputación	`sellers_get`, `platforms_get`
Cuenta	`addresses_list`, `addresses_create`, `payment_methods_list`, `payment_methods_create`, `auth_whoami`, `auth_revoke_self`

Herramientas de vendedor

Listados, inventario, pedidos, envío y seguimiento, devoluciones y respuestas a reseñas, bajo el prefijo seller_*.

Servicios

Un mercado basado en cotizaciones para trabajo en lugar de bienes, bajo el prefijo services_*: solicita una cotización, acéptala, y los fondos se mantienen en depósito hasta que aceptes el entregable.

El catálogo también incluye envelopes_list y envelopes_get, una superficie de vista previa que está desactivada en el servicio alojado. Aparecen en tools/list pero devuelven un error de no encontrado cuando se les llama.

Comprar un producto es un flujo de dos pasos. purchase_create_intent reserva inventario y captura el precio, el IVA y el envío, luego purchase_confirm_intent cobra y crea el pedido. Las intenciones caducan después de 15 minutos. Todos los valores monetarios son peniques enteros.

Idempotencia

Las herramientas de escritura aceptan un _meta.idempotencyKey opcional. Pasar uno te da semántica completa de repetición en reintentos. Si tu cliente no puede configurarlo, el servidor genera uno para que la llamada aún tenga éxito.

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {
    "name": "purchase_create_intent",
    "arguments": { "product_id": "...", "quantity": 1 },
    "_meta": { "idempotencyKey": "intent-abc-123" }
  }
}

Registro

Este repositorio contiene el registro server.json publicado en el registro oficial de MCP bajo el espacio de nombres ai.bitroad.

Soporte

Abre un problema aquí.