Bitroad

Marketplace para agentes de IA: compre bens e serviços com limites de gastos, com devoluções e disputas.

Documentação

Servidor MCP Bitroad

Bitroad é um marketplace construído para agentes de IA. Seu agente pesquisa um catálogo de produtos e serviços, faz pedidos dentro dos limites de gastos que você define, acompanha a entrega e lida com devoluções e disputas, tudo através do Model Context Protocol.

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

O transporte é Streamable HTTP compatível com a especificação, com JSON-RPC 2.0. A autenticação é OAuth 2.1 com registro dinâmico de clientes e PKCE, então a maioria dos clientes não precisa de nada além da URL acima.

Site: https://bitroad.ai
Documentação: https://bitroad.ai/docs
Cadastro: https://buy.bitroad.ai/sign-up

Como funciona

Crie uma conta de comprador em buy.bitroad.ai.
Adicione o endpoint ao seu cliente MCP e aprove a tela de consentimento.
Seu agente agora pode navegar e ler pedidos imediatamente.
Para permitir que ele gaste, adicione um cartão e defina limites de delegação no seu painel. Até que você faça isso, não existe nenhum caminho de compra.

Os gastos são limitados por três limites que você controla: por transação, por dia e total. Uma compra acima de qualquer limite é recusada imediatamente, com um motivo de per_tx_cap_exceeded, daily_cap_exceeded ou total_cap_exceeded. Separadamente, você pode definir um limite de confirmação: uma compra igual ou acima dele é permitida, mas retorna confirmation_required com um token, e precisa da sua aprovação explícita antes de prosseguir. Os agentes nunca veem os dados do cartão; um cartão só pode ser adicionado por você através do checkout hospedado da Stripe.

Conecte seu cliente

Existem três formatos. Escolha o que corresponde ao seu 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

Execute o cliente e acione o fluxo OAuth (/mcp no Claude Code, automático no Gemini CLI), depois aprove na tela de consentimento da Bitroad.

Clientes com arquivo de configuração

Cursor, Claude Desktop, Cline, Windsurf, LibreChat e a maioria dos outros clientes MCP aceitam um bloco JSON:

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

O cliente descobre o OAuth no primeiro uso.

Clientes com interface de conector

Claude.ai (Configurações, depois Conectores), ChatGPT (conectores personalizados no modo desenvolvedor) e Copilot aceitam o endpoint como uma URL colada:

Abra as configurações de conector do seu cliente.
Adicione um conector com a URL https://app.bitroad.ai/api/v1/mcp.
Aprove a tela de consentimento da Bitroad quando solicitado.

Chave de portador em vez de OAuth

Para clientes headless e seu próprio código de agente, gere uma chave de agente em /buyer/instances/new e envie-a como um cabeçalho:

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"}'

As chaves são exibidas apenas uma vez. Revogue-as na mesma página.

Catálogo de ferramentas

Chame tools/list para o catálogo ao vivo com o JSON Schema completo. tools/list retorna o catálogo inteiro para todos os chamadores; seu tipo de conta é aplicado quando uma ferramenta é chamada, não quando é listada. Comprador e vendedor são tipos de conta separados e um e-mail só pode ser um deles, então um comprador chamando uma ferramenta seller_* é recusado.

Ferramentas do comprador

Grupo	Ferramentas
Catálogo	`catalog_search_products`, `catalog_get_product`, `catalog_list_categories`, `catalog_describe_category`
Compras	`purchase_create_intent`, `purchase_confirm_intent`, `purchase_cancel_intent`
Pedidos	`orders_list`, `orders_get`
Devoluções	`returns_initiate`, `returns_get`, `returns_list`, `returns_get_label`
Disputas	`disputes_file`, `disputes_list`, `disputes_get`, `disputes_add_evidence`, `disputes_withdraw`, `disputes_respond`
Reputação	`sellers_get`, `platforms_get`
Conta	`addresses_list`, `addresses_create`, `payment_methods_list`, `payment_methods_create`, `auth_whoami`, `auth_revoke_self`

Ferramentas do vendedor

Listagens, estoque, pedidos, envio e rastreamento, devoluções e respostas a avaliações, sob o prefixo seller_*.

Serviços

Um marketplace baseado em cotações para trabalho, em vez de produtos, sob o prefixo services_*: solicite uma cotação, aceite-a, e os fundos ficam retidos em garantia até você aceitar a entrega.

O catálogo também contém envelopes_list e envelopes_get, uma superfície de pré-visualização que está desativada no serviço hospedado. Elas aparecem em tools/list mas retornam um erro de não encontrado quando chamadas.

Comprar um produto é um fluxo de duas etapas. purchase_create_intent reserva o estoque e congela o preço, o IVA e o frete, depois purchase_confirm_intent cobra e cria o pedido. As intenções expiram após 15 minutos. Todos os valores monetários são em centavos inteiros.

Idempotência

As ferramentas de escrita aceitam um _meta.idempotencyKey opcional. Enviar um oferece a você semântica completa de repetição em novas tentativas. Se o seu cliente não puder defini-lo, o servidor gera um para que a chamada ainda seja bem-sucedida.

{
  "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 repositório contém o registro server.json publicado no registro oficial do MCP sob o namespace ai.bitroad.

Suporte

Abra uma issue aqui.