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 diseñado para agentes de IA. Tu agente busca en un catálogo de bienes y servicios, realiza pedidos bajo los límites de gasto que establezcas, realiza un seguimiento de la entrega y gestiona devoluciones y disputas, todo a través del Protocolo de Contexto de Modelo.

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.
Agrega 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, agrega una tarjeta y establece límites de delegación en tu panel de control. Hasta que lo hagas, no existe ninguna ruta de compra.

El gasto está limitado por tres límites que controlas: por transacción, por día y total. Una compra que supere cualquier límite 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 detalles de la tarjeta; una tarjeta solo puede ser agregada por ti a través del pago alojado de Stripe.

Conecta tu cliente

Hay tres formas. Elige la 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 de OAuth (/mcp en Claude Code, automático en Gemini CLI), luego aprueba 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.
Agrega un conector con la URL https://app.bitroad.ai/api/v1/mcp.
Aprueba la pantalla de consentimiento de Bitroad cuando se te solicite.

Clave de portador 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 un 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.

Puente Stdio

Los clientes y rastreadores de directorios que solo hablan stdio pueden ejecutar el puente en este repositorio. Reenvía cada mensaje JSON-RPC al endpoint alojado sin cambios y no tiene dependencias más allá de Node 18+.

git clone https://github.com/bitroadai/bitroad-mcp && cd bitroad-mcp
BITROAD_API_KEY=br_ik_... node bin/bitroad-mcp.js

O con Docker:

docker build -t bitroad-mcp . && docker run -i -e BITROAD_API_KEY=br_ik_... bitroad-mcp

Como entrada de archivo de configuración:

{
  "mcpServers": {
    "bitroad": {
      "command": "node",
      "args": ["/path/to/bitroad-mcp/bin/bitroad-mcp.js"],
      "env": { "BITROAD_API_KEY": "br_ik_..." }
    }
  }
}

Sin BITROAD_API_KEY, el protocolo de enlace y tools/list aún funcionan; tools/call devuelve un error de autenticación que te indica que lo configures. BITROAD_MCP_URL anula el endpoint.

Catálogo de herramientas

Llama a tools/list para 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 llama a una herramienta de 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 llaman.

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 en peniques enteros.

Idempotencia

Las herramientas de escritura aceptan un _meta.idempotencyKey opcional. Pasarlo te brinda semántica completa de reproducció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í.