claude-openrouter-delegate-mcp

Anthropic ベースの Claude Code セッションから OpenRouter ベースの Claude Code セッションへタスクを委譲します。2 つのセッションが環境変数を共有することはありません。

Claude Code を OpenRouter に向けるということは、ANTHROPIC_* 変数をシェルにエクスポートすることを意味します。これらの変数はプロセス全体に影響するため、1 つのシェルは「Anthropic」か「OpenRouter」のどちらか一方であり、両方になることはありません。また、OpenRouter キーを保持するエクスポート済みの ANTHROPIC_AUTH_TOKEN は、1 つの迷子のサブプロセスから漏洩する可能性があります。

この MCP サーバーは、各委譲セッションを明示的に構築された環境を持つ子プロセスとして起動します。Opus セッションは自身の認証情報を保持し、委譲先は OpenRouter の認証情報を取得します。両者は同じターミナル内で並行して動作します。

┌────────────────────────────┐
│  Claude Code (Opus)        │   your session, Anthropic credentials
│                            │
│   └─ mcp: openrouter ──────┼──▶ spawn: claude -p   (fresh env)
└────────────────────────────┘         ANTHROPIC_BASE_URL=https://openrouter.ai/api
                                       ANTHROPIC_AUTH_TOKEN=sk-or-v1-…
                                       → deepseek/deepseek-v4-flash-0731

これは claude-ollama-delegate-mcp の兄弟プロジェクトです。こちらはローカルの Ollama サーバーに対して同じことを行います。ここでのすべてを形作る違いは、OpenRouter は実際に費用がかかり、400 以上のモデルを提供しているということです。そのため、このパッケージには API キーのパス、価格付きのモデルカタログ、ジョブごとのコストレポートが追加されています。

クイックスタート

# 1. an OpenRouter API key: https://openrouter.ai/keys
export OPENROUTER_API_KEY=sk-or-v1-...

# 2. register the server
claude mcp add openrouter --scope user -- npx -y claude-openrouter-delegate-mcp

# 3. restart your Claude Code session

その後、平易な言葉で委譲を依頼します:

delegate this to openrouter: summarise every exported symbol in src/

デフォルトでは、サーバーは明示的に依頼した場合のみ委譲します。オーケストレーターに独自の判断で決定させるには、委譲モードを参照してください。

Related MCP server: Ollama MCP Server

目次

• クイックスタート

• 仕組み

• 前提条件

• インストール

• API キー

• 設定

• 委譲モード

• モデルの選択

• コスト

• ツールリファレンス

• 運用

• ジョブ成果物

• トラブルシューティング

• 対応プラットフォーム

• セキュリティモデル

• 開発

仕組み

OpenRouter は、OpenAI 形式のエンドポイントに加えて Anthropic 互換の POST /v1/messages エンドポイントを公開しているため、Claude Code は正しいベース URL を指定すれば変更なしで通信できます。各委譲タスクは、それぞれのプロセス内で claude -p として実行され、以下の設定が適用されます:

ANTHROPIC_BASE_URL=https://openrouter.ai/api
ANTHROPIC_AUTH_TOKEN=<your OpenRouter key>
ANTHROPIC_DEFAULT_OPUS_MODEL=<model>
ANTHROPIC_DEFAULT_SONNET_MODEL=<model>
ANTHROPIC_DEFAULT_HAIKU_MODEL=<small model>
ANTHROPIC_SMALL_FAST_MODEL=<small model>
CLAUDE_CODE_SUBAGENT_MODEL=<model>
ANTHROPIC_CUSTOM_HEADERS=HTTP-Referer: …⏎X-Title: …
CLAUDE_CODE_MAX_OUTPUT_TOKENS=<clamped per model>

ベース URL は /api で終わります。これは Claude Code が自身で /v1/messages を追加するためです。ANTHROPIC_API_KEY ではなく ANTHROPIC_AUTH_TOKEN が使用されるのは、これが Authorization: Bearer <key> として送信され、OpenRouter が期待するスキームだからです。

子環境は、プラットフォームごとの小さな許可リストから構築されます。ANTHROPIC_*、CLAUDE_*、AWS_*、GOOGLE_*、AZURE_*、OPENAI_*、BEDROCK_*、VERTEX_*、または OPENROUTER_* に一致するものはすべて、OpenRouter の値が適用される前に削除されます。最後のプレフィックスは意図的なものです。委譲先はキーを ANTHROPIC_AUTH_TOKEN としてのみ必要とするため、委譲先が実行する他のツールが拾い上げる可能性のある別の名前でキーのコピーを受け取ることはありません。

委譲先はまた、--strict-mcp-config と MCP 設定なしで起動します。これにより起動が高速になり、このサーバーを再帰的に呼び出すことを防ぎます。

省略できない 2 つの詳細

出力トークンのクランプ。 Claude Code はすべてのリクエストで max_tokens: 32000 を要求します。多くの OpenRouter モデルはより低い上限を持ち（amazon/nova-micro-v1 は 5120 を許可）、リクエストを拒否します。サーバーはカタログから top_provider.max_completion_tokens を読み取り、CLAUDE_CODE_MAX_OUTPUT_TOKENS を選択したモデルが実際に受け入れる値に固定します。

ツール呼び出しは必須です。 Claude Code はすべてのリクエストで完全なツールスキーマを含む約 110 KB のボディを送信します。ツールを呼び出せないモデルは、支払い後に最初のターンで失敗します。サーバーはカタログの supported_parameters を使用して、そのようなモデルを事前に拒否します。

前提条件

node --version
claude --version
curl -s -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  https://openrouter.ai/api/v1/credits      # {"data":{"total_credits":…}}

インストール

npm から（推奨）

claude mcp add openrouter --scope user \
  --env OPENROUTER_API_KEY=sk-or-v1-... \
  -- npx -y claude-openrouter-delegate-mcp

またはグローバルにインストールします。これにより設定 CLI も PATH に配置されます:

npm install -g claude-openrouter-delegate-mcp
openrouter-mcp-config --api-key sk-or-v1-...
claude mcp add openrouter --scope user -- claude-openrouter-delegate-mcp

ソースから

git clone https://github.com/histonedev/claude-openrouter-delegate-mcp.git
cd claude-openrouter-delegate-mcp
npm install          # builds automatically via the prepare script
claude mcp add openrouter --scope user -- node "$(pwd)/dist/index.js"

設定 CLI を node dist/cli.js … として実行するか、npm link で openrouter-mcp-config を PATH に配置します。

確認

claude mcp list        # openrouter: ... - ✔ Connected

その後、Claude Code セッションを再起動してください。ツールリストは起動時に読み込まれます。

API キー

以下のうち最初に設定されているものから解決されます:

1. OPENROUTER_API_KEY（最優先 — エコシステムの他の部分が使用する名前）

2. OPENROUTER_MCP_API_KEY

3. 設定ファイル内の apiKeyFile — キーを含むファイルへのパス

4. 設定ファイル内の apiKey

openrouter-mcp-config --api-key sk-or-v1-...        # writes ~/.openrouter-mcp/config.json, mode 0600
openrouter-mcp-config --api-key-file ~/.secrets/or  # or keep it somewhere else entirely

キーが MCP ツールを通じて公開されることはありません。openrouter_models は sk-or-v1-a...7f2e として報告し、CLI も同じマスク形式を出力し、設定ファイルは 0600 で書き込まれます。--api-key --scope project で渡されたキーはユーザー設定にリダイレクトされます。プロジェクト設定はコミットされるためです。

キーをディスクに一切置きたくない場合は、MCP 登録時に --env OPENROUTER_API_KEY=… で固定し、設定ファイルをスキップしてください。

設定

設定は 4 つのレイヤーから解決され、後者が優先されます:

1. 組み込みのデフォルト

2. ユーザー設定 — ~/.openrouter-mcp/config.json（$OPENROUTER_MCP_CONFIG で上書き可能）

3. プロジェクト設定 — サーバーの作業ディレクトリ内の ./openrouter-mcp.config.json

4. 環境変数

{
  "delegationMode": "ondemand",
  "defaultModel": "deepseek/deepseek-v4-flash-0731",
  "smallModel": "google/gemini-3.7-flash",
  "allowedModels": ["deepseek/deepseek-v4-flash-0731", "qwen/qwen3.7-flash"],
  "defaultPermissionMode": "auto",
  "maxOutputTokens": 16000,
  "requireToolSupport": true
}

設定の変更

設定はモデルではなく、ターミナルから変更します:

openrouter-mcp-config                                   # show current settings + active layers
openrouter-mcp-config --mode auto                       # off | ondemand | auto
openrouter-mcp-config --default-model qwen/qwen3.7-flash
openrouter-mcp-config --small-model google/gemini-3.7-flash
openrouter-mcp-config --allow deepseek/deepseek-v4-flash-0731,qwen/qwen3.7-flash
openrouter-mcp-config --permission-mode acceptEdits
openrouter-mcp-config --scope project                   # write ./openrouter-mcp.config.json

その後、Claude Code セッションを再起動して、サーバーが設定を再読み込みするようにします。

これ用の MCP ツールは意図的に存在しません。 セキュリティモデルを参照してください。

委譲モード

これは、モデルが実際に読み取るツールの説明を書き換えることで、オーケストレーターが委譲にどの程度積極的に手を伸ばすかを制御します。変更にはセッションの再起動が必要です（設計上の意図です）。

どちらのモードにも明示的なコスト警告が含まれます。ローカルモデルとは異なり、委譲されたすべてのターンが課金され、すべてのリクエストが数万の入力トークンを運ぶためです。

モデルの選択

OpenRouter は 400 以上のモデルを提供しています。openrouter_models はツール対応のものにフィルタリングし、デフォルトで切り詰めます。カタログ全体をオーケストレーターのコンテキストに投入すること自体が高コストだからです。

openrouter_models({ filter: "gemini", limit: 10 })
openrouter_models({ free_only: true })

デフォルトは deepseek/deepseek-v4-flash-0731 です。ツール対応、1.3M コンテキスト、そして安価です。allowedModels を設定して、信頼するショートリストに委譲を固定してください。許可されたセットは delegate_start の説明に埋め込まれるため、オーケストレーターは追加の呼び出しなしでメニューを把握でき、他のモデルは黙って代替されるのではなく名前で拒否されます。

モデルの品質はさまざまで、それはあなたが管理すべき問題です

これらは Claude モデルではなく、Claude Code はチャット UI よりもモデルに強く依存します。このパッケージの構築中に、実際の実行で観察されたこと:

• モデルがツールを正しく呼び出しても、最終テキストを返さないことがあります。作業は行われましたが、締めくくりのメッセージがありませんでした。サーバーはこれを検出し、空の結果の代わりに記録されたアクティビティトレイルを返します。

• モデルが独自のネイティブなツール呼び出しマークアップをプレーンテキストとして出力することがあります — DeepSeek が推論ブロック内で <｜DSML｜tool_calls> を生成するなど — 構造化されたツール呼び出しの代わりに。何も実行されず、トークンは依然として課金されます。プロンプトが長く複雑になるほど、これが発生する可能性が高くなります。

• 完了したジョブの tool calls: 0 注釈は、古典的な失敗のためにあります。つまり、ツール呼び出しに裏付けられていない、リポジトリに関する自信満々の回答です。

弱いモデルには短く単一目的のプロンプトを好み、max_turns で作業を制限し、主張が重要な場合は delegate_status を確認してください。

コスト

完了したすべてのジョブがコストを報告し、ラベルはその信頼度を示します:

cost:       $0.00045   (billed by OpenRouter, 1 generation(s))
cost:       >=$0.00045 (billed so far -- 1 of 2 generations recorded)
cost:       $0.00924   (rough list-price estimate; actual routing may differ several-fold)

OpenRouterは生成IDをAnthropicのメッセージIDとして返すため、サーバーはそれらを収集し、/v1/generationに各リクエストの実際のコストを問い合わせます。それが信頼できる数値です。課金レコードは生成終了の少し後に届くため、ジョブは一時的に部分合計を報告することがあります — >=として表示され、最終的な数値としては決して表示されません。なぜなら、コスト表示が誤ってはいけない方向は下方向だけだからです。

見積もりは、レコードを取得できない場合のフォールバックです。桁レベルの目安としてのみ扱ってください。テストでは、同じモデルで同一のトークン数が、プロバイダーのルーティングとキャッシュヒットによって10倍も請求が異なり、ある実行ではリスト価格での計算が20倍高くなりました。

トークン数について知っておくべきことが2つあります：

• Claude Codeはプロンプトのほぼ全体をinput_tokensではなくcache_creation_input_tokensとして報告します。tokens: in …の行はすべての入力クラスを合計します。「12 input tokens」のように見えるジョブは、実際には~42,000です。

• OpenRouterはキャッシュを尊重しないプロバイダーにルーティングすることが多く（native_tokens_cached: 0）、そのため再開された会話はキャッシュ読み取りの数値が示すほど安くはありません。

コスト削減。 smallModelが最も効果的なレバーです。Claude Codeのhaikuスロットはバックグラウンドのユーティリティ呼び出しを担当しており、メインモデルは高性能なまま、そこに安価なモデルを指定しても品質はほとんど損なわれません。次にmax_turnsがエージェントのループを制限し、allowed_toolsがデリゲートにタスクに必要な以上にリポジトリを探索させないようにします。

ツールリファレンス

delegate_start

delegate_followupはjob_idまたはsession_idを受け取り、さらに同じprompt/prompt_fileのペアと、オプションのpermission_mode、max_turns、wait_secondsを受け取ります。

運用

デフォルトで非同期

delegate_startはミリ秒単位でjob_idを返し、デリゲートはバックグラウンドで実行を続けます。これにより、長時間のタスクがセッションを停止させたり、MCPクライアントのタイムアウトを引き起こしたりするのを防ぎます。ほとんどのクライアントは60秒後に単一のリクエストを諦めますが、これは多くのデリゲートタスクがかかる時間より短いのです。

delegate_start({ prompt: "Audit src/ for unused exports" })
  → job_id A, session_id S, turn 1, state: running

delegate_status({ job_id: "A" })
  → recent activity:
      [tool] Grep: export
      [tool] Read: /repo/src/index.ts

delegate_result({ job_id: "A" })
  → the final text

代わりにブロックするには、それらのいずれかにwait_secondsを渡します。短いタスクには便利ですが、クライアントのリクエストタイムアウト未満に抑えてください。

双方向の会話

すべてのジョブにはsession_idが付いています。そのjob_idをdelegate_followupに渡すと、完全な履歴を持つセッションが再開されます。session_idはターンをまたいで安定していますが、各ターンは新しいjob_idを取得します。

delegate_start({ prompt: "Summarise the auth flow in this repo" })
  → job A, session S, turn 1
delegate_followup({ job_id: "A", prompt: "Now list every place it can fail" })
  → job B, session S, turn 2   (delegate still remembers turn 1)

再開すると会話が入力トークンとして再生されるため、長いスレッドは新しいスレッドよりも1ターンあたりのコストが高くなります。ただし、同じコンテキストを再構築するよりははるかに安価です。

長いプロンプト

すべてのプロンプトパラメータにはprompt_file版があります。内部的には、プロンプトは常にディスクに書き込まれ、stdinを介してCLIに渡されます — argvエントリとしても、シェル経由でもありません。バッククォート、$(...)、引用符、改行、glob文字はそのまま通過し、argvの長さ制限もありません。

権限

// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })

// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })

キャンセル

delegate_cancel({ job_id: "A" })

デリゲートとそれが開始したすべてを強制終了し、それ以上クレジットを消費しないようにします。サーバーはシャットダウン時にも実行中のデリゲートを強制終了します。

ジョブのアーティファクト

各ジョブは~/.openrouter-mcp/jobs/<job_id>/に書き込みます：

stream.jsonlは、デリゲートの要約が説得力に欠ける場合に確認すべき場所です。そこにはモデルによる説明ではなく、実際のツール結果が保持されています。自動的に削除されるものはありません — 好きなときにディレクトリを削除してください。

トラブルシューティング

No OpenRouter API key configured OPENROUTER_API_KEYを設定するか、openrouter-mcp-config --api-key sk-or-v1-...を実行してから、セッションを再起動してください。

OpenRouter rejected the API key (HTTP 401) openrouter.ai/keysで確認してください。キーはサーバー起動時に読み込まれるため、新しいキーにはセッションの再起動が必要です。

Model "x" does not support tool calling 意図した動作です — Claude Codeはすべてのリクエストでツールスキーマを送信します。別のモデルを選ぶか、それでも試す場合はrequireToolSupport: falseを設定してください。

Model "x" is not in the allowed list 意図した動作です。openrouter-mcp-config --allow <models>を実行してから再起動してください。

デリゲートがテキストを返さない、またはツール呼び出しが何も実行しない 配線の問題ではなく、モデルの品質の問題です — モデルの品質はばらつくを参照してください。より短いプロンプトやより高性能なモデルを試し、stream.jsonlを読んで実際に何が起こったのかを確認してください。

MCPクライアントからのRequest timed out wait_secondsがクライアントのリクエストごとのタイムアウト（多くの場合60秒）を超えました。wait_secondsを外し、代わりにdelegate_statusでポーリングしてください — それが非同期設計の目的です。

max_tokensに関するHTTP 400 モデルの出力上限が要求された値より低いです。サーバーはカタログの値に自動的にクランプします。カタログが誤っている場合はmaxOutputTokensを下げてください。

ツールがClaude Codeに表示されない ツールリストはセッション開始時に読み込まれます。再起動するか、claude mcp listで確認してください。

デリゲートが起動エラーですぐに失敗する CLIが見つかりませんでした。OPENROUTER_MCP_CLAUDE_BINにclaudeの絶対パスを設定してください。

プラットフォームサポート

プラットフォームの違いはsrc/platform.tsに分離されています：

バイナリの解決。 POSIXではspawnがPATHを検索します。Windowsでは、ネイティブインストールではclaude.exe、npmインストールではclaude.cmdが生成されますが、CreateProcessは.cmdを直接実行できません — そのためサーバーは.exe優先でPATH × PATHEXTを走査し、.cmdシムをcmd.exe経由でルーティングするフォールバックを使用します。

引数のエスケープ。 そのフォールバックは2つのレイヤーを適用します：MSVCRTのargvクオート、次にcmd自身のメタ文字（& | < > ^ " ( ) % !）のキャレットエスケープです。2番目のレイヤーを省略するのは、古典的な.cmdコマンドインジェクションの穴です。プロンプトはこのパスには決して触れません — stdin経由で渡されます。制限が1つあります：複数行の append_system_promptはcmd.exeのコマンドラインをまたげないため、サーバーはそれを静かに壊すのではなく、OPENROUTER_MCP_CLAUDE_BINを指す明確なエラーを発生させます。

環境変数の許可リスト。 WindowsはPOSIXよりもはるかに多くの環境変数を保持します。SystemRootとwindirは必須です — これらを取り除くとWinsockが初期化に失敗し、子プロセスはソケットをまったく開けなくなります。

キャンセル。 POSIXでは子プロセスはプロセスグループリーダーとしてdetachedで生成され、process.kill(-pid)でキャンセルされます。Windowsではtaskkill /T /Fを使用します。

セキュリティモデル

資格情報の分離がポイントです。 子プロセスの環境は継承ではなくゼロから構築され、OpenRouterの値が適用される前にプロバイダー変数が取り除かれます。test/env-unit.mjsは、キーが正確に1つの変数で子プロセスに届き、親の秘密情報が残らないことを検証します。test/e2e.mjsは、偽のANTHROPIC_API_KEYと実際のANTHROPIC_BASE_URL=https://api.anthropic.comで親を汚染し、デリゲートがどちらも見えないことを確認します。

キーはツール経由では決して読み取れません。 すべての診断パスがキーをマスクし、test/readonly.mjsはツール出力にもCLI出力にもキーが含まれないことを検証します。これは、トークンがリテラル文字列ollamaであるOllama版よりも、ここでの方が重要です。

委任ポリシーはモデルから書き換えられません。 delegationMode、allowedModels、APIキーを変更するMCPツールはありません。ondemandが不便だと感じたモデルが、自分でautoに切り替えて支出を開始することはできません。設定は起動時に一度だけ読み込まれ、実行時に変更されることはなく、ツールの説明にもポリシーはモデルが変更できるものではないと明記されています。

これはガードレールであり、セキュリティ境界ではありません。 シェルアクセスを持つエージェントは設定ファイルを編集できます。ツールを削除することで得られるのは、そのような変更がタスク途中の単発の静かなツール呼び出しではなく、次回の再起動時にのみ有効になる可視的なファイル編集であることです。完全に防ぐには、MCP登録時に--envで値を固定してください。これにより設定ファイルが上書きされます：

claude mcp add openrouter --scope user \
  --env OPENROUTER_API_KEY=sk-or-v1-... \
  --env OPENROUTER_MCP_DELEGATION_MODE=ondemand \
  --env OPENROUTER_MCP_ALLOWED_MODELS=deepseek/deepseek-v4-flash-0731 \
  -- node /path/to/claude-openrouter-delegate-mcp/dist/index.js

支出は現実です。 暴走したautoモードのオーケストレーターは、あなたの忍耐ではなくクレジットを消費します。このサーバーに渡すキーにはOpenRouterのキー上限を設定しておいてください — それはモデルが抗弁できない上限です。

デリゲートはあなたのファイルシステムを継承します。 デリゲートはあなたのユーザーとして、指定したcwdで、defaultPermissionModeで実行されます。委任されたセッションは通常のClaude Codeセッションと同じように扱ってください — 信頼度の低いモデルに作業を任せる場合は、disallowed_toolsまたは読み取り専用の権限モードを使用してください。

開発

npm install        # installs and builds
npm run build      # tsc
npm run dev        # tsc --watch

テスト

node test/env-unit.mjs       # env isolation, key handling, model slot wiring
node test/pricing-unit.mjs   # cost arithmetic, catalog filtering, URL normalisation
node test/quoting.mjs        # Windows argv/cmd escaping, incl. an injection probe
node test/killtree-unit.mjs  # process-tree termination (cross-platform)
OPENROUTER_API_KEY=... node test/e2e.mjs     # full MCP round trip         (costs ~$0.01)
OPENROUTER_API_KEY=... node test/async.mjs   # async polling, prompt_file, cancel
CFG_PATH=/tmp/c.json CFG_CWD=/tmp node test/readonly.mjs   # config is read-only to the model

npm test はネットワークを必要としない4つのテストを実行します。これらは Windows と POSIX の両方で成功します。プロセッスツリーのテストはシェルの組み込みコマンドではなく node プロセスからツリーを構築するため、POSIX 専用ではありません。

リリースの公開

npm login                       # interactive, once per machine
npm version patch               # or minor / major -- tags and bumps
npm publish                     # prepare script builds first
git push --follow-tags

npm publish はスクリプトや非対話シェルではなく、実際のターミナルから実行してください。WebAuthn/セキュリティキー 2FA では、CLI はブラウザを開いてチャレンジを完了します。TTY がないとそれができないため、セキュリティキーでは生成できない TOTP コードを要求するようにフォールバックします（npm error code EOTP）。CI では、代わりに Bypass 2FA 付きのきめ細かいアクセストークンを使用してください。

パッケージには dist/、README.md、LICENSE のみが含まれます。publishConfig.access は public で、prepare はパッキング前に tsc を実行するため、古い dist/ が公開されることはありません。

レイアウト

ライセンス

MIT — LICENSE を参照してください。