Codex Supervisor MCP

コード互換ホストが Codex app-server の作業を開始、監視、誘導、中断、再開、承認できるようにするローカル Model Context Protocol (MCP) ブリッジです。

codex app-server をラップするものであり、ターミナル UI を自動化したり IDE をスクレイピングしたりするものではありません。

機能

サーバーは以下の MCP ツールを公開します:

Related MCP server: Codex Bridge MCP

要件

• Node.js 22 以降。

• 現在の Codex CLI が codex として利用可能であること。

• Codex CLI の認証がすでに設定されていること。

• 1 つ以上の明示的なローカルリポジトリルート。

このプロジェクトには npm のランタイム依存関係はありません。

パッケージの検証

npm test

テストスイートはプロトコル互換のモック app-server を使用します。モデルリクエストは行わず、Codex の認証も必要としません。

Codex CLI でのインストール

MCP サーバー名として codex-supervisor を使用します。この名前は CODEX_SUPERVISOR_MCP_NAME と一致している必要があります。ブリッジはこの名前を使用して、子の app-server がこの同じ MCP サーバーを再帰的に読み込むのを防ぎます。

macOS または Linux

codex mcp add codex-supervisor \
  --env CODEX_ALLOWED_ROOTS="/Users/you/code:/Users/you/work" \
  --env CODEX_SUPERVISOR_MCP_NAME="codex-supervisor" \
  -- node "/absolute/path/to/codex-supervisor-mcp/src/index.mjs"

ルート間の区切りにはプラットフォームのパスリスト区切り文字を使用します。macOS と Linux ではコロン (:) です。

Windows PowerShell

codex mcp add codex-supervisor `
  --env CODEX_ALLOWED_ROOTS="C:\src;D:\work" `
  --env CODEX_SUPERVISOR_MCP_NAME="codex-supervisor" `
  -- node "C:\absolute\path\to\codex-supervisor-mcp\src\index.mjs"

Windows ではパスリストの区切り文字はセミコロン (;) です。

登録を確認します:

codex mcp list

Codex で /mcp と入力して、接続されたサーバーを確認します。

config.toml でのインストール

examples/config.toml をコピーして調整し、その内容を ~/.codex/config.toml または信頼できるプロジェクトの .codex/config.toml に配置します。

絶対パスを使用してください。サーバー ID と CODEX_SUPERVISOR_MCP_NAME は同一に保ってください。

ChatGPT デスクトップまたは Codex IDE 拡張機能

1. Settings → MCP servers → Add server を開きます。

2. 名前を codex-supervisor に設定します。

3. STDIO を選択します。

4. コマンドを node に設定します。

5. src/index.mjs への絶対パスを唯一の引数として追加します。

6. CODEX_ALLOWED_ROOTS と CODEX_SUPERVISOR_MCP_NAME=codex-supervisor を追加します。

7. 保存してホストを再起動します。

8. /mcp と入力してツールを確認します。

ローカル STDIO MCP サーバーは、通常の ChatGPT Web チャットでは読み込まれません。Web からこのブリッジを使用するには、別途デプロイされた認証付きリモート MCP サービスまたはホスト型プラグインが必要です。

一般的なワークフロー

MCP ホストに次のように依頼します:

Use codex_start in /absolute/path/to/repository to implement the requested
change. Use workspaceWrite, keep network access disabled, wait for progress,
show me every approval request before resolving it, and report the final diff
and test result.

ホストは次の順序に従う必要があります:

codex_start -> codex_wait
  approval request -> inspect -> codex_resolve_approval -> codex_wait
  active correction -> codex_steer -> codex_wait
  completed -> codex_status
  later follow-up -> codex_send -> codex_wait

start/send/steer/interrupt の各呼び出しは eventCursor を返します。これを codex_wait または codex_status の afterSequence として渡すことで、古いイベントの再再生を避けられます。

approvalPolicy は現在の app-server ワイヤ値である on-request(デフォルト)と untrusted を受け入れます。レガシー値の onRequest と unlessTrusted はブリッジによって受け入れられ、app-server リクエストの前に正規化されます。

公開承認 API は、Codex app-server リリースがそのリクエストに対して cancel のみを宣伝している場合でも、decline を受け入れます。その場合、ブリッジは安全な app-server キャンセル応答を使用し、要求された決定と実際の決定の両方を報告します。

設定

デフォルトの app-server 引数は次と同等です:

-c mcp_servers.<CODEX_SUPERVISOR_MCP_NAME>.enabled=false app-server

CODEX_APP_SERVER_ARGS を上書きすると、その再帰ガードが削除されます。自分で同等の無効化上書きを含めてください。

セキュリティモデル

• CODEX_ALLOWED_ROOTS は必須です。

• パスは realpath で正規化されます。シンボリックリンクによるエスケープは拒否されます。

• Codex は選択されたリポジトリとプラットフォームのデフォルトへの制限付き読み取りアクセスを受け取ります。

• workspaceWrite は書き込み可能なルートを選択されたリポジトリに制限します。

• dangerFullAccess は公開されません。

• ネットワークアクセスには、CODEX_ALLOW_NETWORK=1 とタスク上の networkAccess: true の両方が必要です。

• ブリッジには汎用的でサンドボックス化されていないシェルツールはありません。

• コマンド実行とファイル変更の承認は明示的に解決する必要があります。

• 許可されたルートの外にあるスレッドは拒否またはフィルタリングされます。

• イベントペイロードは保存前にサイズ制限されます。

• 保存されたスレッドパスは使用時に再正規化されます。削除または置換されたリポジトリパスはフェイルクローズします。

• 同じスレッドへの変更、承認応答、および再試行されたリモート呼び出しは、2 回実行されるのではなく、直列化または重複排除されます。

• 転送エラーは、STDIO または HTTP 境界を越える前に再帰的に編集され、サイズ制限されます。

• リレーおよびリモートサーバーの資格情報(BIOTELE_* および CODEX_REMOTE_*)は、子 Codex 環境から削除されます。

• リモート結果の送信は HMAC 認証され、base64url エンコードされ、制限付きチャンクに分割され、使用前に長さと SHA-256 で検証されます。エンコーディングはトランスポートをコンテンツフィルターから保護します。これは暗号化ではありません。

子の app-server は、非リレーのプロセス設定とより広範な Codex 構成を引き続き継承します。信頼できないコードで使用する前に、他の環境シークレット、アプリ、スキル、フック、設定済み MCP サーバーを監査してください。環境のストリップはオペレーティングシステムのセキュリティ境界ではありません。同じ Windows ユーザーとして実行されている子は、ユーザースコープの設定を意図的に照会できます。その脅威が範囲内にある場合は、専用の Windows アカウントを使用してください。

サポートされている承認リクエスト

このリリースは次を解決します:

• item/commandExecution/requestApproval

• item/fileChange/requestApproval

他の app-server リクエストは codex_status と codex_list_approvals で表示されたままですが、ブリッジはそれらへの応答を拒否します。これにより、汎用応答エンドポイントが暗黙的に権限を付与したり、機密性の高いユーザー入力を提供したりすることを防ぎます。

永続化とモニタリング

Codex は永続化されたスレッド履歴を所有します。ブリッジは、ストリームされたイベントバッファー、最新の差分、保留中のリクエスト状態をメモリに保持します。MCP サーバーを再起動すると、その一時状態はクリアされますが、codex_list_threads と codex_read_thread を使用して、承認済みの永続化スレッドを回復できます。

開発

npm test
node --check src/index.mjs

プロジェクトレイアウト:

src/app-server-client.mjs  Codex app-server JSONL client
src/approval-policy.mjs    Approval-policy validation and legacy normalization
src/event-store.mjs        Bounded event, turn, and approval state
src/security.mjs           Repository-root policy
src/supervisor-service.mjs Codex lifecycle orchestration
src/tool-registry.mjs      MCP tool schemas and validation
src/mcp-server.mjs         Dual-era MCP STDIO transport
src/index.mjs              Entrypoint
test/                      Unit and integration tests

ライセンス

MIT

Codex App Server 互換性

バージョン 1.0.3 は、turn/start から非推奨の readOnly.access フィールドと workspaceWrite.readOnlyAccess フィールドを削除します。現在の Codex App Server リリースは、クライアントがカスタムの制限付き読み取りスコープを必要とする場合に権限プロファイルを使用します。スーパーバイザーは引き続き書き込み可能なルートを選択されたリポジトリに制限し、すべてのタスクディレクトリを CODEX_ALLOWED_ROOTS に対して検証します。

Hostinger リモートリレー

バージョン 1.2.5 は、ChatGPT リモート MCP アクセス用の Hostinger 互換リレーを提供します:

ChatGPT -> OAuth bearer JWT -> Hostinger /mcp -> namespace-routed queue
  codex_*  -> outbound Windows local-agent -> Codex app-server
  reeves_* -> outbound Reeves Android agent -> accessibility service

公開 /mcp エンドポイントは、外部アイデンティティプロバイダーからの RS256 OAuth アクセストークンを検証します。Windows エージェントと Reeves エージェントは、アウトバウンドポーリング、ステータス、リース取得、結果送信にのみ、独立した HMAC 資格情報を使用します。Hostinger リレーは Codex を起動することも、ローカルリポジトリを読み取ることもありません。

ホスト型リレーは、既存のすべての codex_* ツールを保持し、さらに reeves_status、reeves_tap、reeves_swipe、reeves_type、reeves_back、reeves_home、reeves_recents、reeves_sequence、reeves_screenshot を公開します。ローカル STDIO Codex レジストリは Codex 専用のままです。エージェントの要求は認証されたキー ID によってフィルタリングされます。クライアントが指定したルーティングフィールドは無視されます。

reeves_screenshot は、Android ピクセルを標準の MCP image コンテンツブロック(image/png と base64 データ)として、幅、高さ、キャプチャタイムスタンプ、エージェント ID、バイト長メタデータとともに返します。Android エージェントはリレーがアドバタイズするチャンク化結果プロトコルを使用するため、使用できない Android ローカルパスは公開されず、各署名付き HTTP リクエストはリレーの本文制限内に収まります。

reeves_sequence は、1 から 50 までの順序付けられたデバイスアクションを 1 つのルーティングされたジョブで送信します。Android はタップ、スワイプ、タイプ、Back、Home、Recents、待機、スクリーンショットのアクションをローカルで実行し、デフォルトでは最初のエラーで停止し、デフォルトでは 1 つの最終 MCP イメージを返します。結果には、インデックス化されたアクションの結果と、追加のシークレットフリーなリレー/Android ステージタイミングが含まれます。既存の 25 秒のエージェントリクエストは、エンキュー時起動のロングポールであり、取得遅延ではありません。Android は、各成功した結果送信の直後に別の要求を開始し、1 つの OkHttp 接続プールを再利用します。

このリリースはまた、サポートされている MCP プロトコルバージョンをネゴシエートし、制限付きの OAuth サブジェクトにバインドされたセッションを発行し、後続のリクエストでそのセッションを要求します。再試行されたツール呼び出しは、OAuth サブジェクト、MCP セッション、型付き JSON-RPC ID、リクエストハッシュにバインドされます。セッションを終了すると、キャッシュされたまたは保留中の作業が無効になります。このリリースはまた、キャンセルされたリレー作業とクラッシュした app-server 状態をクリーンアップし、承認されたパスを再検証し、スレッドごとのイベントを分離し、すべての公開トランスポートで制限付きのネストされたエラーデータを編集します。

バージョン 1.2.5 はまた、codex_status.latestAgentMessage を承認済みの永続化トランスクリプトと調整します。完全に永続化された外部 Codex 完了(合成された rollout-* ターンを含む)は、ブリッジが観測した古いメッセージを置き換えますが、不完全または中断されたトランスクリプトの末尾は除外されたままになります。

Windows エージェントを更新する前に、更新されたリレーをデプロイしてください。新しいリレーはレガシーの一回限りの結果を引き続き受け入れますが、新しいエージェントは、リレーがサポートをアドバタイズした後にのみチャンク形式を使用します。

Hostinger hPanel の手順、mcp.biotele.mx の DNS、Auth0 のセットアップ、Microsoft Entra ID のセットアップ、ChatGPT Web コネクタのセットアップと復旧、環境変数、ローカルエージェントのインストール、脅威モデルについては、docs/REMOTE_DEPLOYMENT.md を参照してください。