mcp-agents

AI CLI ツール（Claude Code、Antigravity CLI（agy）、Codex CLI）をラップする MCP サーバーです。Chrome DevTools MCP をリモートでリースしたブラウザにプロキシすることもできます。

前提条件

• Node.js >= 26

• 以下の CLI のうち少なくとも 1 つがインストールされ、$PATH に含まれていること:

--provider で選択した CLI だけが存在していれば十分です。

Related MCP server: claudecode-mcp

インストール

npm install -g mcp-agents

グローバルインストールが最も高速で信頼性の高い起動方法です。npx -y mcp-agents は MCP サーバーが起動した後は機能的に同等ですが、起動は MCP クライアントが接続できる前に npm パッケージの解決・キャッシュ状態に依存します。

ヒント: プロジェクトの .mcp.json が mcp-agents を参照している場合は、セットアップスクリプト（例: bin/setup）に npm install -g mcp-agents を追加して、新しい開発者が自動的に取得できるようにしてください。

クイックテスト

# Default provider (codex)
mcp-agents

# Specific provider
mcp-agents --provider claude
mcp-agents --provider gemini

# Browser provider (example injected lease helper)
mcp-agents --provider browser \
  --browser_lease_command '["bin/box","--browser"]'

サーバーは JSON-RPC over stdio で通信します。待機状態になると stderr に [mcp-agents] ready (provider: <name>) を出力します。

プロバイダーとツール

各 --provider フラグは 1 つの CLI バックエンドを選択します:

Claude レビュー

本格的なセカンドオピニオンやコードレビューには、バックグラウンドツールを使用してください:

1. 完全なレビュープロンプトと絶対パスの cwd を指定して claude-start を呼び出します。

2. 返された jobId と cursor を指定して claude-status を呼び出します。状態が終端になるまで、新しいカーソルごとに繰り返します。

3. 状態が completed になったら claude-result を呼び出します。done が true になるまで nextOffset から続けます。

4. 判定が不要になった場合は claude-cancel を呼び出します。

claude-status はデフォルトで 10 秒間ロングポーリングし、wait_ms は最大 60 秒まで受け付けます。ステータスポーリングをキャンセルしてもジョブはキャンセルされません。ジョブは 1 回限りで、現在の MCP 接続に限定されます。応答セッションはなく、切断するとアクティブな作業はキャンセルされます。サーバーはアクティブ 8 件、保持 32 件のジョブを許可し、終端ジョブを 1 時間保持し、結果を 32,768 Unicode コードポイント単位でページングし、最終結果が 10 MiB を超える場合は拒否します。

バックグラウンドレビューには、ブリッジ所有の 2 時間の期限があります。オペレーターはサーバー起動時に --timeout <seconds> で置き換えることができます。呼び出し側は timeout_ms でジョブを短縮することはできません。Claude は claude-opus-4-8 に effort xhigh で固定され、リーフレビューアーとして実行されます。プロジェクトの指示とリポジトリコンテキストは保持されますが、フック、サブエージェント、スキル、スラッシュコマンド、外部 MCP サーバー、変更ツールは無効になります。Read、Glob、Grep、プランモードの読み取り専用 Bash 検査のみが利用可能です。リーフ指示はテスト実行、インストール、委任、外部副作用も禁止します。中間モデル出力、ツール入力/結果、パス、推論は MCP を通じて転送されません。サニタイズされたフェーズステータスと最終判定のみが公開されます。

ブロッキングの claude_code ツールは、単一の MCP 呼び出しがクライアントのタイムアウト内で問題なく完了できる小さなプロンプトにのみ使用してください。

claude_code パラメータ

その他の tools/call 引数（model、effort、config など）は無視されます。

Claude は claude-opus-4-8 に effort xhigh で固定されています。呼び出し側は呼び出しごとにモデルや effort を変更できません。呼び出しは --output-format json で実行されます。サーバーは JSON ペイロードを解析し、アシスタントの result テキストを返します（is_error=true の場合は MCP エラー）。長いデフォルトは深い Opus レビューに対応するためです。呼び出し側は小さな timeout_ms を設定でき、サーバーオペレーターは --timeout <seconds> でデフォルトを上書きできます。

gemini パラメータ

その他の tools/call 引数（model や model_reasoning_effort など）は無視されます。

agy は常に --sandbox（端末制限有効）で実行されます。呼び出しごとのサンドボックスの切り替えはありません。

browser（リモート Chrome パススルー）

ブラウザプロバイダーは、ローカルの chrome-devtools-mcp サーバーを即座に起動し、最初のブラウザツール呼び出しでリモート Chrome リースを遅延取得します。MCP サーバーとその書き込みファイルはすべてローカルに留まります。CDP のみがオペレーター提供のループバックトンネルを通過します。取得中に到着した呼び出しは、1 つのプロビジョニング試行を共有し、FIFO 順序を維持します。ラッパー所有の取得、ステータス、解放、ジョブ、キャンセルツールはありません。

crabbox を使ったクイックセットアップ

crabbox との組み合わせに最適です。一時的でシングルテナントのボックスで、自身のキャップで終了します。ブラウザリースが必要とするライフタイムであり、正しく行う必要のあるティアダウンはありません。

acquire ヘルパーは 4 つのことを行います: ボックスをリースする。--remote-debugging-port=<remote> を指定して Chromium を起動する。ssh -L 127.0.0.1:<local-cdp-port>:127.0.0.1:<remote> を開く（テスト対象のページが自分のマシンで提供されている場合は、--app-port 用に一致する -R を追加）。その後、ローカルポートで /json/version が応答したら、次のように出力します:

record_version=1
state=ready
generation=<opaque token>
local_cdp_port=<the port you were given>
browser_url=http://127.0.0.1:<that same port>

status はそのリースを再確認し、release はそれを破棄します。終了コード 69 はレーンをフェイルクローズドに保ちます。

プロバイダーはクラウドや SSH に関する知識はありません。注入されたコマンドがリースを所有し、次の argv 形式を受け取ります:

acquire --session <id> --local-cdp-port <port> --viewport <WxH> [--app-port <port>]
status --session <id> [--generation <token>]
release --session <id> --generation <token> --reason idle|shutdown

成功した acquire 出力は、バージョン 1 の ready レコード、世代、選択されたローカル CDP ポート、対応するブラウザ URL を含む不活性な UTF-8 の key=value データです。終了 69 はフェイルクローズドです。呼び出しは「GUI が検証されていません — ブラウザボックスが利用できません」を返し、ローカルブラウザを起動しません。ヘルパーが報告したローカル開発サーバーのプリフライトエラーはそのまま保持されます。終了 75 はループバックバインド競合を報告します。mcp-agents は新しいポートを選択し、ダウンストリームを再起動し、元の MCP initialize 機能（roots を含む）と initialized 通知を再生し、重複する initialize 結果を公開せずに最大 3 回再試行します。

chrome-devtools-mcp は意図的にピン留めされていません。フォールバックは最新リリースに浮動します。ここでは特定のバージョンの再接続動作に依存するものはありません。すべてのブラウザツールの結果は、ダウンストリームが再接続を報告するかどうかに関係なく、発行されたリース世代に対して検証されるため、新しいリリースがフェイルクローズドの契約を静かに弱めることはできません。解決は次の順序で決定的です:

1. --browser_command または MCP_AGENTS_BROWSER_COMMAND（コマンド文字列または JSON argv）。

2. パッケージローカルで解決可能な chrome-devtools-mcp、次に node_modules/.bin/chrome-devtools-mcp。

3. npx -y chrome-devtools-mcp@latest。

3 番目のパスでは、最初の initialize が npm の解決を待つ場合があります。起動を高速化するには、mcp-agents と一緒に chrome-devtools-mcp をインストールするか、別の場所にインストールして --browser_command でその実行ファイルを指定してください。特定のデプロイメントで固定バージョンが必要な場合は、そこでピン留めしてください。ブラウザダウンストリームには、解決された chrome-devtools-mcp リリースがサポートする Node バージョンが必要です。このパッケージ自身の >=26 の下限は、ピン留めされていない依存関係が最新を追跡するため、そのレベル以上に保たれます。

chrome-devtools-mcp は意図的に開発依存関係であり、実行時依存関係ではありません。したがって、開発者チェックアウトはパッケージローカルのパスを使用しますが、公開パッケージのコンシューマーは、mcp-agents と一緒にパッケージをインストールするか、明示的なコマンドを提供しない限り、npx フォールバックを使用します。

ビューポートはリースヘルパーに渡され、リモート Chromium のウィンドウサイズを設定できるようにします。Chrome DevTools MCP の --viewport は意図的に省略されています。--browserUrl を介してアタッチする場合、これは不活性だからです。

完了したダウンストリームの JSON-RPC フレームごとに、世代のアイドルタイマーがリセットされます。stderr と部分的な出力はリセットされません。アイドル解放には 60 秒のクリーンアップ制限があり、リモート Chromium、SSH トンネル、ボックスが実際に停止できるようになります。シャットダウン解放は別の 15 秒の制限を使用し、追跡され、再利用されます。どちらもベストエフォートのコスト最適化です。Chrome が消えた場合、中断されたネイティブ接続エラーは再生されません。ヘルパーのステータス 69 は、browser_lease_replaced でそれを補強し、ブラウザが置き換えられたこと、状態が失われたこと、中断された結果が不明であること、呼び出し側が盲目的に再生するのではなく状態を検査する必要があることを明示的に警告します。ステータス 0 はネイティブエラーを保持します。ステータス 70 は、失われたリースとして誤って報告されるのではなく、不明のままです。次のブラウザ呼び出しは再取得し、Chrome DevTools MCP の再接続パスを使用します。

クライアントの初期化フレームと下流の roots/list リクエスト/レスポンスは、ID や URI の書き換えなしに転送されます。下流の再起動時、終了したプロセスに返すべきレスポンスは破棄され、置き換え先のプロセスが ID を再利用できる前に、そのリクエスト相関は破棄されます。これにより、Chrome DevTools MCP のローカルファイル書き込み許可リストが維持され、--allowUnrestrictedPaths は意図的に決して渡されません。App と MinIO のプリフライト失敗は、個別に、元の文言のまま報告されます。Performance trace と Lighthouse の説明では、リモートリンクでの計測はゲート(合格/不合格の判定基準)ではないと警告し、upload_file は、ローカルパスをリモートの Chromium に直接渡せないことを警告します。

URL 制限はオプトイン方式です。ループバックのみをデフォルトにすると、OAuth やサードパーティのアセットが壊れるためです。堅牢化されたループバック専用のデプロイでは、たとえば次のように繰り返し実行できます:

--browser_allowed_url_pattern 'http://127.0.0.1/*' \
--browser_allowed_url_pattern 'https://127.0.0.1/*'

ターゲットアプリケーションと互換性のある、最も狭いパターンを使用してください。プロバイダは実験的なページ ID ルーティングを有効にしません。1 つのプロセスが 1 つのリース、プロファイル、ポートを所有します。

codex (パススルー)

codex プロバイダは、分離された CODEX_HOME 内で Codex のネイティブ MCP サーバー(codex mcp-server)にパススルーします。ブリッジは、サーバー起動ディレクトリ配下のプライベートな tmp/codex-homes/ ツリー内に各ホームを作成し、auth.json をコピーして、最小限の config.toml を書き込みます。通常の外部 MCP サーバーリストは継承されません。これにより、ブリッジ呼び出し中に Codex が Claude や Gemini などの他のエージェントツールを再帰的に起動するのを防ぎます。親ディレクトリと生成されたホームディレクトリはモード 0700 を使用し、コピーされた認証情報と生成されたランタイムファイルはモード 0600 を使用します。

分離されたホームは認証のスナップショットです。ブリッジが再接続するまで、後からの codex login を認識できません。Codex が型付きの unauthorized 終端イベントを報告した場合、ラッパーは重複イベントを抑制し、structuredContent.code に codex_auth_invalidated、action に reauthenticate_and_restart を設定した 1 つの MCP ツールエラーを返します。status、result、cancel、peek、ping、その他の MCP 操作が引き続き利用可能な間、新しい Codex ターンはローカルで拒否されます。ブリッジを停止し、同じ OS ユーザーで codex logout と codex login を実行し、codex exec で確認してから再接続してください。クリーンアップ時、ローテーションされた認証情報は、分離コピーが変更され、かつ正規の認証情報が起動時スナップショットと一致する場合にのみ書き戻されます。したがって、古いブリッジが新しい手動ログインや別のブリッジのトークンローテーションを上書きすることはありません。

許可リストに登録されている唯一のユーザー設定は Fast モードです。起動時に、ブリッジはソースの $CODEX_HOME/config.toml を読み取り、トップレベルの service_tier = "fast" と [features].fast_mode = true の両方を見つけた場合にのみ、分離ホームで Fast モードを有効にします。部分的、無効、欠落、または読み取り不能な設定は Standard モードのままです。その他のユーザー設定はすべて分離されたままです。いずれかの設定を変更した後は、MCP サーバーを再起動してください。Fast モードでは ChatGPT クレジットの消費量が増加するか、API Priority の課金が発生します。

その他の起動時デフォルト: sandbox_mode=workspace-write、approval_policy=never(サーバー全体で --sandbox_mode / --approval_policy により設定可能)、web_search=cached、check_for_update_on_startup=false、allow_login_shell=false、history.persistence=none。固定のブリッジ機能デフォルトは、features.multi_agent=false、features.apps=false、features.plugins=false、features.hooks=false、features.skill_mcp_dependency_install=false です。apps/plugins は無効のままで、ChatGPT のアプリ/プラグインスキル(Figma、Gmail、Presentations など)をブリッジされたセッションコンテキストに入れないようにしています。ネイティブのサブエージェントも [agents] enabled = false で追加で無効化されます。Codex >= 0.145.0 では、安定化された multi_agent 機能フラグだけではコラボツールを削除できなくなったためです。セッションは呼び出しごとに allow_subagents でオプトインします(後述)。この [agents] 行はバージョン対応です。ブリッジは起動時に codex --version を一度プローブし、Codex < 0.145.0 ではこの行を省略します。そのバージョンでは [agents] 配下のブール値が致命的な設定解析エラー(0.102–0.144)になり、機能フラグが単独でコラボツールを制御しているためです。解析できないバージョンは最新の Codex とみなされます。

Workspace-write セッションでは、サンドボックス化されたコマンドが DynamoDB、Redis、OpenSearch、MinIO などのローカルサービスに到達できるように、ネットワークアクセスがデフォルトで有効になっています。サーバー全体で無効にするには、--codex-workspace-network=false または MCP_AGENTS_CODEX_WORKSPACE_NETWORK_ACCESS=false を設定します。CLI フラグは環境変数より優先されます。これはサーバーが所有するサンドボックス設定であり、呼び出しごとのツールスキーマには意図的に含まれていません。

Codex はこの設定に対して localhost 限定のスコープを提供しません。有効にすると、workspace-write セッションのコマンドからの一般的なアウトバウンドネットワークアクセスが許可されます。ファイルシステムへの書き込みは、ワークスペースとその他の設定済みの書き込み可能ルートに制限されたままです。read-only および danger-full-access セッションは sandbox_workspace_write 設定を使用しません。

ブリッジは、Codex の広範な設定形状のネイティブスキーマを、意図的に小さな契約に置き換えます:

両方のスキーマは additionalProperties: false を設定します。サポートされていない、欠落している、または無効な引数は、Codex が実行される前に JSON-RPC -32602 でローカルに拒否されます。これには、config、approval-policy、developer-instructions、base-instructions、compact-prompt などのネイティブの逃げ道も含まれます。将来のアップストリームのスキーマ追加は、mcp-agents が意図的に採用するまで非表示のままです。厳選された 2 つの選択肢以外のモデル値も同様に拒否されます。

ネイティブサブエージェント。 codex または codex-start の allow_subagents: true により、そのセッションは Codex の組み込みマルチエージェントツール(spawn_agent、wait_agent など)を使用できます。これは sandbox とまったく同様にセッションスコープです。リプライはそれを継承し、変更できません。デフォルトはオフです。内部的には、このフラグは呼び出しごとの設定オーバーライドにより、ネイティブのマルチエージェントゲート(agents.enabled と features.multi_agent。上記と同じバージョンゲートに一致)のみを切り替えます。分離ホームの他のすべては変更されません。特に [mcp_servers] の削除は引き続き有効です。生成されたサブエージェントは Codex 専用のインプロセスワーカーであり、このブリッジに再入場したり、Claude、Gemini、その他の外部 MCP ツールに到達したりすることはできません。また、実際の $CODEX_HOME/agents/ にあるカスタムエージェントロールはコピーされません。残る注意点はリーチではなく並行性です。サブエージェントはセッションの sandbox_mode と approval_policy を継承するため、approval_policy=never の workspace-write では、複数のエージェントが同時に同じワークスペースに書き込む可能性があります。Codex がそれらを調整しますが、それに応じて委任の範囲を設定してください。

MCP ブリッジでは approval_policy=never は意図的なものです。切り離されたツール呼び出しは、対話的な承認のやり取りを確実に実行できないためです。オペレータは --approval_policy でサーバー全体に untrusted または on-request を選択できますが、呼び出し側がリクエストごとにそのポリシーを弱めたり変更したりすることはできません。新しい各セッションはサンドボックスを明示的に指定する必要があるため、書き込み権限は呼び出しサイトで確認できます。

起動フラグ(--model、--model_reasoning_effort)は、分離されたネイティブ Codex サーバーのデフォルトを設定します(上書きされない限り gpt-5.6-sol と xhigh)。各最初の codex 呼び出しでは、2 つのモデルのいずれかと、許可された 4 つの推論 effort のいずれかを選択できます:

セレクタはセッション作成時にのみ適用されます。どちらかを省略すると、サーバー設定のデフォルトが使用されます。すべての codex-reply は両方の選択を継承し、変更できません。他のモデルと effort レベルは、クローズドなラッパー契約を通じて意図的に利用できません。

たとえば、読み取り専用のレビューは次のように開始します:

{
  "prompt": "Review this diff",
  "cwd": "/absolute/path/to/project",
  "sandbox": "read-only",
  "model": "gpt-5.6-terra",
  "model_reasoning_effort": "high",
  "goal": "Find correctness and security defects"
}

Goal 注入。 サーバー起動時に --goal "<text>" でデフォルトの目的を設定するか、呼び出しで goal を渡します。mcp-agents は、初期 goal を Codex のネイティブな developer-instructions に内部的に変換します:

{
  "prompt": "Refactor the parser",
  "cwd": "/absolute/path/to/project",
  "sandbox": "workspace-write",
  "model_reasoning_effort": "xhigh",
  "goal": "Keep the public API unchanged"
}

developer メッセージはスレッドに永続するため、リプライはそれを継承します。codex-reply の呼び出しごとの goal は、ネイティブのリプライツールに developer-instructions フィールドがないため、簡潔なプロンプトリマインダーになります。直接の developer 指示は公開されません。goal は、狭く監査可能な継続的目的インターフェースです。呼び出しごとの goal はサーバーデフォルトを上書きします。"" は 1 回の呼び出しでそのデフォルトを抑制します。

ブリッジは tools/list レスポンスを書き換えて、これらの厳選されたスキーマを通知します。通常のネイティブフレームは、前述の型付き認証失敗を除き、バイト単位でそのままパススルーされます。ローカルで生成された検証エラーと認証エラーは、進捗メッセージやリカバリメッセージと同じ、フレームセーフなキュー/境界の方式を使用します。

スレッド内での優先順位。 最初の codex 呼び出しで設定された目的は開発者ロールのメッセージであり、スレッド全体にわたって持続するため、優先されます。後から codex-reply で指定された異なる goal はプロンプトレベルのリマインダーに過ぎず、常設の目的を確実に上書きすることはできません（ライブ検証済み — 最初の目的と競合するリプライの goal は、常設の目的が優先され無視されます）。リプライのリマインダーが機能するのは、競合する常設の目的に妨げられない場合のみです。目的を途中で本当に変更するには、codex-reply で変更するのではなく、新しい codex 呼び出しを開始してください。

注記 — これは Codex のネイティブな /goal ではありません。 Codex の /goal スラッシュコマンド（ライフサイクル／予算／エビデンスに基づく完了を備えた、永続的でスレッドスコープのゴール状態）は TUI 限定の機能です。これは Codex ターミナル UI で解析され、codex mcp-server からは到達できません。MCP プロンプトに /goal … を前置しても、それを有効化するわけではなく、テキストはユーザーメッセージとしてそのまま通過するだけです。したがって、このラッパーは developer-instructions（常設の目的のための MCP ネイティブな手段）を使って Codex を導きます。これはプロンプト／ロールの条件付けであり、ネイティブなゴールライフサイクルサブシステムではありません。

呼び出しごとの liveness。 codex パススルーは、開いているすべての tools/call を個別に追跡します。--codex_idle_timeout <seconds>（デフォルト 600、0 で無効）は、1 回の呼び出しが関連する Codex アクティビティなしで継続できる時間を制限します。その呼び出しの _meta.requestId（または対応するレスポンスや対話的なやり取り）を運ぶ Codex イベントだけが、そのアイドル期限を更新します。Codex の stderr、クライアントの ping、無関係なリクエスト、および別の呼び出しに属するイベントは、停止した呼び出しを生かし続けることはできません。呼び出しがアイドル期限に達すると、ラッパーは JSON-RPC エラー（-32001）でその呼び出しのみを失敗させ、そのリクエストに対して Codex に notifications/cancelled を送信します — ベストエフォートであり、Codex に停止を強制するのではなく要求します（下記のキャンセルを参照）— 停止した呼び出しの遅れて届いたネイティブレスポンスを抑制し、接続を開いたままにします — 兄弟の呼び出しと stdio トランスポートは影響を受けません。これは重要です。なぜなら、stdio トランスポートが閉じると、Claude Code などの MCP クライアントはサーバーを failed とマークし、セッションの残りの期間、すべての mcp__codex__* ツールを恒久的に登録解除するからです（stdio サーバーは自動再接続されません）。そのため、1 つの停止したレビューがブリッジ全体をダウンさせてはならないのです。Codex プロセスグループは、実際のティアダウン（クライアントの切断、シグナル、または stdout の EPIPE）の際には依然として回収されます。唯一の例外は、Codex がレスポンスフレームの書き込み途中で詰まり（エラーを注入できる安全な境界がない）、かつキャンセルも無視した場合です。その場合、ラッパーは 1 回再試行し、その後、制限付きのブリッジ全体のティアダウンにエスカレーションします — 部分的なフレームにクリーンなフレームを出力する方法はないため、クライアントは新しいブリッジに再接続することになります。

キャンセル。 クライアントのキャンセル（notifications/cancelled — すべての ESC、中断されたターン、またはサブエージェントのティアダウン）も同じように扱われます。それは正確に 1 つのリクエストを消費します。--codex_cancel_grace <seconds>（デフォルト 30）は、Codex がそれを確認するまでに要する時間を制限します。期限が切れると、ラッパーはそのリクエスト ID をローカルで解決し、Codex の遅れたレスポンスを抑制し、ブリッジとすべての兄弟呼び出しを実行中のままにします。リクエストを解決することは、Codex が停止したことの証明にはなりません — 確認されなかったターンは放棄されたものとして記録され、実行と書き込みを継続する可能性があります。前述のフレーム途中のエスカレーションは、2 回目の完全な猶予期間を発動させるため、ブリッジが終了するまでにその経路はおおよそ 2 倍の時間がかかります。この猶予期間は意図的に長めに設定されています — ターン途中の Codex はサンドボックス化されたコマンドを実行中であり、MCP キャンセルをすぐに処理しないため、短い猶予期間ではエスカレーション経路がデフォルトの経路になってしまいます。これはタイムアウトの場合よりも重要です。なぜなら、隔離された CODEX_HOME には Codex の sessions/ ディレクトリが保持されており、ブリッジ全体のティアダウンにより、そのプロセス内のすべての threadId が恒久的に再開不可能になり、次の codex-reply は Session not found で失敗するからです。

[!WARNING] リクエストを放棄しても Codex は停止しません。ラッパーは停止を要求しますが、キャンセルを無視するターンは、クライアントが諦めた後もずっと実行を継続し、ワークスペースへの書き込みも続けます。すべての放棄は、その thread_id と job_id とともに stderr に記録され、ターンが後に終了した場合も再度記録されるため、予期せず変更されたツリーは推測ではなく説明可能です。ここで特に注意が必要なのはバックグラウンドジョブです。codex-start ジョブはこのラッパーのジョブテーブルに存在し、MCP クライアントのタスクレジストリにはありません。したがって、クライアント側の「タスクを停止」はそれに到達できません — 到達できるのは、その jobId を持つ codex-cancel だけです。ジョブはこのプロセスを通じてポーリングされるため、再接続を生き延びることは決してできません。したがって、クライアントの切断はすべての非終端ジョブと開いているリクエストをキャンセルし、制限付きの終了処理は、それでも動作し続ける場合には Codex プロセスグループを回収します。

--timeout <seconds> も Codex 呼び出しに対して（デフォルト 7200）不変のハードデッドラインとして適用されます。関連するアクティビティはアイドルウィンドウを延長できますが、このハードデッドラインを延長することは決してありません。クライアントが諦める前に必ずラッパーの明示的なエラーを受け取る必要がある場合は、ラッパーのデッドラインを MCP クライアント自身のウォールクロックツールタイムアウトより短く設定してください。

受信リクエストが _meta.progressToken を提供する場合、ラッパーはその正確なトークンを使用して標準の MCP notifications/progress 更新を送信します。プログレストークンを独自に作り出すことは決してありません。最初の有用なステータスは即座に送信され、それ以降の更新は毎秒最大 1 回にまとめられ、最新のステータスが優先されます。他に何も出力がない作業中は、Codex: still running という通知が 10 秒ごとに送信され、最後にリクエストと関連付けられた Codex イベントからの経過時間が含まれます。

ステータステキストはフェイルクローズドです。ブリッジは、明示的に帰属が示されたコメンタリー、アクティブなプランステップ、およびコマンド、パッチ、MCP ツール、Web／画像作業、サブエージェントに関する一般的なライフサイクルの要約を公開します。最終回答テキスト、推論、プロンプト、コマンド文字列または出力、ツール引数、検索クエリ、ファイルパス、トークンテレメトリは公開しません。メッセージは空白が正規化され、200 Unicode コードポイントに制限されます。ネイティブの codex/event フレームはバイト単位で変更されません。ただし、型付きの unauthorized エラーイベントは、上記の単一の構造化された認証失敗に置き換えられます。進行状況は並行する MCP チャネルであり、通常は追加のツール結果／モデルコンテキストではなく UI ステータスです。

オプションのバックグラウンドジョブ。 既存の codex および codex-reply 呼び出しはブロッキングのままで、現在の動作を維持します。トランスクリプトに表示される更新を必要とするクライアントは、代わりに、Codex ブリッジが公開する 6 つのラッパー所有のジョブツールを使用できます：

長いビルドを含め、ブロッキングの codex 呼び出しを優先してください。 ステータス変更ごとに呼び出し元の 1 ターンではなく 1 回のツール呼び出しで済み、プログレス対応 UI には notifications/progress を引き続きストリーミングし、ターンを中断することでキャンセルされます。ジョブを使用するのは、作業が呼び出し元よりも長生きしなければならない場合だけです — 待つのをやめた後も実行を継続する必要があるか、別のエージェントが後で jobId によってキャンセルできる必要がある場合です。

codex-peek — そのターンはまだ動作していますか？

ブロッキング呼び出しは、返ってくるまで不透明であり、「詰まっている」と「ビジー」が外部からは同一に見えます。codex-peek は、何かをキャンセルすることなく、その疑問に答えます。ブロッキングとバックグラウンドを問わず、進行中のすべての Codex ターンを、読み取り専用かつ即座に一覧表示し、オプションの cwd / threadId / requestId フィルターを受け付けます。

代わりにターンごとのプロセスを探してはいけません。codex mcp-server は長時間稼働し、すべてのリクエストを多重化するため、見つけるべき codex exec はなく、ビルドの実行中にプロセステーブルのチェックは何も報告しません。

見た目ほど意味のない答えが 3 つあります。空のリストはターンが終了した証拠ではありません — 放棄されたターンは Codex 内で実行を継続し、報告すべき進行中のものは何も残っていません。その数は abandonedTurnsProcessWide として返されます — これはそのスコープにちなんで名付けられています。放棄されたターンはワークスペースを保持しないため、フィルターによって絞り込まれることは決してないからです。大きな elapsedSeconds は停止ではありません — それは単なるウォールクロックです — そして大きな lastActivitySeconds も停止ではありません。1 回のツール呼び出しが正当に数分間無音で実行されることがあるため、静かであることは証明されていないだけで、終了したわけでは決してありません。確認のためにキャンセルすることは、元に戻せない唯一のことです。また、cwd フィルターは、ワークスペースが不明なターンを決して隠しません — それは cwdUnknown で報告されます。「判断できない」ことが「そこで何も実行されていない」に静かに変わってはならないからです。

開始結果は、不透明な jobId、ステータスの cursor、および次に推奨される呼び出しとともに即座に返されます。繰り返しの codex-status 呼び出しは通常の MCP ツール結果を生成するため、外側のエージェントやサブエージェントは、その UI が notifications/progress をレンダリングしない場合でも、Codex が何をしているかを中継できます — これはブロッキング呼び出しにはなく、ジョブだけが提供する唯一の可視性です。現在のカーソル位置では、ステータス呼び出しは変更を待ってからハートビートを返します。wait_ms は 0 から 60000 の範囲で設定でき、省略された場合は下記のステータス間隔にデフォルト設定されます（そのペーシングが無効な場合は 10000）。

ステータス待機を終わらせるものは2つあり、どちらもポーリングコストに関係します。カーソル前進は、サーバー側で--codex_status_interval <seconds>（デフォルト30）によってペーシングされ、これは毎メッセージごとにカーソルを進める代わりに中間的な進捗を結合します。もう1つは**wait_msハートビートで、こちらはその間隔によってペーシングされません。そのためwait_msは、ハートビートがレポート対象のカーソルを追い越さないよう、ステータス間隔を追跡します（60000で上限設定されるため、60秒を超える間隔でも60秒ごとにハートビートします）。wait_msはあくまでアイドル待機の上限であり、ポーリング間隔の下限ではありません。カーソルがすでに先頭より遅れている場合、ステータス呼び出しは即座に**返るため、遅れているポーラーはwait_msを上げても遅くできません。ただし追いついているポーラーは遅くできます。これがwait_msを下げるとターン数が無駄になる理由です。

ペーシングされるのは中間的な進捗更新のみです。ライフサイクル遷移（最初のrunning、キャンセル、および任意の終端状態）はカーソルを進め、間隔をバイパスしてすべての待機者を直接起こすため、間隔を上げても完了が遅れることはありません。ストール検出も同様に影響を受けません。lastActivitySecondsは生のCodexイベントからスタンプされ、ステータスティックからではありません。またcodex-commentaryは完全なナラティブを保持し続けます。0はすべての変更でカーソル前進を復元します。60を超える値はハートビート上限に制御を委ね、ステータステキストを古くさせるだけです。進捗通知は独自の、はるかに細かいケイデンスを維持し、呼び出し側にコンテキストコストがかかりません。ただし、これらはブロッキング呼び出しでのみ発行されることに注意してください。バックグラウンドジョブのリクエストには進捗トークンが含まれないため、ジョブの可視性はcodex-status / codex-commentaryのみです。

commentaryEndOffsetが進んだら、最後のnextOffsetを指定してcodex-commentaryを呼び出します。コメンタリーには、commentaryフェーズで明示的にマークされたCodexメッセージのみが含まれます。隠れた推論、プロンプト、最終回答のドラフト、コマンド文字列と出力、ツール引数、パス、検索クエリ、生のレスポンスアイテムは除外されます。安全でないターミナル制御は除去されますが、残りのテキストはモデルが作成したものであり、依然として信頼できないものとして扱う必要があります。オフセットはUnicodeコードポイントを数えます。各読み取りは最大32,768コードポイントを返します。ブリッジは1MiBのUTF-8テールを保持し、古いコメンタリーがバッファから落ちた場合は絶対切り捨て境界を報告します。

ステータスが終端状態になると、codex-resultを使用し、doneがtrueになるまでnextOffsetから続行します。各ページはペイロードを、通常のMCPテキストコンテンツと、構造化結果を優先するクライアント向けのstructuredContent.textの両方として返します。結果ページも32,768コードポイントに上限があります。ブリッジの10MiBキャプチャ制限より大きいネイティブ結果フレームは、プライベートレスポンスをMCPトランスポートに漏らす代わりに、ジョブを原子的に失敗させます。

ジョブは意図的に接続ローカルです。MCPサーバーを再起動または再接続すると失われます。アクティブなジョブは最大8つ、保持されるレコードは32件までで、終端レコードは1時間後に期限切れになります。キャンセルはブロッキング呼び出しと同じ境界付き解決セマンティクスを持つため、キャンセルされた書き込み可能ジョブを再試行する前に作業ツリーを検査してください。ジョブAPIは呼び出しレベルのオプトインであり、クライアントのMCP Tasksサポートを必要としません。

これらの通知は意図的に進捗対応クライアントのアイドルウィンドウを維持し、存続権限はラッパーのアイドルおよびハードデッドラインに委ねます。これらは--codex_idle_timeoutを更新せず、ラッパーのハードデッドラインを延長せず、クライアントの独立したハード壁時計ツールタイムアウトも延長しません。生成された進捗フレームはネイティブの改行境界でのみ挿入されます。Codexがフレーム途中でストールした場合、最新の通知は安全な境界を待ち、実アイドルウォッチドッグが恒久的なストールを終了させます。クライアントタイムアウトは、想定される最長のCodex実行時間にレスポンスヘッドルームを加えた値を超えるように設定してください。期限切れになると、クライアントは呼び出しをキャンセルし、以下の境界付きキャンセルパスが引き継ぎます。

終端結果のリカバリ。 Codexは早期のリクエスト相関セッションイベントでスレッドIDを通知するため、ラッパーはビルド完了前にそれを保持します。Codexが後で終端完了イベントと最終エージェントメッセージを発行しても、ネイティブのtools/callレスポンスが短い終端レスポンス猶予期間内に到着しない場合、ラッパーはcontentとstructuredContent.threadIdの両方を含む同等の成功結果を返します。一致する遅延ネイティブレスポンスは破棄され、JSON-RPCレスポンスのexactly-onceセマンティクスを維持します。これは、作業がツリーに反映されたものの、呼び出し側が結果もスレッドIDも受け取れなかった障害モードをカバーします。

キャンセルと再接続。 クライアントのキャンセルは、--codex_cancel_graceによって制限される短いリセット不可の猶予期間を開始します（以下のフレーム途中のエスカレーションが2つ目の猶予期間を設定するため、そのパスは約2倍の時間がかかることがあります）。Codexがその期間内に解決しない場合、ラッパーはそのリクエストIDをローカルで解決し、Codexの遅延レスポンスを抑制し、ブリッジとすべての兄弟呼び出しを実行したままにします — 単一のストールした呼び出しがブリッジ全体をダウンさせてはなりません。2つの境界付き例外があります：フレーム途中で詰まりキャンセルも無視するストリーム（エラーを注入できる安全な境界がないため、ラッパーは1回再試行してからブリッジ全体のティアダウンにエスカレーションします）、および集計上限です。抑制されたレスポンスがMAX_SUPPRESSED_CODEX_RESPONSESに達すると、ブリッジはそれらを無期限に追跡する代わりに終了します。どちらの後も、クライアントは新しいブリッジに再接続します。猶予期間内に到着したネイティブレスポンスは、部分的に転送されたフレームを破損させずにインターセプトできる場合は常に破棄されます。キャンセルされた、書き込み可能な可能性のある呼び出しは自動的に再実行されません。キャンセルはベストエフォートであり、Codexが停止したことを証明するものではありません — 未確認のターンは終了ではなく放棄として記録され、実行を継続してワークスペースに書き込む可能性があるため、手動で再試行する前に作業ツリーを検査してください。

このレガシーブリッジは意図的に、既存のstdio接続内でcodex mcp-serverを再スポーンしたり、スレッドを透過的にリプレイしたりはしません。codex-reply状態は古いCodexプロセスに属するため、破棄された子プロセスのスレッドIDは再接続後に再開できません。耐久性のある同一接続リカバリには、透過的なレガシーパススルーからcodex app-server（thread/start、turn/start、turn/interrupt、thread/resume）上のMCPアダプターへの個別の移行が必要です。

Claude Codeとの統合

グローバルにインストールされたmcp-agentsバイナリを使用して、プロジェクトの.mcp.jsonにエントリを追加します：

{
  "mcpServers": {
    "codex": {
      "command": "mcp-agents",
      "args": ["--provider", "codex"],
      "timeout": 7500000
    },
    "gemini": {
      "command": "mcp-agents",
      "args": ["--provider", "gemini"]
    }
  }
}

npm（グローバルインストール）vs npx — グローバルにインストールされたバイナリを推奨します。 上記のcommand: "mcp-agents"形式はローカルにインストールされたバイナリを直接起動します。以下のnpx代替案は毎回のプロセス起動時にnpx -y mcp-agentsを実行します。これはコールドスタート速度だけでなく信頼性に関わります。Claude Codeは（再）接続のたびにstdioサーバーを再起動します（セッション途中の再接続後を含めて）。そしてnpxは、オフラインのフォールバックなしに毎回の起動時にパッケージレジストリ解決を実行します。その解決が遅い場合（VPN、キャプティブポータル、レジストリの不調）、もはや存在しないバージョンに古いキャッシュが残っている場合（npm error code ETARGET）、またはその他の理由で失敗する場合、起動が失敗し、トランスポートが閉じ、ツールはセッション中失われます。グローバルにインストールされたバイナリ（またはnode server.jsへの絶対パス）は、ネットワーク依存関係と、シグナル/ティアダウンパスからの1つのプロセスレベルを削除します。npm install -g mcp-agentsで一度インストールし（またはソースチェックアウトからnpm link）、設定をそれに向けます。

ソースチェックアウトを個人用のCodexブリッジとして使用する場合、ユーザーレベルの~/.claude.jsonエントリはツリーを直接起動し、リクエストごとのアイドル上限を無効にできます（長く正当に無音のレビューが、早期に中止されるのではなく、クライアント自身の壁時計タイムアウトのみで制限されるように）：

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-agents/server.js", "--provider", "codex", "--codex_idle_timeout", "0"],
      "env": {},
      "timeout": 3600000
    }
  }
}

ベアnodeはMCPクライアントのPATHに対して解決されます。nodeが、その環境で初期化されていないバージョンマネージャー（nvm/fnm/asdf）によって管理されている場合は、代わりに絶対nodeパスを使用します（which node、例：/opt/homebrew/bin/node）。

サーバー起動時にcodexのデフォルトを上書きします：

{
  "mcpServers": {
    "codex": {
      "command": "mcp-agents",
      "args": ["--provider", "codex", "--model", "gpt-5.6-sol", "--model_reasoning_effort", "xhigh", "--codex-workspace-network=false"],
      "timeout": 7500000
    }
  }
}

最初のcodex呼び出しごとに、gpt-5.6-solまたはgpt-5.6-terraと、medium、high、xhigh、またはmaxを選択できます。省略されたセレクターはサーバーのデフォルトを使用し、応答は両方の選択を継承します。他のモデル、生のconfig、および呼び出しごとの承認ポリシー引数は、Codexが実行される前に拒否されます。デフォルトの目標を提供するにはargsに"--goal", "<text>"を追加します（上記のGoal注入を参照）。

Claudeはサーバーごとのtimeoutをミリ秒単位のハード壁時計上限として解釈します。進捗はそれを延長しません。ラッパーの--timeout（デフォルト7,200秒）を上回るように、レスポンスヘッドルームを含めて設定してください。プロジェクトの.mcp.jsonエントリは同じ名前のユーザーレベルのMCPエントリを上書きできるため、ユーザーレベルのコピーに頼るのではなく、プロジェクトエントリにタイムアウトを設定してください。

上記で説明した明示的なFast-modeペアを除き、ブリッジは通常の~/.codex/config.tomlから設定を継承しません。特に、継承されたMCPサーバーはブリッジされたCodexセッション内では意図的に利用できません。

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "mcp-agents", "--provider", "codex"],
      "timeout": 7500000
    }
  }
}

npxはプロセス起動にのみ影響します。接続後は、ツール呼び出しのレイテンシはどちらの場合も同じサーバーコードです。ただし、すべての起動（再接続を含む）は、オフラインのフォールバックなしでnpmレジストリに対してパッケージを解決するため、遅い、オフライン、または古いキャッシュの解決は起動を失敗させ、セッション途中でツールを失う可能性があります（上記のnpm vs npxを参照）。mcp-agents@x.y.zを固定すると、セッション途中の@latestが新しく公開されたバージョンを取得するのを防ぎますが、起動ごとのネットワーク依存関係は削除されません。ゼロインストールが起動の信頼性よりも重要な場合にのみnpxを使用してください。

OpenAI Codexとの統合

~/.codex/config.tomlに2つのエントリを追加します — 利用可能にしたいプロバイダーごとに1つです。960秒のClaudeクライアントタイムアウトは、ブロッキングの900秒claude_codeツールとの互換性を維持します。バックグラウンドレビューは1つのMCPリクエストを開いたままにしません：claude-startは即座に返り、各claude-statusポーリングは最大60秒です。

[mcp_servers.claude-code]
command = "mcp-agents"
args = ["--provider", "claude"]
tool_timeout_sec = 960

[mcp_servers.claude-code.tools.claude-start]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-status]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-result]
approval_mode = "approve"

[mcp_servers.claude-code.tools.claude-cancel]
approval_mode = "approve"

[mcp_servers.gemini]
command = "mcp-agents"
args = ["--provider", "gemini"]
tool_timeout_sec = 360

Codexセッションで、Claudeのセカンドオピニオンまたはレビューを依頼し、claude-start → claude-status → claude-resultを使用します。小さなブロッキングプロンプトにはclaude_codeを保持します。geminiはブロッキングツールのままです。

開発

npm install
npm link          # symlinks mcp-agents to your local server.js

npm link後、server.jsへの編集は即座に反映されます — 再インストールは不要です。

実際の/tmpプロジェクト.mcp.jsonファイルを通じて起動パスをベンチマークします：

npm run bench:mcp-startup

これはinitializeからtools/listまでのMCP起動を測定します。プロバイダーモデル/ツールは呼び出しません。

手動のClaudeバックグラウンドチェックでは、短いレビュープロンプトとこのリポジトリをcwdとしてclaude-startを呼び出し、返された各カーソルでclaude-statusをポーリングし、claude-resultで判定を読みます。逆方向では、Claude Codeにcodex-startを呼び出させ、codex-statusをポーリングし、codex-resultを読みます。これらのスモークチェックは実際のモデル呼び出しを使用し、決定論的なテストスイートゲートとは別のものです。

仕組み

1. MCPクライアントがstdio経由で接続します

2. サーバーはargvから--provider <name>を読み取ります（デフォルトはcodex）

3. Geminiは1つのブロッキングCLIツールを登録します。Claudeはレガシーブロッキングツールに加えて一回限りのレビュージョブツールを登録します。Codexはネイティブツールを転送し、バックグラウンドジョブツールを追加します

4. クライアントはツール名とpromptを指定してtools/callを呼び出します

5. サーバーはCLIをデタッチされた子プロセスとして実行します。ClaudeレビュージョブはストリームJSONを安全なステータスと保持された結果ページに解析し、ブロッキングツールは正規化されたプロバイダー出力を返します

サーバーは、非同期サブプロセスがアクティブハンドルを登録する前にstdinがEOFに達した場合にNode.jsが早期に終了しないように、小さなキープアライブタイマーを保持しています。ClaudeおよびGeminiプロバイダーモードでは、そのキープアライブはシャットダウン中にクリアされます。MCP stdio接続が閉じると、アクティブなClaudeジョブは割り込みと時間制限付きTERM/KILLフォールバックを受け取り、サーバーが終了する前に、残りの追跡対象デタッチ済みプロバイダープロセスグループが回収されます。

ライセンス

MIT