codex-mcp-bridge

codex-mcp-bridge

Codex CLIをサブプロセスとしてラップし、コード実行、ウェブ検索、構造化出力をModel Context Protocolツールとして提供するMCP サーバーです。

Claude Code、Gemini CLI、Cursor、Windsurf、VS Codeなど、MCPに対応するあらゆるMCPクライアントで利用できます。

これは必要ですか？

シェルにアクセスできるターミナルエージェント（Claude Code、Codex CLI、Gemini CLI）を使用している場合は、Codex CLIを直接呼び出してください。より速く、低コストで、オーバーヘッドもありません。

# Review current branch vs main
codex review --base main

# Review uncommitted changes
codex review --uncommitted

# Review with custom focus
codex review --base main "Focus on security and error handling"

# From a worktree (run inside the worktree; `-C` is broken for `review`)
cd /path/to/worktree && codex review --base main

# General analysis
codex exec "Analyze src/utils/parse.ts for edge cases"

次の場合は、代わりにこのMCPブリッジを使用してください：

• クライアントがシェルにアクセスできない場合（Cursor、Windsurf、Claude Desktop、VS Code）
• JSON Schemaによる検証付きの構造化出力が必要な場合（Codex CLIの--jsonには既知の不具合があります）
• タイムアウト時に部分的なレスポンスを取得したり、クォータ超過時にモデルを自動でフォールバックさせたりする必要がある場合
• サブプロセスの分離が必要な場合：明示的な環境変数の許可リスト、シェルエスケープの防止、出力時のシークレットのマスキング、FIFOキューによる同時実行（並列起動は最大3件、CODEX_MAX_CONCURRENTで設定可能）
• セッション再開（sessionId／resetSession）による複数ターンの会話が必要な場合（listSessionsで確認可能）

Worktreeに関する注意：Codex CLIのイシュー#9084により、codex -C /path review ...が動作しません。この問題を避けるには、worktree内からcodex reviewを実行してください。

クイックスタート

npx codex-mcp-bridge

前提条件

• Codex CLIがインストールされていること（npm i -g @openai/codex）
• OPENAI_API_KEY環境変数を設定するか、codex auth loginを完了していること

Claude Code

claude mcp add codex-bridge -- npx -y codex-mcp-bridge

Gemini CLI

~/.gemini/settings.jsonに追加します：

{
  "mcpServers": {
    "codex-bridge": {
      "command": "npx",
      "args": ["-y", "codex-mcp-bridge"]
    }
  }
}

Cursor／Windsurf／VS Code

MCP設定に追加します：

{
  "codex-bridge": {
    "command": "npx",
    "args": ["-y", "codex-mcp-bridge"],
    "env": {
      "OPENAI_API_KEY": "sk-..."
    }
  }
}

ツール

ツール	説明
codex	ファイルコンテキスト、セッション再開、サンドボックス制御を使ってプロンプトを実行します。セッションIDによる複数ターンの会話に対応します。自由形式のレビュー用プロンプトに使用してください。詳しくはこのCLIを使ったコードレビューを参照してください。
review	codex exec review --jsonを使った、差分を認識するCodexのネイティブレビューです。呼び出し元のプロンプトは不要で、未コミットの変更、ベースブランチ、コミットのレビューに対応します。
search	codex --searchによるウェブ検索です。情報源のURLを含む、要約された回答を返します。
query	軽量なテキスト分析です。リポジトリのコンテキストやセッションは使用せず、分離された一時ディレクトリで実行します。
structured	Ajvを使ってJSON Schemaに準拠した出力を検証します。データ抽出、分類、または機械で解析できる出力が必要なあらゆるタスクに使用します。
ping	CLIのバージョン、機能、同時実行の診断情報（activeCount、queueDepth）を確認します。
mcpStatus	Codexが認識している各MCPサーバーについて、認証タイプ、ツール一覧、初期化されたかどうかを報告します。オプションの診断モードでは、明示的な失敗状態とエラーテキストも追加されます。
listSessions	アクティブな会話セッションを、メタデータ（ターン数、モデル、タイムスタンプ）とともに一覧表示します。

codex

汎用実行機能です。sessionId による複数ターンの会話、サンドボックスレベル（read-only、workspace-write、full-auto）、推論の労力の制御に対応しています。resetSession: true を渡すと、セッションを破棄して新しく開始します。再開する前に listSessions を使ってアクティブなセッションを確認できます。

主なパラメーター：prompt（必須）、files、model、sessionId、sandbox、reasoningEffort、workingDirectory、timeout（デフォルトは60s）。

search

Codex CLI の --search フラグを介して、OpenAI ネイティブの検索インフラストラクチャを利用したウェブ検索を行います。ソース URL を含む、統合された回答を返します。

主なパラメーター：query（必須）、model、workingDirectory、timeout（デフォルトは120s）。

query

軽量な非エージェント型のテキスト分析です。隔離された一時ディレクトリで実行されるため、ブリッジのリポジトリコンテキストが漏れることはありません。分析するテキストは context パラメーターに渡します。reasoningEffort と maxResponseLength に対応しています。

主なパラメーター：prompt（必須）、context、model、reasoningEffort、timeout（デフォルトは60s）。

review

Codex CLI ネイティブの差分対応レビューを行う薄いラッパーです。ブリッジは差分セレクターを codex exec review --json に渡し、レビュー用プロンプトは上流の Codex が管理します。workingDirectory には実際の git リポジトリを指定する必要があります。

主なパラメーター：mode（必須：uncommitted、base、または commit）、workingDirectory（必須）、base（base モードで必須）、commit（commit モードで必須）、title、model、timeout（デフォルトは180s）。

structured

プロンプトに JSON Schema を埋め込み、Ajv で応答を検証します。成功時は整形済みの JSON を、失敗時は検証エラーを返します。

主なパラメーター：prompt（必須）、schema（必須、JSON 文字列）、files、model、workingDirectory、timeout（デフォルトは60s）。

ping

パラメーターはありません。CLI のバージョン、認証状態、モデル設定、並行処理の診断情報（activeCount、queueDepth）を返します。

mcpStatus

Codex 独自の app-server プロトコルから見た、サーバーごとの MCP 状態を報告します。他のすべてのツールとは異なり、測定対象そのものが無効になるため、Codex の MCP サーバーを抑制せず、サブプロセス環境の強化も意図的に行いません。そのため、~/.codex/config.toml に設定されたサーバーを起動するので、通常の呼び出しより時間がかかります。diagnostics: true を指定し、信頼済みプロジェクト内の workingDirectory を指定すると、起動するスレッドによって、そのプロジェクトの .codex/config.toml のサーバーも起動されます。

主なパラメーター：diagnostics（デフォルトは false）、workingDirectory、timeout（リクエストごと、デフォルトは90s）。

モード	所要時間	得られる情報
default	~6-9s	インベントリ：認証タイプ、ツール名と数、サーバーごとの initialized / unknown。スレッドは作成されず、セッション記録も書き込まれません。
diagnostics: true	~10-20s	明示的な failed 状態と、原因を示すエラーテキスト（期限切れの OAuth グラント、バイナリの欠落、リモート側の拒否）が追加されます。一時的なスレッドを起動しますが、ディスク上に作成されることはありません。

出力の読み方：

• unknown は失敗ではありません。 インベントリにサーバー情報がなく、明示的な判定も得られなかったことを意味します。failed を報告できるのは diagnostics: true の場合のみです。
• degraded の警告がある場合、unknown を信用しないでください。 呼び出しに時間がかかると、正常なサーバーが未初期化として報告されることが確認されています。そのため、このツールは基盤となる呼び出しにかかった時間を報告し、疑わしいほど遅かった場合は結果にフラグを付けます。
• builtIn は、設定ファイルにはないものの Codex が注入するサーバーを示します。configuredButUnreported は、設定ファイルにはあるものの Codex が一度も言及しなかったサーバーを示します。

例：

atlassian            failed       auth=oAuth  tools=0
    error: MCP client for `atlassian` failed to start: MCP startup failed: failed to
    refresh OAuth tokens for server atlassian: ... invalid_grant: Grant not found
codex_apps           initialized  auth=bearerToken  tools=117  (builtIn)
linear               initialized  auth=oAuth  tools=57
serena               initialized  auth=unsupported  tools=22

すべてのツールは、durationMs、model、fallbackUsed、および該当する場合はセッション情報を含む実行メタデータ（_meta）を付加します。詳細は DESIGN.md を参照してください。

この CLI を使ったコードレビュー

このブリッジにはレビュー用プロンプトは同梱されていません。コードレビューには3つの方法があります。

ネイティブのアップストリーム codex review

codex review --base main
codex review --uncommitted
codex review --base main "Focus on security and error handling"

Codex CLI に組み込まれた、差分を認識するレビューです。ブリッジは関与しません。クライアントからシェルにアクセスできる場合に使用してください。

ネイティブの差分認識レビュー用ブリッジ review ツール

{
  "tool": "review",
  "arguments": {
    "mode": "base",
    "base": "main",
    "workingDirectory": "/path/to/worktree"
  }
}

ブリッジは workingDirectory から codex exec review --json を実行し、最終的なレビューのテキストを取得して、threadId、イベント数、秘匿化されたコマンド出力などのレビューのメタデータを返します。プロンプトは受け付けません。

呼び出し元が指定したプロンプトを使うブリッジ codex ツール

{
  "tool": "codex",
  "arguments": {
    "prompt": "<your review prompt + diff or file references>",
    "sandbox": "read-only"
  }
}

ブリッジは指定されたプロンプトを使って codex exec --sandbox read-only を実行し、標準出力を返します。自由形式のレビュープロンプトや、uncommitted、base、commit の差分セレクターでは表現できないレビュー入力に使用してください。

代表的なレビュープロンプト

出発点として、自由に調整してください。

Review the following diff:

<diff content>

Look for:
- Bugs that would surface in production
- Missing error handling on user-supplied input
- Tests modified to silence failures rather than verify behaviour
- Security issues (injection, missing auth checks, secret leaks)

For each finding cite file:line, severity (high/medium/low), and a suggested fix.
Skip style/formatting; assume an autoformatter handles those.

ブリッジはプロンプトの内容に関与しません。理由については、ADR-001 を参照してください。

設定

変数	デフォルト	説明
CODEX_DEFAULT_MODEL	(CLI のデフォルト)	すべてのツールで使用するデフォルトモデル
CODEX_FALLBACK_MODEL	o3	クォータ超過時のフォールバック（無効にするには none）
CODEX_CLI_PATH	codex	CLI バイナリへのパス
CODEX_MAX_CONCURRENT	3	同時に起動するサブプロセスの最大数
CODEX_MCP_SERVERS	(未設定)	有効な状態を維持する Codex 内部 MCP サーバーを制御します。DESIGN.md を参照してください。
CODEX_HOME	~/.codex	サブプロセスが認証情報を読み込むルート

2 つ目の Codex アカウントでブリッジを実行する

CODEX_HOME は ID を完全に切り替えます。認証情報、config.toml、スキル、スレッド履歴はすべてルートの下に保存されるため、2 つ目のルートは 2 つ目のインストールになります。このブリッジが行うすべてのツール呼び出しは、誰かが前に座って操作しているセッションではなくマシンの通信です。そのため、対話型の codex で個人用アカウントを使い続けながら、仕事用またはチーム用のアカウントを使うのに適しています。

クライアントを起動したターミナルに選択が左右されないよう、環境変数はシェル全体ではなくサーバー登録時に設定してください。

{
  "mcpServers": {
    "codex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codex-mcp-bridge"],
      "env": {
        "CODEX_HOME": "/home/you/.codex-work",
        "CODEX_DEFAULT_MODEL": "gpt-5.6-sol"
      }
    }
  }
}

設定する前に、次の 3 点を確認してください。

• **まず、そのルートでログインしてください。**ルートは認証情報があって初めて使用できます。CODEX_HOME=/home/you/.codex-work codex login（または codex login --with-api-key）を実行してください。CODEX_HOME=/home/you/.codex-work codex login status で確認できます。
• **JSON の env ブロックには条件分岐がありません。**そのルートのログインが失効すると、ブリッジが起動するすべてのサブプロセスはそのルートを使用します。シェルラッパーのようにデフォルトのルートへフォールバックすることはできません。
• **CODEX_DEFAULT_MODEL も一緒に設定してください。**ブリッジは CODEX_HOME から config.toml を解決するため、新しく作成したルートには config.toml がなく、モデルは CLI のデフォルトに戻ります。また、設定がない場合は無効にする対象も継承するものも有効にする名前もないため、CODEX_MCP_SERVERS の大部分も機能しません。これはデフォルト設定の意図どおりです。ただし、{ または [ で始まる値で指定する生の TOML オーバーライドだけは無効になりません。これは -c mcp_servers=... としてそのまま渡され、config.toml は読み込まれません。

Codex MCP サーバーの選択

必要な機能...	検討する候補
構造化出力、モデルのフォールバック、並行実行の管理、セッションの再開	このブリッジ
conversationId によるセッションのスレッド化、コールバック URI の転送	@tuannvm/codex-mcp-server
承認ポリシーに対応した構造化パッチ出力	cexll/codex-mcp-server
並列サブエージェントに対応した最小限の codex exec ラッパー	codex-as-mcp
ネイティブ Codex MCP（実験的、ラッパー不要）	codex mcp serve（ドキュメント）

パフォーマンス

Codex CLI の起動時のオーバーヘッドは最小限（<100ms）なので、実行時間の大部分はモデルの推論に費やされます。

シナリオ	標準的な時間
簡単なプロンプト	9-12s
ウェブ検索	~17s

デフォルトのタイムアウト（60-300s）は、一般的なワークロードに十分な余裕があります。

ブリッジファミリー

同じアーキテクチャで、基盤となる CLI が異なる 2 つの MCP サーバーです。どちらもターミナルエージェントをサブプロセスとしてラップし、MCP ツールとして公開します。利用するモデルプロバイダーに合うものを選ぶか、複数モデルのワークフローで両方を実行してください。

	codex-mcp-bridge	claude-mcp-bridge
CLI	Codex CLI	Claude Code
プロバイダー	OpenAI	Anthropic
ツール	codex、review、search、query、structured、ping、listSessions	query、review、search、structured、ping、listSessions
コードレビュー	ネイティブの codex exec review --json をラップする review ツール、または呼び出し元がプロンプトを指定する codex ツール	呼び出し元がプロンプトを指定し、強化された分離のデフォルト設定を備える review ツール
構造化出力	Ajv による検証	ネイティブの --json-schema
セッションの再開	複数ターンに対応するセッション ID	ネイティブの --resume
予算上限	非対応	ネイティブの --max-budget-usd
推論レベルの制御	reasoningEffort（low/medium/high）	--effort low/medium/high/max
コールドスタート	<100ms（推論が大部分を占める）	~1-2s
認証	OPENAI_API_KEY	claude login（サブスクリプション）または ANTHROPIC_API_KEY
コスト	トークンごとの従量課金	サブスクリプション（料金に含まれる）または API クレジット
同時実行数	3（設定可能）	3（設定可能）
モデルのフォールバック	フォールバックモデルで自動再試行	フォールバックモデルで自動再試行

両者に共通する機能：サブプロセス環境の分離、パスのサンドボックス化、出力の秘匿化（シークレットの除去）、FIFO 方式の同時実行キュー、MCP ツールのアノテーション、_meta レスポンスメタデータ、進捗のハートビート。

開発

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit

関連資料

• DESIGN.md - アーキテクチャ、MCP サーバーの制御文法、セッション、出力の解析、レスポンスメタデータ
• SECURITY.md - 環境の分離、パスのサンドボックス化、出力の秘匿化、リソース制限
• CHANGELOG.md - リリース履歴

ライセンス

MIT