agent-mcp-hub

agent-mcp-hub

複数の CLI コーディングエージェント（Codex、Cursor、 OpenCode、Claude、Antigravity）をあらゆる MCP クライアントに接続する、1 つの MCP サーバーです。

設計上、stdio のみです。 このハブには Docker イメージも HTTP トランスポートもありません（どちらも 0.5.x 系で削除されました）。コンテナ化されたサーバーやリモート サーバーでは呼び出し元のリポジトリパスを参照できず、呼び出し元の CLI ログインも再利用できません。どちらも製品の契約を損なうことになります。このハブは MCP クライアントの子プロセスとして、あなたのマシン上で、あなたとして実行されます。

ツール

ツール	説明
codex	プロンプトを codex exec に委任します（プロンプトは stdin 経由で渡されます）
cursor	プロンプトを cursor-agent -p に委任します（プロンプトは stdin 経由で渡されます）
opencode	プロンプトを opencode run に委任します
claude	プロンプトを Claude Code CLI に委任します（プロンプトは stdin 経由で渡されます）
agy	プロンプトを Google Antigravity に委任します（agy --print=… を使用し、プロンプトはフラグの値として渡されます）
run_all	同じプロンプトをすべてのエージェントに並列で渡し、結果を横並びで表示します
list_agents	インストール済みで PATH 上にあるエージェント CLI を表示します
ping	ヘルスチェック

エージェントツールは、prompt（必須）、model、cwd、timeoutMs（実行時間の上限。デフォルトは 1800000 = 30 分）、および idleTimeoutMs（非アクティブ時の上限。デフォルトは 300000 = 5 分）を受け付けます。長時間実行タスクとタイムアウトを参照してください。

既知の制限：opencode のプロンプトは - で始められない場合があります（CLI がフラグとして解析する可能性があります）。このツールは推測で処理せず、対処方法がわかるエラーを返します。

エージェントごとのモデルの選択

モデル ID はエージェントごとに異なり、重複しません。 o3 は agy では意味を持たず、gemini-3.6-flash-low は codex では意味を持ちません。また、opencode は独自の名前空間（opencode/big-pickle）を使用します。そのため、1 つの model 値がファンアウト先で有効なのは、最大でも 1 つのエージェントです。

• run_all はエージェントごとのマップである models を受け付けます。指定されていないエージェントは、model にフォールバックし、それもない場合は各 CLI のデフォルトを使用します。
• review_change は runnerModel と reviewerModel を受け付けるため、変更を書くエージェントとレビューするエージェントに、異なるエンジン と ティアを使用できます。model はどちらにもフォールバックとして使用されます。

{
  "tool": "run_all",
  "arguments": {
    "prompt": "Explain the retry logic in src/exec.ts",
    "models": { "codex": "o3", "agy": "gemini-3.6-flash-low", "claude": "haiku" }
  }
}

models に未知のエージェント名を指定すると、有効なエージェントの一覧とともに拒否されます。タイプミスがデフォルトモデルに黙ってフォールバックすることはありません。

有効な ID の確認方法：opencode models、cursor-agent models、agy models で一覧を確認できます。codex と claude には同様のコマンドがありません。codex は ~/.codex/config.toml からデフォルトを読み込み、claude はドキュメントに記載されたエイリアス（opus、sonnet、haiku、fable）を受け付けます。claude models はサブコマンドではない点に注意してください。プロンプトとして扱われるため、その「モデル一覧」は生成されたテキストであり、信頼できる情報源ではありません。

エラー処理

ラップ対象の CLI が失敗すると、ハブは失敗を分類し、ANSI コードを含まない、明確で対処方法がわかる isError の結果を返します。生のターミナル出力をそのまま返すことはなく、分類名と具体的な修正方法を示します。

分類	対処例
not_installed	CLI をインストールします（例：npm i -g @openai/codex）／PATH を修正します
not_authenticated	codex login · cursor-agent login · opencode auth login · claude → /login · agy → 初回実行時にサインインします（または対応する API キーを設定します）
not_configured	CLI の設定でモデル／プロバイダーを設定します
timed_out	timeoutMs を増やすか、エージェント／モデルが応答しているか確認します
stream_stalled	エージェントはネットワークに接続できていますが、ストリームが繰り返し切断されます（例：TLS インターセプトプロキシ経由の cursor）。そのエージェントは利用不可として扱ってください。timeoutMs を増やしても解決しません
server_busy	少し待ってから再試行します（上流のレート制限、またはローカルのエージェント起動キューが満杯です）
tool_failure	汎用的なゼロ以外の終了コードです。メッセージには (exit N) と省略された出力末尾が含まれます

たとえば、認証されていない cursor が ANSI コード付きの「任意のキーを押してサインイン」バナーを返すことはなくなりました。代わりに cursor is not authenticated … Fix: run cursor-agent login`` を返します。

変更をレビューする（review_change）

Git の cwd で runner エージェントを実行して変更を行い、実際に変更された内容の git diff を取得した後、reviewer エージェントにその差分を評価させます。runner の出力、差分（--stat）、および所見付きの PASS / WARN / FAIL 判定を返します。

入力: runner、reviewer（エージェント名）、prompt、cwd（Git ワークツリーである必要があります）、省略可能な runnerModel、reviewerModel、両方のフォールバックとなる model、 timeoutMs。

主な注意点:

• エージェントをまたいで利用する設計です。たとえば、codex が記述し、claude がレビューします。

• 通常のエージェントツールでは公開されない、具体的な差分を返します。

• 新規作成された（未追跡の）ファイルは、内容とともにレビュアーに提示されます（上限あり：1 ファイルあたり 64 KiB、50 ファイル。超過分は切り捨てられ、その旨が示されます）。git diff だけでは、これらのファイルはすべて含まれません。

• ワークツリーがすでに変更済みの場合、差分に既存の変更が含まれることがあります（出力に記載されます）。

• クライアント側の停止フックや PR 時の CI レビューを補完するものであり、置き換えるものではありません。

• 確認ゲート（MCP_CONFIRM）が適用されます。

• レビュアーは最小権限で実行されますが、それによってどの程度の保証が得られるかはエージェントによって異なります。 レビュアーのプロンプトには攻撃者の影響を受けた差分が埋め込まれるため、runner に付与される書き込み権限ではなく、読み取り専用で実行されます。5 つのうち、実際の制限があるのは 2 つだけです。

  レビュアー	読み取り専用にする仕組み	強制されますか？
  codex	-s read-only	はい — OS レベルのサンドボックス
  claude	--disallowedTools Write,Edit,…,Bash	はい — ハーネスレベルの拒否
  cursor	--trust --mode plan（--force なし）	いいえ — モデルへの助言のみ
  agy	権限付与を保留	一部 — ヘッドレス実行時の自動拒否であり、サンドボックスではありません
  opencode	利用できる仕組みなし	いいえ — 制限なし

  制限を確実に適用したい場合は、レビュアーとして codex または claude を選んでください。 これは nonce で保護された差分と使い捨ての一時 cwd による多層防御です。いずれもサンドボックスではありません。

{
  "tool": "review_change",
  "arguments": {
    "runner": "codex",
    "reviewer": "claude",
    "prompt": "Add retry with exponential backoff to the API client",
    "cwd": "/Users/you/projects/my-app"
  }
}

前提条件

使用する CLI をインストールし、認証してください（いずれか一部だけでも利用できます）。

• Codex: npm i -g @openai/codex && codex login
• Cursor: curl https://cursor.com/install -fsS | bash && cursor-agent login
• OpenCode: npm i -g opencode-ai && opencode auth login
• Claude Code: npm i -g @anthropic-ai/claude-code && claude（初回実行時にログインします）
• Antigravity: Antigravity CLI をインストールします（例：brew install --cask antigravity-cli）。 次に agy を一度実行してサインインします。login サブコマンドはなく、 認証情報は OS のキーチェーンに保存されるため、設定する API キー環境変数はありません。

インストール

推奨 — グローバルインストール（高速で安定した起動）： バージョンを一度固定してインストールし、 クライアントから agent-mcp-hub バイナリを指定します。すぐに起動し、クライアントも安定して接続できます。

npm i -g [email protected]

Claude Code

claude mcp add agent-hub -- agent-mcp-hub

Cursor / 汎用 mcp.json

{
  "mcpServers": {
    "agent-hub": {
      "command": "agent-mcp-hub"
    }
  }
}

インストール不要の代替方法（npx）

グローバルインストールは不要ですが、npx は起動のたびにパッケージを再解決するため、初回起動が遅くなり、 クライアントの接続確認タイムアウトがまれに発生することがあります（サーバー自体に問題はありません。その場合は再試行してください）。継続して利用する場合は、グローバルインストールをおすすめします。

claude mcp add agent-hub -- npx -y [email protected]
# mcp.json:  "command": "npx", "args": ["-y", "[email protected]"]

プレリリース版 / フォールバック： 未リリースのコミットをテストするには、 GitHub から直接実行します：npx -y github:blackaxgit/agent-mcp-hub#<tag-or-sha>。初回の取得時に ソースからビルドするため、npm v12 以降では prepare スクリプトの実行を許可する必要があります。

設定

MCP_AGENTS — 公開するエージェントのカンマ区切りの許可リスト （codex,cursor,opencode,claude,agy）。未設定または空の場合は、すべてのエージェントを公開します。無効化された エージェントにはツールが割り当てられず、list_agents/run_all にも表示されません。未知の名前を指定すると、有効な名前の一覧を含むエラーが起動時に発生するため、タイプミスによってエージェントが気付かないうちに無効化されることはありません。

stdio の場合は、クライアントの mcp.json に設定します。

{
  "mcpServers": {
    "agent-hub": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": { "MCP_AGENTS": "codex,claude" }
    }
  }
}

エージェントの実行前に確認 — MCP_CONFIRM

MCP_CONFIRM=1（値は1／true／on／all、デフォルトはオフ）を設定すると、エージェントのツール、およびrun_allがCLIを実際に起動する前に確認を求めます。サーバーは簡単な概要（エージェント・プロンプト・cwd・モデル）を送信して待機します。承認するとエージェントを実行し、拒否すると何も実行せず、キャンセルとして処理を終了します。

これは標準のMCP elicitation機能を使用するため、クライアント／IDEに依存しません。フォームによるelicitationに対応するあらゆるMCPクライアント（Claude Code、Cursor、VS Code、Zed、Windsurf、カスタムSDKクライアントなど）で動作します。この確認ゲートは製品名ではなく、プロトコルの機能を基準にします。elicitationに対応していないクライアントでは、プロンプトなしでそのまま実行されます（停止したり、エラーが発生したりすることはありません）。

{
  "mcpServers": {
    "agent-hub": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": { "MCP_CONFIRM": "1" }
    }
  }
}

長時間実行タスクとタイムアウト

複雑なエージェントのタスクは、完了まで何分もかかることがあります。ハブはそれぞれの実行に独立した2つのタイマーを設けています。これにより、成果を上げながら長時間実行するタスクは継続でき、実際に停止したタスクは速やかに失敗します。

• アイドル（無活動）タイムアウト — idleTimeoutMs（呼び出しごと）／MCP_AGENT_IDLE_TIMEOUT_MS （環境変数）、デフォルトは 300000（5分） です。CLIが出力するチャンクごとにタイマーがリセットされるため、作業を続けている（出力をストリーミングしている）エージェントはタイムアウトしません。出力が途絶えたエージェント（到達不能なモデルバックエンドでopencodeが停止した場合など）は、上限時間を使い切るのではなく、アイドル時間を過ぎると終了します。その際、「出力がありません。エージェントが停止しているか、モデル／バックエンドに到達できない可能性があります」という対処可能なエラーが返されます。
• 合計実行時間の上限 — timeoutMs（呼び出しごと）／MCP_AGENT_TIMEOUT_MS（環境変数）、デフォルトは 1800000（30分） です。アクティビティの有無にかかわらず適用される、厳格な上限です。

いずれかのタイマーが先に作動すると、エージェントのプロセスグループが終了します。注意点： アイドルタイマーのリセットは、CLIが途中経過をストリーミングすることを前提としています。codexとopencodeはストリーミングしますが、claude -p、cursor-agent -p、agy --printは最終結果のみを出力する場合があります。そのため、これらで長時間出力のないタスクを実行すると、5分でアイドルタイムアウトにより終了することがあります。そのようなタスクではidleTimeoutMs／MCP_AGENT_IDLE_TIMEOUT_MSを大きくするか、合計時間の上限を利用してください。

agyは特に注意が必要です。回答全体を最後に一度に出力します（計測では、12行の回答の各行がすべて同じ時刻に届きました）。ハブは内部の--print-timeoutを48時間に引き上げるため、agyのデフォルトの5分で実行が打ち切られることはありません。そのため、実際に停止した場合に対する保護はアイドルタイマーのみです。agyで長時間の自律タスクを実行する場合は、それに応じてidleTimeoutMsを設定してください。

エージェントの実行中、ハブは通知を要求したクライアント（_meta.progressToken）にMCPの進捗通知を送信し、長時間の実行中も状況を確認できるようにします。注：**Claude Code（stdio）**では、.mcp.jsonのサーバーごとのリクエストtimeout（または、Claude Codeが参照する環境変数MCP_TOOL_TIMEOUT）が、進捗によってリセットされない厳密な実時間の上限です（デフォルトは約28時間）。最長の実行時間より短く設定している場合は、値を大きくしてください。

アップグレード

グローバルインストール： 新しいバージョンをインストールしてください。MCP設定に固定されているagent-mcp-hubコマンドは、次回クライアントを起動したときに新しいバージョンを使用します。

npm i -g [email protected]

npx（バージョン固定）： MCP設定で固定しているバージョンを更新します。たとえば、すべての箇所で[email protected]を[email protected]に変更します。

常に最新版を使用（共有設定には非推奨）： バージョンを固定せず、agent-mcp-hub@latestを使用します。npxはバージョンごとにキャッシュするため、古いコピーが使われる場合があります。最新のものを取得するには、npx --prefer-online agent-mcp-hubまたはnpx clear-npx-cacheを実行してください。

バージョンを固定すると再現性が得られるため、チーム全体で使用するファイルやリポジトリにコミットするmcp.jsonファイルでは、バージョン固定を推奨します。

開発

npm install
npm test           # vitest
npm run typecheck  # strict TS over src + tests
npm run dev        # run from source over stdio
npm run build      # emit dist/

アーキテクチャ

純粋なアダプター（src/adapters/* — プロンプトから{args, stdin?}への変換。I/Oなし）→ 単一のサブプロセス境界（src/exec.ts）→ MCP stdio サーバー（src/server.ts）。エージェントを追加するには、約15行のアダプターファイルを1つ作成し、src/registry.tsに1行追加します。

ライセンス

Mozilla Public License 2.0（MPL-2.0）。

0.5.2より前のバージョンはMITライセンスでリリースされており、それらのバージョンにはそのライセンスが引き続き適用されます。MPL-2.0は0.5.2以降に適用されます。