Codex Persistent MCP

🚀 codex-persistent-mcp

English | Chinese (Simplified) | Chinese (Traditional)

このサーバーは、セッションの永続化をローカルの codex-cli に委任する軽量なMCP（stdio）サーバーです。これにより、MCP呼び出しでも実際のセッションが作成され、ユーザーは後で codex resume <session_id> を使用してセッションを再開できます。

🚀 クイックスタート (推奨: npx自動更新)

Claude Code

claude mcp add-json --scope user codex-persistent \
  '{"command":"npx","args":["-y","codex-persistent-mcp"],"env":{"CODEX_BIN":"/absolute/path/to/codex"}}'

確認:

claude mcp list
claude mcp get codex-persistent

Codex CLI

codex mcp add codex-persistent --env CODEX_BIN=/absolute/path/to/codex -- npx -y codex-persistent-mcp

確認:

codex mcp list --json
codex mcp get codex-persistent --json

Antigravity

Antigravityは、--add-mcp を介してMCPサーバーを追加することができます。

antigravity --add-mcp '{"name":"codex-persistent","command":"npx","args":["-y","codex-persistent-mcp"],"env":{"CODEX_BIN":"/absolute/path/to/codex"}}'

✨ 解決する問題

• 他のエージェントがMCPを介してCodexを呼び出しても、実際の永続化されたセッションを取得できます。
• サーバーの再起動でもコンテキストが失われません（コンテキストはCodex CLIのセッションストアに保存されます）。
• ユーザーはいつでも codex resume <session_id> を使用して同じ会話を続けることができます。
• MCPを介して作成されたセッションは、同じプロジェクト（CWD）の codex resume に表示されます。

📦 インストールガイド

要件

• Node.js (推奨: 18+)
• codex-cli (開発は codex-cli 0.77.0 を基準に行われています)

インストールとビルド

npm install
npm run build

グローバルインストール (オプション)

npmに公開した後、グローバルなCLIとしてインストールできます。

npm install -g codex-persistent-mcp

実行

npm start

💻 使用例

基本的な使用法

このサーバーは3つの主要なツールを公開しています（すべて session_id を返します）。

• codex_chat
  • 入力: session_id? (UUID), prompt, cwd?, model?, reasoning_effort?, timeout_ms?
  • 出力: session_id, reply, usage?
• codex_plan
  • 入力: session_id?, requirements, plan, constraints?, cwd?, model?, reasoning_effort?, timeout_ms?
  • 出力: session_id, critique, usage?
• codex_review
  • 入力: session_id?, change_summary, test_results?, open_questions?, cwd?, model?, reasoning_effort?, timeout_ms?
  • 出力: session_id, review, usage?

下位互換性のあるツール名 codex_guard_plan と codex_guard_final も利用可能です。

🔧 技術詳細

動作原理 (codex resume が機能する理由)

各ツールの呼び出しは codex サブプロセスを生成します。

• 新しいセッション:
  • codex exec --skip-git-repo-check --json -C <cwd> "<prompt>"
• セッションの再開:
  • codex exec --skip-git-repo-check --json -C <cwd> resume <session_id> "<prompt>"

サーバーは --json によって生成されたJSONLイベントストリームを解析します。

• thread.started.thread_id をMCPの session_id として読み取ります。
• item.completed イベントのうち agent_message タイプのものを収集し、最終メッセージを reply として返します。

同じ session_id のリクエストは、書き込みの順序が乱れないようにシリアライズされます。

環境変数

• CODEX_BIN: codex 実行可能ファイルのパス (デフォルト: codex)
• CODEX_PERSISTENT_MCP_ORIGIN: すべてのプロンプトに注入される識別子 (デフォルト: codex-persistent-mcp)

作業ディレクトリ (cwd)

CodexはワークスペースのCWDを含むセッションメタデータを保存し、codex resume はデフォルトでCWDでセッションをフィルタリングします。

• 新しいセッションを開始するとき（session_id がない場合）、cwd（リポジトリのルート）を渡す必要があります。
• セッションを再開するとき（session_id がある場合）、cwd はオプションです。サーバーはCodexのローカルセッションストアから再利用または推測します。

“AI vs human” の属性付け

Codex CLIは、入力がMCPを介して別のAIから来たことを自動的に認識できません。

このサーバーは、すべてのリクエストに小さなヘッダーを注入することで、Codexが確実に区別できるようにします。

• <<<MCP_CONTEXT_BEGIN>>> が含まれるメッセージ → MCPを介したAIエージェントからのもの（エージェントに返信）
• 含まれないメッセージ → 人間のユーザーからのもの（例: codex resume）

リクエストごとのモデルと推論のオーバーライド

デフォルトでは、Codex CLIは ~/.codex/config.toml（例: model と model_reasoning_effort）を読み取ります。

このMCPサーバーは、リクエストごとのオーバーライドをサポートしています。

• model: そのリクエストのみ codex exec -m <model> に渡されます。
• reasoning_effort: そのリクエストのみ codex exec -c model_reasoning_effort="..." として渡されます。

これらのフィールドを渡さない場合、リクエストはCodex CLIのデフォルトに従います。

バージョン固定と自動更新

npx -y codex-persistent-mcp は一般的に最新バージョンを取得します。これは便利ですが、再現性が低くなります。

バージョンを固定するには:

npx -y codex-persistent-mcp@0.1.3

推奨ワークフロー (2エージェントガードレール)

• 計画前: “要件 + ドラフト計画” を codex_plan に送信して、ギャップ/リスク/質問/テストを取得します。
• 完了前: “変更概要 + テスト結果 + 未解決の質問” を codex_review に送信して最終レビューを受けます。
• いつでも: codex resume <session_id> を使用して同じセッションを手動で続けることができます。

トラブルシューティング

codex が見つからない

PATHが継承されていない場合（例: nvm）によく発生します。以下のように設定することで解決します。

• CODEX_BIN=/absolute/path/to/codex (which codex を使用して見つける)

なぜ cwd を渡す必要があるのか

Codexが正しいワークスペースコンテキストを記録し、codex resume がそのリポジトリでセッションをデフォルトで表示するように、プロジェクトのルートを渡します。

npm publishに2FAが必要 (メンテナー向け)

一部のnpmアカウントでは、公開時に2要素認証（2FA）または2FAをバイパスできる自動化/細粒度トークンを使用する必要があります。

• 書き込み用に2FAを有効にする:
  • npm profile enable-2fa auth-and-writes
• 次に、ワンタイムパスワード（OTP）で公開する:
  • npm publish --otp=123456