特徴

• 🤖 マルチAPIチャット: OpenAI Chat Completions、Anthropic Messages、OpenAI Responses互換のエンドポイントに対応
• 🖼️ マルチモーダル生成: テキストチャットに加え、画像・動画生成(テキストから、画像から、先頭/末尾フレーム、参照アセット)の非同期タスクに対応
• 🔍 モデル・アカウント情報の取得: 利用可能なモデルの一覧、モデル詳細、アカウント残高、使用量・請求の詳細、チャージ履歴を取得
• 🔑 ヘッダー経由のキー渡し: 各呼び出しはリクエストヘッダーからAPIキーを読み取るため、1つのデプロイを複数アカウントで共有できます — サーバー側でキーを保存・キャッシュすることはありません

クイックスタート

Claude Codeでの利用を推奨します。-s userを追加すると、ユーザースコープで登録されます(すべてのプロジェクトで利用可能)。

ステップ1: 接続を追加する

コピーclaude mcp add --transport http basicrouter https://api.basicrouter.ai/mcp \
  --header "X-Basicrouter-Api-Key: <your BasicRouter API key>" \
  -s user

ステップ2: 接続を確認する

コピーclaude mcp list          # should show ✓ Connected
claude mcp get basicrouter  # should show Scope: User config (available in all your projects)

ステップ3: 使ってみる

Claudeに次のように話しかけてみてください。

• 「BasicRouterを使ってclaude-sonnet-5を呼び出し、秋についての詩を書いて」
• 「私のBasicRouterアカウントで利用可能なモデルを一覧表示して」
• 「私のBasicRouterの残高と最近の使用量を確認して」
• 「BasicRouterを使ってサイバーパンクな夜の都市の画像を生成して」

Claudeは自動的に対応するMCPツールを呼び出し、結果を返します。

Claude Desktopで使う

mcpServersセクションに以下を追加してください。

コピー{
  "mcpServers": {
    "basicrouter": {
      "type": "http",
      "url": "https://api.basicrouter.ai/mcp",
      "headers": {
        "X-Basicrouter-Api-Key": "<your BasicRouter API key>"
      }
    }
  }
}

Codex CLIで使う

推奨: env_http_headersを使い、環境変数からキーを読み込む方法

まずシェルで環境変数をエクスポートします。

コピーexport BASICROUTER_API_KEY=<your BasicRouter API key>

次に~/.codex/config.tomlに以下を記述します。

コピー[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
env_http_headers = { "X-Basicrouter-Api-Key" = "BASICROUTER_API_KEY" }

別の方法: http_headersを使い、キーを設定ファイルに直接書き込む方法(専用の環境変数を管理したくない場合に便利ですが、キーが設定ファイルに平文で保存される点に注意してください)

コピー[mcp_servers.basicrouter]
url = "https://api.basicrouter.ai/mcp"
http_headers = { "X-Basicrouter-Api-Key" = "<your BasicRouter API key>" }

Codexの設定UIから追加する場合:

• タイプ: HTTP / Streamable HTTP
• 名前: basicrouter
• URL：https://api.basicrouter.ai/mcp
• ヘッダー名: X-Basicrouter-Api-Key
• ヘッダー値: あなたのBasicRouter APIキー

接続を確認する

Codex CLIを起動後、/mcp コマンドで設定済みのMCPサーバーとその接続状態が一覧表示されます — 正しく読み込まれているか確認するだけです。使い方はClaudeと同じで、 Codexが自動的に適切なツールを選択します。

設定ファイルに他のMCPサーバーが既に登録されている場合は、同じ階層に追記してください。編集後はClaude Desktopを完全に終了して再起動してください。

ツール

このMCPサーバーは14個のツールを提供し、5つのカテゴリーに分類されています。

1. チャット

1. chat_completion — Chat Completions

一度の対話リクエストを送信し、モデルの完全な返信を返します（ストリーミング非対応）。テキストだけでなく、画像と動画を渡してマルチモーダル理解も可能です（モデルが対応する vision/video 能力をサポートしている必要あり — list_models で input_modalities を確認）——メッセージの content を文字列からコンテンツブロック配列に変更し、text と image_url / video_url を混在させます。

マルチモーダル入力（text / image / video）

画像入力（URL 方式）：

コピー{"role": "user", "content": [
  {"type": "text", "text": "この画像に何が写っていますか？"},
  {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
]}

画像入力（Base64 方式）：

コピー{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,<BASE64_STRING>"}}

対応画像形式：PNG、JPEG、GIF（先頭フレームのみ）、WebP。 1 枚の画像サイズ上限 20MB。

注意：大きな画像の Base64 文字列は非常に長くなり、リクエストボディ超過で 失敗する可能性があります。URL 方式の使用を推奨します。

detail パラメータ（任意、image_url オブジェクトに設定）が画像処理精度を制御："auto"（デフォルト、モデルが画像サイズで自動決定）/ "low"（512x512 サムネイル、高速・低消費、単純分類向け）/ "high"（フル解像度、小字読取・細部分析向け）。1 メッセージの content 配列に複数の image_url ブロックを置いて複数画像を渡せます。

動画入力（URL）：

コピー{"role": "user", "content": [
  {"type": "text", "text": "この動画の内容を説明してください。"},
  {"type": "video_url", "video_url": {"url": "https://example.com/video.mp4"}}
]}

動画入力（Base64）：

コピー{"type": "video_url", "video_url": {"url": "data:video/mp4;base64,<BASE64_STRING>"}}

BasicRouter で video 入力をサポートするモデルには Qwen、Doubao（dola-seed）、Kimi、MiniMax シリーズの一部モデルが含まれます。詳細は list_models が返す input_modalities で確認してください。 OpenAI 公式 Chat Completions 標準は動画をネイティブサポートしませんが、BasicRouter ゲートウェイは

コピー{"type": "video_url", "video_url": {"url": "..."}}

拡張形式で動画入力をサポートします。この形式は OpenRouter、NVIDIA NIM、vLLM などの video_url 形式と一致します。

2. create_message — Anthropic Messages互換

Anthropic Messages 互換インターフェースを呼び出します（ストリーミング非対応）。コンテンツブロックは text、image、tool_use、tool_result、thinking、redacted_thinking をサポート。画像は

コピー{"type": "image", "source": {...}}

コンテンツブロックで渡します。

マルチモーダル入力（text / image / video）

画像入力は 3 種類の source タイプをサポート：

1. Base64 エンコード（注意：data フィールドは純 Base64 文字列で、data: プレフィックスを含まない）。media_type は image/jpeg、image/png、image/gif、image/webp をサポート：

コピー{"type": "image", "source": {
  "type": "base64",
  "media_type": "image/jpeg",
  "data": "<BASE64_STRING>"
}}

2. URL 参照：

コピー{"type": "image", "source": {
  "type": "url",
  "url": "https://example.com/image.jpg"
}}

3. File ID（事前に Files API で purpose="vision" で画像をアップロードし file_id を取得）：

コピー{"type": "image", "source": {
  "type": "file",
  "file_id": "<file_id>"
}}

1 メッセージの content 配列に複数の image ブロックを置いて複数画像を渡せます。

注意：大きな画像の Base64 文字列は非常に長くなり、リクエストボディ超過で 失敗する可能性があります。URL 方式の使用を推奨します。

動画入力：Anthropic Messages API は動画ファイルをサポートしません。動画理解が必要な場合は ffmpeg 等でキーフレームを抽出し、各フレームを image コンテンツブロックとして渡してください。BasicRouter で動画入力をサポートするモデル（list_models で input_modalities に video が含まれるか確認）の場合は chat_completion または create_response インターフェースを使用してネイティブ動画サポートをご利用ください。

3. create_response — OpenAI Responses互換

messages の代わりに input を、システムメッセージの代わりに instructions を、response_format の代わりに text.format を使います。テキストだけでなく、画像と動画を渡してマルチモーダル理解も可能です（モデルが対応する vision/video 能力をサポートしている必要あり — list_models で input_modalities を確認）——input をメッセージオブジェクト配列にし、content をコンテンツブロック配列でテキストと画像/動画を混在させます。

マルチモーダル入力（text / image / video）

注意：Responses API のコンテンツブロック型は input_text / input_image / input_video を使い（Chat Completions の text / image_url / video_url ではなく）、image_url / video_url はネストオブジェクトではなく直接文字列です。

画像入力（URL 方式）：

コピー[{"role": "user", "content": [
  {"type": "input_text", "text": "この画像に何が写っていますか？"},
  {"type": "input_image", "image_url": "https://example.com/image.jpg"}
]}]

画像入力（Base64 方式）：

コピー{"type": "input_image", "image_url": "data:image/jpeg;base64,<BASE64_STRING>"}

対応画像形式：PNG、JPEG、GIF（先頭フレームのみ）、WebP。 1 枚の画像サイズ上限 20MB。

注意：大きな画像の Base64 文字列は非常に長くなり、リクエストボディ超過で 失敗する可能性があります。URL 方式の使用を推奨します。

画像入力（File ID 方式）：

コピー{"type": "input_image", "file_id": "<file_id>"}

file_id は Files API で purpose="vision" で画像をアップロードして取得します。

detail パラメータ（任意、input_image オブジェクトに設定）が画像処理精度を制御："auto"（デフォルト）/ "low"（512x512 サムネイル、高速・低消費）/ "high"（フル解像度、小字読取・細部分析向け）/ "original"（原始解像度、一部の新モデルのみ対応）。1 メッセージの content 配列に複数の input_image ブロックを置いて複数画像を渡せます。

動画入力（URL）：

コピー[{"role": "user", "content": [
  {"type": "input_text", "text": "この動画の内容を説明してください。"},
  {"type": "input_video", "video_url": "https://example.com/video.mp4"}
]}]

動画入力（Base64）：

コピー{"type": "input_video", "video_url": "data:video/mp4;base64,<BASE64_STRING>"}

動画入力（File ID）：

コピー{"type": "input_video", "file_id": "<file_id>"}

BasicRouter で video 入力をサポートするモデルには Qwen、Doubao（dola-seed）、Kimi、MiniMax シリーズの一部モデルが含まれます。詳細は list_models が返す input_modalities で確認してください。 OpenAI 公式 Responses API 標準は動画をネイティブサポートしませんが、BasicRouter ゲートウェイは

コピー{"type": "input_video", "video_url": "..."}

拡張形式で動画入力をサポートします。この形式は BytePlus/Volcengine などの input_video 形式と一致します。

2. モデル・アカウント

4. list_models — 利用可能なモデルの一覧

現在のアカウントで利用可能なモデルを、ベンダー、モダリティ、機能、価格などのメタデータとともに返します。パラメータなし。リストの各項目に price_tiers 価格帯が含まれ、現在の呼び出し元の有効な課金価格（実際の課金と一致）を返します（価格帯フィールド説明を参照）。

5. get_model — 単一モデルの詳細を取得

出力に price_tiers 価格帯を含みます（価格帯フィールド説明を参照）。モデルが存在しない場合は 404 を返し、価格フィールドは含みません。

6. get_balance — アカウント残高の確認

現在のアカウントの使用量と残高を返します。パラメータなし。

3. 請求

7. list_usage — モデル使用量・請求の詳細

ページネーション対応のモデル使用量請求詳細を、注文作成時刻の降順で返します。通常の使用料のみで、チャージや調整は含みません。

8. list_transactions — チャージ・パッケージ購入の取引履歴

ページネーション対応の、支払い済みのチャージ/パッケージ購入取引履歴を、作成時刻の降順で返します。

4. 画像生成

9. list_image_models — 画像モデルの一覧

対応する画像生成モデルを、解像度、アスペクト比、最大画像数(maxCount)、最大参照画像数(fileMax)とともに返します。パラメータなし。画像を生成する前に必ず確認してください — ここで公開されている値のみ指定できます。リストの各項目に priceTiers 価格帯を含みます（価格帯フィールド説明を参照）。

10. create_image_generation — 画像生成タスクを送信

非同期で送信し、即座にtaskIdを返します。アカウントのクレジットを消費します。

11. get_image_generation — 画像タスクのポーリング

返却内容: statusはpending / success / failedのいずれか。imagesは画像URLのJSON文字列配列。 textにはモデルからの追加出力(例: Geminiのマルチモーダル出力)が含まれます。

5. 動画生成

12. list_video_models — 動画モデルの一覧

対応する動画生成モデルを、allowedVideoTypes、時間範囲(videoDurationMin/Max)、解像度、アスペクト比、参照アセット数の上限(fileMax)とともに返します。パラメータなし。動画を生成する前に必ず確認してください。リストの各項目に priceTiers 価格帯を含みます（価格帯フィールド説明を参照）。

13. create_video_generation — 動画生成タスクを送信

非同期で送信し、即座にtaskIdを返します。アカウントのクレジットを消費します。

video_typeの意味:

14. get_video_generation — 動画タスクのポーリング

価格帯フィールド説明

list_models、get_model、list_image_models、list_video_models の 4 つのモデル照会ツールの出力は、現在の呼び出し元（API Key ユーザー）の有効な課金価格を返し、実際の課金と完全に一致し、そのモデルのすべての価格帯を含みます。

命名の違い：list_models / get_model は OpenAI のスネークケース（price_tiers）に従い、list_image_models / list_video_models は camelCase（priceTiers）に従います。構造は全く同じです。

price_tiers / priceTiers は配列で、各要素は 1 つの価格帯です：

3 種のモデルタイプは同じ構造を共有し、説明フィールドの充填のみが異なり、該当しないフィールドは null です：

価格の意味：返される inputPrice / outputPrice / cacheReadPrice / cacheWritePrice 等は、価格チェーン（chain）→ guidance → 基準価格を段階的に解決した後の、現在の API Key ユーザー向けの最終課金単価で、実際の課金と一致します。呼び出し元が見る単価は、自身の価格チェーン（reseller / distributor / 企業 / ユーザー単位設定）により異なります。

実際の課金額 = 使用量 ÷ quantity × 該当単価 × ratio。動画の秒単位課金の場合、実際の課金 = duration × outputPrice × ratio。

境界と例外処理（読み取り専用インターフェースは価格設定の問題で 500 を返しません）：

レスポンス例（list_models、テキストモデル）：

コピー{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o",
      "object": "model",
      "display_name": "gpt-4o",
      "context_length": 128000,
      "description": "...",
      "price_tiers": [
        {
          "region": "GLOBAL",
          "bandMin": null,
          "bandMax": null,
          "resolution": null,
          "clarity": null,
          "unit": "token",
          "quantity": 1000,
          "description": "1K token あたり",
          "inputPrice": 0.0025,
          "outputPrice": 0.01,
          "cachePrice": 0.00125,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

レスポンス例（list_image_models、画像モデル、priceTiers は構造同上、unit は image）：

コピー{
  "object": "list",
  "data": [
    {
      "id": "dall-e-3",
      "object": "image_model",
      "displayName": "dall-e-3",
      "resolutions": ["1024x1024", "1792x1024", "1024x1792"],
      "priceTiers": [
        {
          "region": null,
          "bandMin": null,
          "bandMax": null,
          "resolution": "1024x1024",
          "clarity": "standard",
          "unit": "image",
          "quantity": 1,
          "description": "1 枚あたり",
          "inputPrice": 0,
          "outputPrice": 0.04,
          "cachePrice": 0,
          "cacheReadPrice": 0,
          "cacheWritePrice": 0,
          "ratio": 1,
          "mode": "RATIO",
          "planId": null
        }
      ]
    }
  ]
}

使用例

例1: シンプルなチャットリクエスト

質問例: 「BasicRouterを使ってclaude-sonnet-5を呼び出し、PythonのGILとは何か聞いて」

AIはchat_completionを次のように呼び出します。

コピー{
  "model": "claude-sonnet-5",
  "messages": [{"role": "user", "content": "What is Python's GIL?"}]
}

例2: Anthropic Messagesエンドポイントでのツール使用

質問例: 「BasicRouterのMessagesエンドポイントを使い、天気を確認するかどうかをモデルに判断させて」

AIはツール定義とtool_choiceを渡してcreate_messageを呼び出します。 レスポンスにはtool_useコンテンツブロックが含まれます。

例3: 利用可能なモデルの一覧表示

質問例: 「私のBasicRouterアカウントのモデルを一覧表示して」

AIはlist_modelsを呼び出し、利用可能なすべてのモデルのID、ベンダー、モダリティ、価格などを返します。

例4: 残高と使用量の確認

質問例: 「今月の私のBasicRouterの使用量を確認して」

AIは残高確認のためにget_balanceを呼び出し、続けて使用量の内訳のために list_usage(start_timeを今月に指定)を呼び出します。

例5: 画像の生成

質問例: 「BasicRouterを使ってサイバーパンクな夜の都市の画像を生成して」

AIはまずlist_image_modelsでスペックを確認し、次に create_image_generationを呼び出してtaskIdを取得し、その後 get_image_generationをポーリングして画像URLを取得します。

例6: テキストから動画を生成

質問例: 「BasicRouterを使って宇宙の星雲の5秒間の動画を生成して」

AIはまずlist_video_modelsでスペックを確認し、次に create_video_generation(video_type=1、duration=5)を呼び出し、 taskIdを取得した後にget_video_generationをポーリングします。

FAQ

ツール呼び出しが「missing BasicRouter API Key」で失敗する

• claude mcp addを--headerなしで実行した、またはキーが間違っている
• JSON設定ファイルを直接編集している場合、headersフィールド名が間違っている( X-Basicrouter-Api-Keyである必要があります)
• ローカル実行時にBASICROUTER_API_KEY環境変数が設定されていない

ツール呼び出しが「BasicRouter returned 401 unauthorized」で失敗する

APIキー自体が間違っているか、期限切れです — BasicRouterのコンソールで再生成してください。

ClaudeがBasicRouterのツールを呼び出さない場合は?

• claude mcp listで接続が✓ Connectedと表示されているか確認してください
• 接続状態を確認する: claude mcp get basicrouter
• 明示的に指示してみてください: 「BasicRouterのchat_completionツールを使って claude-sonnet-5を呼び出して…」

画像/動画生成がずっとpendingのままになる

• 画像タスクはget_image_generation、動画タスクはget_video_generation でポーリングしてください — なお、実行中の動画タスクのstatusは"running"であり、"pending"ではないことに注意してください
• 生成には時間がかかります。通常は数秒から数十秒、動画の場合はさらに長くなります
• callback_urlを指定していた場合、完了時にコールバックが呼び出されるため、ポーリングは不要です

list_image_models / list_video_modelsがエラーになる

どちらのツールもそれ自体はクレジットを消費しません — エラーは通常、キーまたはネットワークの問題を示しています。まず list_modelsが正常に動作するか確認してください。

注意事項

• ヘッダー名:MCPはX-Basicrouter-Api-Key経由でキーを渡します。
• クレジットの消費:chat_completion / create_message / create_response / create_image_generation / create_video_generationはすべてアカウントのクレジットを消費します — 事前に残高を確認したい場合は get_balanceを先に呼び出してください。
• 生成前にスペックを確認:model、resolution、ratio、count、duration、video_typeなどの画像/動画生成パラメータは、 list_image_models / list_video_modelsが公開している値のみ使用できます。 それ以外の値を指定するとエラーになります。
• ストリーミング非対応:3つのチャットエンドポイントはいずれもストリーミングに対応していません — 各エンドポイントは完全な結果を一度に返します。
• ステートレス設計:各リクエストは独立しており、セッションは保存されません。複数ターンの会話には create_responseの previous_response_idを使うか、messagesで 自分で履歴を管理してください。