Bitroad

Bitroad MCP 服务

Bitroad 是一个专为 AI Agent 打造的交易平台。你的 Agent 可以搜索商品和服务目录，在你设定的支出上限内下单、跟踪配送，并处理退货和争议，所有操作都通过 Model Context Protocol 完成。

端点： https://app.bitroad.ai/api/v1/mcp

传输方式采用符合规范的 Streamable HTTP 和 JSON-RPC 2.0。身份验证使用 OAuth 2.1，并支持动态客户端注册和 PKCE，因此大多数客户端只需使用上述 URL。

• 网站：https://bitroad.ai
• 文档：https://bitroad.ai/docs
• 注册：https://buy.bitroad.ai/sign-up

工作原理

1. 在 buy.bitroad.ai 创建买家账号。
2. 将端点添加到你的 MCP 客户端，并批准授权页面。
3. 你的 Agent 随后即可浏览商品并查看订单。
4. 如需允许其消费，请添加银行卡并在控制面板中设置委托消费上限。在此之前，完全无法购买。

消费金额受你控制的三项上限约束：单笔、每日和总额。超出任一上限的购买都会被直接拒绝，并返回原因 per_tx_cap_exceeded、daily_cap_exceeded 或 total_cap_exceeded。此外，你还可以设置确认门槛：达到或超过该门槛的购买会获准，但将返回 confirmation_required 和一个令牌，必须经你明确确认后才能继续。Agent 永远看不到银行卡详细信息；只能由你通过 Stripe 托管结账页面添加银行卡。

连接客户端

有三种方式，请选择与你的客户端匹配的方式。

命令行客户端

# 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

运行客户端并触发 OAuth 流程（在 Claude Code 中使用 /mcp，Gemini CLI 中则会自动触发），然后在 Bitroad 授权页面批准。

配置文件客户端

Cursor、Claude Desktop、Cline、Windsurf、LibreChat 和大多数其他 MCP 客户端都接受 JSON 代码块：

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

客户端会在首次使用时发现 OAuth。

连接器 UI 客户端

Claude.ai（依次进入 Settings 和 Connectors）、ChatGPT（开发者模式下的自定义连接器）和 Copilot 支持粘贴端点 URL：

1. 打开客户端的连接器设置。
2. 添加连接器，URL 为 https://app.bitroad.ai/api/v1/mcp。
3. 出现提示时，在 Bitroad 授权页面批准。

使用 Bearer 密钥代替 OAuth

对于无头客户端和你自己的 Agent 代码，请在 /buyer/instances/new 创建 Agent 密钥，并将其作为标头发送：

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

密钥仅显示一次。你可以在同一页面撤销密钥。

Stdio 桥接

仅支持 stdio 的客户端和目录爬虫可以运行此代码库中的桥接程序。它会将每条 JSON-RPC 消息原样转发到托管端点，除 Node 18+ 外无需其他依赖。

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

也可以使用 Docker：

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

作为配置文件条目：

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

未设置 BITROAD_API_KEY 时，握手和 tools/list 仍可正常运行；tools/call 会返回身份验证错误，提示你进行设置。BITROAD_MCP_URL 可覆盖端点。

工具目录

调用 tools/list 获取包含完整 JSON Schema 的实时目录。tools/list 会向每位调用者返回整个目录；账户类型会在调用工具时验证，而不是在列出工具时验证。买家和卖家是不同的账户类型，一个邮箱只能属于其中一种，因此买家调用 seller_* 工具会被拒绝。

买家工具

分组	工具
商品目录	catalog_search_products、catalog_get_product、catalog_list_categories、catalog_describe_category
购买	purchase_create_intent、purchase_confirm_intent、purchase_cancel_intent
订单	orders_list、orders_get
退货	returns_initiate、returns_get、returns_list、returns_get_label
争议	disputes_file、disputes_list、disputes_get、disputes_add_evidence、disputes_withdraw、disputes_respond
信誉	sellers_get、platforms_get
账户	addresses_list、addresses_create、payment_methods_list、payment_methods_create、auth_whoami、auth_revoke_self

卖家工具

商品上架、库存、订单、配送和追踪、退货及评价回复，均以 seller_* 为前缀。

服务

这是一个按报价为工作而非商品提供交易的平台，工具以 services_* 为前缀：请求报价、接受报价，资金会托管，直到你接受交付成果。

目录还包含 envelopes_list 和 envelopes_get，这是一个预览功能，目前在托管服务上已关闭。它们会显示在 tools/list 中，但调用时会返回未找到错误。

购买商品分为两个步骤。purchase_create_intent 会预留库存并记录价格、增值税和配送费用，随后 purchase_confirm_intent 会收取费用并创建订单。购买意向会在 15 分钟后过期。所有金额均以整数便士表示。

幂等性

写入工具接受可选参数 _meta.idempotencyKey。传入该参数后，重试时会完整重放原操作。如果客户端无法设置该参数，服务端会自动生成一个，因此调用仍会成功。

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

注册表

此仓库包含发布到官方 MCP 注册表 ai.bitroad 命名空间下的 server.json 记录。

支持

请在此处提交 issue。