🌊

Codex CLI 完全ガイド：MCP を活用したマルチエージェント連携

に公開
AI
AI コーディング
Vibe Coding
Codex
Codex CLI
tech

はじめに

Codex CLI は単独でも強力なローカルエージェントですが、Model Context Protocol（MCP）を活用すると他のエージェントやツールと連携したマルチエージェント環境を構築できます。本記事では、MCP の基本概念から Codex CLI での設定方法、実際のワークフローまでを詳しく解説します。

1. MCP とは何か

MCP（Model Context Protocol）は AI エージェントとツール・データソースを接続するためのプロトコルで、JSON-RPC を基盤にツール呼び出しやイベント通知を行います。Codex CLI では次の 2 つの形で MCP をサポートしています。

  1. MCP クライアント：Codex が外部 MCP サーバー（例：Serena、context7、GitHub MCP など）に接続し、ツール群を利用する。
  2. MCP サーバー：codex mcp-server で Codex 自身を MCP サーバーとして公開し、外部エージェント（例：OpenAI Agents SDK）に組み込む。

docs/advanced.md でも MCP の概要と codex mcp-server の利用例が紹介されています。

2. MCP クライアントとして外部ツールを利用する

2.1 設定ファイルに MCP サーバーを登録

~/.codex/config.toml の [mcp_servers] セクションにサーバー名をキーとして設定します。例えば Serena を登録するには：

[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]
startup_timeout_sec = 10

docs/config.md には mcp_servers ブロックの書式とパラメータが解説されています。startup_timeout_sec や tool_timeout_sec で個別のタイムアウトが調整可能です。

2.2 CLI から MCP サーバーを操作

codex mcp サブコマンド（codex-rs/cli/src/mcp_cmd.rs）で、登録済み MCP サーバーを管理できます。

  • codex mcp list — 登録済みサーバーを列挙。
  • codex mcp add <name> -- <command...> — 新規追加。
  • codex mcp get <name> --json — 設定内容を JSON で表示。
  • codex mcp remove <name> — 削除。

内部では Config::load_with_cli_overrides を通じて config.toml を読み込み、設定を更新します。

2.3 Codex から MCP ツールを呼び出す流れ

  1. セッション開始時、codex-rs/core/src/mcp_connection_manager.rs が McpConnectionManager::new を呼び出し、各 MCP サーバーを並列で初期化。Initialize → ListTools を発行して利用可能ツールを取得します。
  2. 会話中に MCP ツールが必要になった場合、Codex は CallTool リクエストを MCP サーバーに送信（McpClientAdapter::call_tool）。
  3. 結果が JSON-RPC として返り、Codex が最終回答に組み込みます。

2.4 マルチエージェント活用の例

  • 依存関係の解析：Serena のような外部エージェントを呼び出し、特定言語のコード解析を任せる。
  • ドキュメント検索：context7 など、ドキュメント検索に特化した MCP サーバーを組み合わせる。
  • GitHub 自動化：GitHub MCP を接続し、Issue 作成や PR レビューチェックを Codex から呼び出す。
  • 記事投稿：記事投稿用 MCP（ブログ CMS や Notion API を MCP 化したもの）を呼び出し、生成したコンテンツを自動で公開。
  • CI 連携：Codex が生成するパッチを外部 MCP エージェントで検証し、結果をフィードバック。

2.5 実践的な tips

  • 初回起動でリポジトリクローンやキャッシュ作成が必要な MCP サーバーの場合、sandbox_workspace_write.network_access=true と writable_roots の追加が必須です。詳細は別記事「codex exec での MCP 起動エラーと対処法」を参照。
  • タイムアウトは startup_timeout_sec や tool_timeout_sec で調整。Codex CLI の -c オプションで一時的に変更することもできます。

3. Codex を MCP サーバーとして公開する

3.1 目的とメリット

codex mcp-server を実行すると、Codex CLI が MCP サーバーとして動作し、他のエージェントプラットフォーム（例：OpenAI Agents SDK、独自 MCP クライアント）から Codex の機能を "ツール" として利用できます。これにより、複数のエージェントが役割分担しながら Codex を呼び出すマルチエージェント構成が実現します。

3.2 起動手順と基本構成

  1. 事前準備：Codex CLI がログイン済みであることを確認し、必要なら ~/.codex/config.toml にプロファイルを整備。
  2. MCP サーバー起動：ターミナルで以下を実行。
    codex mcp-server
    デフォルトでは stdio で JSON-RPC をやり取りする形で起動します。起動に成功すると、Codex が提供するツール一覧がログに出力されます。
  3. クライアントから接続：MCP 準拠のクライアント（例：MCP Inspector、Agents SDK）から tools/list を送信し、利用可能なツールを確認します。

3.3 提供されるツール

バージョンによって異なりますが、codex-rs/mcp-server/src/message_processor.rs を確認すると主に以下のようなツールが公開されています。

  • config：Codex の一時的な設定変更を行う。
  • run_task（仮称）：Codex にタスクを渡して処理結果を受け取る。
  • apply_patch、status など、Codex の内部ツールチェーンを外部から呼び出すもの。

ツール名は tools/list の結果で確認し、必要に応じて MCP クライアント側で適切にラップしてください。

3.4 実際の利用例

例1：MCP Inspector で動作を確認

  1. Codex MCP サーバーを起動：codex mcp-server
  2. 別ターミナルで MCP Inspector を起動：
    npx @modelcontextprotocol/inspector codex mcp-server
  3. Inspector 上で tools/list → tools/call を実行し、Codex ツールを直接呼び出す。例えば run_task に { "prompt": "README を要約して" } を送り、Codex の応答を確認。

例2：OpenAI Agents SDK との連携

  1. Agents SDK のツール設定で Codex MCP サーバーを登録。
  2. "要件整理エージェント" → "Codex ツール" → "検証エージェント" のようなワークフローを構築し、複数エージェントが協調して開発タスクを自動化。
  3. Codex は通常の CLI と同様にファイル編集・テスト実行・差分生成を行い、結果を Agents SDK に返します。

例3：GitHub MCP と組み合わせた自動レビュー

  1. GitHub MCP サーバー（例：@openai/github-mcp）を別プロセスで起動し、config.toml に登録。
  2. Codex MCP サーバーを起動し、Agents SDK などのクライアントから次のようなマルチエージェントシナリオを構築：
    • エージェントA：Codex MCP ツールを呼び出してローカルでコード変更とテストを実施。
    • エージェントB：GitHub MCP ツールを呼び出して PR を作成し、レビューコメントを投稿。
    • エージェントC：Codex が生成したテスト結果や差分を確認し、GitHub Issue にサマリを記録。
  3. Codex と GitHub MCP の組み合わせにより、コード変更からレビュー、GitHub 反映までを自動化できます。

例4：記事自動投稿 MCP との連携

  1. WordPress / Ghost / Notion など向けに MCP サーバーを用意（例：CMS API を MCP ツールとして公開したもの）。
  2. Codex MCP サーバーを起動。Agents SDK または自作クライアントで以下のフローを構築：
    • エージェントA（Codex）：新機能の解説記事を生成し、run_task で HTML or Markdown を出力。
    • エージェントB（記事投稿 MCP）：生成した記事を tools/call 経由で CMS に投稿し、公開ステータスや URL を返す。
    • エージェントC（チェック用）：公開結果を確認し、SNS 投稿や添付画像生成を追加で実行。
  3. Codex が文章を生成し、記事投稿 MCP が配信まで行うことで、製品リリースの記事化を自動化できます。

3.5 運用上の注意

  • サンドボックス制限：MCP サーバーを動かす際も config.toml のサンドボックスが適用されます。必要な権限（ネットワーク、書き込み先）を事前に許可してください。
  • セキュリティ：公開ネットワークで稼働させる場合は、SSH トンネル、VPN、認証トークン等でアクセス制御を行う。
  • リソース管理：複数クライアントから同時に呼び出される場合は、並列数やジョブキューを調整し、Codex や外部 MCP サーバーの負荷を適切に管理する。

4. 実際のマルチエージェント運用例

4.1 Codex + Serena（コード解析）

  1. codex mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context codex
  2. codex exec -c 'sandbox_workspace_write={network_access=true}' -- cd /path/to/repo "この Rust プロジェクトの構造を教えて"
  3. Codex が Serena のツールを呼び出し、解析結果を組み込んだ回答を返す。

4.2 Codex + 自作 MCP サーバー（社内 API）

  1. 社内データベースにアクセスする MCP サーバーを用意し、config.toml に登録。
  2. Codex から社内 API ツールを呼び出し、レポート生成や監視情報の取得を自動化。

4.3 Codex + GitHub MCP（開発フロー自動化）

  1. GitHub MCP サーバーを起動し、codex mcp add github -- <github-mcp-command> で登録。
  2. Codex はローカル修正とテストを担当し、GitHub MCP が Issue/PR 操作を担当。
  3. Agents SDK などを介して "修正 → テスト → PR 作成 → レビュー依頼" までを一貫して自動化。

4.4 Codex MCP サーバー + 記事投稿 MCP（コンテンツ配信）

  1. Codex MCP サーバーを起動し、記事投稿 MCP（WordPress/Notion/Ghost など）をクライアント側に登録。
  2. エージェントが Codex に文章作成を依頼し、結果を記事投稿 MCP に渡して公開。
  3. 公開後、Codex がサマリ生成・SNS 投稿支援などの追加タスクを実施。

5. ベストプラクティス

  • ネットワークとサンドボックス設定：MCP サーバーが必要とする書き込み先・ネットワークアクセスを config.toml や -c で事前に許可する。
  • ログモニタリング：RUST_LOG=info や ~/.codex/log/ のログを監視し、初期化失敗の原因を特定。
  • タイムアウト管理：応答の遅い MCP サーバーには startup_timeout_sec や tool_timeout_sec を十分に確保。
  • セキュリティ：外部からの呼び出しに備え、認証・アクセス制御・秘密情報のマスキングを徹底。

6. まとめ

  • Codex CLI は MCP を通じて多様なツール・エージェントと連携できる。
  • [mcp_servers] の設定と codex mcp サブコマンドで外部 MCP サーバーの接続管理が可能。
  • codex mcp-server で Codex 自体を MCP サーバーとして公開し、マルチエージェント環境に組み込める。
  • GitHub MCP や記事投稿 MCP などを組み合わせることで、開発からドキュメント配信までの一連のワークフロー自動化が可能。

今後のシリーズ記事では、具体的な MCP サーバーの追加・削除のハンズオンや、Agents SDK と Codex を組み合わせたマルチエージェントワークフロー構築例も紹介予定です。

Discussion