Bitroad

Bitroad MCP サーバー

Bitroad は AI エージェント向けに構築されたマーケットプレイスです。エージェントは商品やサービスのカタログを検索し、設定した利用上限の範囲内で注文し、配送状況を追跡し、返品や紛争に対応します。これらすべてを Model Context Protocol 経由で行います。

エンドポイント： https://app.bitroad.ai/api/v1/mcp

トランスポートは仕様に準拠した Streamable HTTP で、JSON-RPC 2.0 を使用します。認証は動的クライアント登録と PKCE に対応した OAuth 2.1 なので、ほとんどのクライアントでは上記の URL だけで利用できます。

• ウェブサイト： https://bitroad.ai
• ドキュメント： https://bitroad.ai/docs
• サインアップ： https://buy.bitroad.ai/sign-up

仕組み

1. buy.bitroad.ai で購入者アカウントを作成します。
2. エンドポイントを MCP クライアントに追加し、同意画面で承認します。
3. これでエージェントは、すぐに商品を閲覧し、注文を確認できるようになります。
4. 購入を許可するには、カードを追加し、ダッシュボードで委任の上限を設定します。設定するまでは、購入手段は一切ありません。

支出は、取引ごと、1 日あたり、合計の 3 つの上限によって制御されます。いずれかの上限を超える購入は、per_tx_cap_exceeded、daily_cap_exceeded、または total_cap_exceeded の理由で拒否されます。また、確認しきい値も設定できます。この金額以上の購入は許可されますが、confirmation_required とトークンが返され、処理を進めるにはユーザーによる明示的な承認が必要です。エージェントにカード情報が表示されることはありません。カードを追加できるのは、Stripe のホスト型チェックアウトを通じてユーザー自身が操作する場合のみです。

クライアントの接続

接続方法は 3 種類あります。お使いのクライアントに合った方法を選んでください。

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

クライアントを実行して 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 の同意画面で承認します。

OAuth の代わりにベアラーキーを使用する

ヘッドレスクライアントや独自のエージェントコードでは、/buyer/instances/new でエージェントキーを発行し、ヘッダーとして送信します。

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 を設定すると、エンドポイントを上書きできます。

ツールカタログ

ライブカタログと完全な JSON Schema を取得するには、tools/list を呼び出してください。tools/list はすべての呼び出し元にカタログ全体を返します。アカウントの種類は、ツールの呼び出し時に適用されるのであって、 一覧表示時ではありません。購入者と販売者は別々のアカウントの種類であり、1 つのメールアドレスを両方に使うことはできません。そのため、購入者が 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 には表示されますが、呼び出すと「見つかりません」というエラーが返されます。

商品の購入は 2 段階のフローです。purchase_create_intent は在庫を確保し、価格、VAT、送料をスナップショットとして保存します。続いて 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 を作成してください。