Claude Code Codex MCP 連携を試してみたいけれど、どこから手をつければいいかわからない。そんな悩みはありませんか？Claude Codeを使っていて「Codexも契約しているのに、どう組み合わせれば一番強いのかわからない」という疑問を持つ方は多いはずです。実は、Codex CLIは codex mcp-server コマンドひとつでClaude配下に組み込めます。しかし、日本語情報が少なく、設定場所やモデル制約で詰まりやすいのが実態です。この記事を読めば、すぐ動く構成を手に入れられます。
筆者自身、Claudeの使用上限によく引っかかっていました。Codex側もPlusプランに加入していたため、「この2つをうまく組み合わせれば、Claudeの使用量を削減できるのでは」と考えたのが導入のきっかけです。設定作業ではいくつかハマりどころがありました。しかし、ひとつひとつ解決していくうちに、ClaudeとCodexの強みを活かした使い方の手応えをつかめました。関連記事として、Claude Codeの基本コマンド一覧もあわせてご覧ください。
Claude CodeからCodexをMCP経由でサブエージェント化すると何ができるか
Claude Code Codex MCP連携の最大の魅力は、2つのAIを「司令塔」と「実行役」に分けられる点です。単なる連携紹介ではなく、それぞれの強みを活かした役割分担を設計できます。まず、この構成で何が実現できるのかを整理します。
この記事で実現する構成の全体像
実現する構成はシンプルです。Claude CodeがMCP経由でCodex CLIを呼び出します。さらに、Claude側のカスタムエージェント定義で役割を固定します。つまり、Claudeが指示を出し、Codexが実行を担うという流れです。
具体的には、以下の2つのファイルを設定します。
.mcp.json：Codex CLIをMCPサーバーとして登録する設定ファイル.claude/agents/codex-worker.md：Claudeがいつ・どのようにCodexを使うかを定義するエージェントファイル
この2ファイルを用意するだけで、ClaudeからCodexへのタスク委譲が可能になります。出典: Claude Code Docs
なぜClaude単体ではなくClaude×Codexに分けるのか
Claude単体で全作業を行うと、コンテキストが肥大化しやすくなります。また、使用量上限に到達するリスクも高まります。そのため、役割を明確に分けることが重要です。
Claudeは文章整理・設計・レビューに優れています。一方、Codexはコード実行・構造分析・ファイル操作に向いています。この特性を活かして分担することで、コンテキスト効率と作業品質の両方が向上します。
この構成が向いている人
- Claude CodeとCodex CLIの両方を契約しており、使用量を効率化したいエンジニア
- コードの調査・実装・レビューを自動化したい開発者
- マルチAIエージェント構成を実際に組んでみたい方
前提知識として押さえたいMCPとClaude Codeの仕組み
設定の意味を理解するために、まず基礎的な概念を整理します。「なぜその設定を書くのか」がわかると、トラブルシュートもしやすくなります。具体的には、MCPの仕組みとClaudeのサブエージェント設計の2点を押さえておくと、後の設定作業がスムーズになります。
MCPはClaude Codeから外部ツールを呼び出すための仕組み
MCP（Model Context Protocol）は、AIから外部ツールを呼び出すための標準化された接続方式です。プラグインではなく、あくまでプロトコル（通信の規約）です。そのため、異なるツール間で同じ方法で接続できます。
Claude Codeは、このMCPを通じて外部のサーバーやツールと連携できます。設定すれば、GitHub・Notion・データベースなど多様なサービスをClaude Codeから操作できます。出典: Claude Code Docs
Codex CLIは codex mcp-server でMCPサーバーとして起動できる
この記事の核心となる情報です。多くの読者がまだ知らないポイントとして強調します。Codex CLIには codex mcp-server というサブコマンドがあります。このコマンドを実行すると、CodexがstdioベースのMCPサーバーとして起動します。
stdioとは標準入出力のことです。つまり、テキストベースのJSON-RPCメッセージを通じて、Claude CodeとCodexがやり取りできるようになります。筆者もこの機能の存在を知らなかったため、最初は別の方法を探していました。しかし、実際に試してみるとシンプルに動作しました。
Claude Codeのサブエージェントは .claude/agents/ で定義する
MCPサーバーの設定とサブエージェントの定義は、別物です。この点を混同すると後半で混乱します。整理すると以下のとおりです。
.mcp.json：どのMCPサーバーをClaude Codeに接続するかを定義する.claude/agents/：Claudeがどのエージェントにどんなタスクを委譲するかを定義する
サブエージェントはYAMLフロントマター付きのMarkdownファイルで定義します。各エージェントは独立したコンテキストで動作し、結果をメイン会話に返します。出典: Claude Code Docs
Claude Code Codex MCP連携の全体手順
ここからは実際の設定手順を解説します。全体の流れをつかんでから、各ステップに進みましょう。手順は3段階です。
手順1 .mcp.json でCodex用MCPサーバーを定義する
まず、プロジェクトルートに .mcp.json ファイルを作成します。このファイルはプロジェクトスコープのMCP設定ファイルです。チームメンバー全員が同じ設定を共有できるため、バージョン管理にコミットするのが推奨されています。
なお、settings.json にMCPサーバーを定義してもClaude Codeには反映されません。これは多くの人がハマるポイントです。必ず .mcp.json を使ってください。
次に、動作確認として以下のコマンドでCodexがMCPサーバーとして起動できるか確認します。
# CodexのMCPサーバーとしての起動確認
codex mcp-serverログに「Starting MCP server…」のようなメッセージが表示されれば成功です。出典: Scott Spence Blog
手順2 .claude/agents/ にCodex活用用エージェントを作る
MCPサーバーとしてCodexを登録しただけでは、Claudeはいつ・どのようにCodexを使うべきかわかりません。そのため、エージェント定義ファイルを作成します。
プロジェクトの .claude/agents/ ディレクトリに、用途別のMarkdownファイルを置きます。たとえば「コード調査用」「実装用」のように分けると管理しやすくなります。
手順3 ClaudeからCodex担当エージェントを呼び出して動作確認する
設定が完了したら、Claude Codeのセッションを再起動します。そのうえで、以下のような指示でエージェントを呼び出してみましょう。
codex-workerエージェントを使って、このリポジトリのsrcディレクトリ構造を調査してくださいClaudeがCodexに処理を委譲し、結果を返してきたら成功です。
実際の設定ファイル例（コードサンプル中心）
ここでは実際に動作する設定ファイルをそのまま掲載します。コピーして使えるよう、最小構成を意識しています。
.mcp.json の記述例
プロジェクトルートに .mcp.json を作成し、以下のように記述します。
{
"mcpServers": {
"codex": {
"command": "codex",
"args": ["mcp-server"]
}
}
}重要なポイントは3つです。
"mcpServers"キーの下にサーバー定義を書く"command"にCodex CLIの実行コマンド（codex）を指定する"args"に["mcp-server"]を指定してMCPサーバーモードで起動させる
これだけで、Claude CodeからCodexがMCPサーバーとして使えるようになります。出典: GitHub / tuannvm
.claude/agents/codex-worker.md の記述例
続いて、エージェント定義ファイルを作成します。YAMLフロントマター付きのMarkdownで記述します。
---
name: codex-worker
description: "コード調査・実装・構造分析をCodexに委譲するエージェント。ファイル横断的な調査やコード実行が必要なタスクに積極的に使う。"
tools:
- Read
- Write
- Bash
model: sonnet
permissionMode: acceptEdits
---
# Codex実行エージェント
あなたはCodex CLIをオーケストレートして、コード調査・実装・構造分析を担当するエージェントです。
## 役割
- ファイル横断的なコード調査
- コードの実装・修正
- リポジトリ構造の分析
- 体系的なドキュメント生成
## 呼び出し方法
BashツールでCodex CLIを呼び出します。
```bash
codex exec --model gpt-5.4 "【依頼内容】"
```
## 出力形式
調査結果は必ず以下の形式で返してください。
1. 結論（1〜2文）
2. 根拠（箇条書き）
3. 次のアクション候補（任意）フロントマターの各フィールドの意味は以下のとおりです。
name：エージェントの識別子。呼び出し時に使用する名前description：Claudeがいつこのエージェントを使うかを判断するための説明文tools：エージェントが使えるツールの一覧model：エージェントが使うモデル（sonnet/opus/haiku）permissionMode：権限の扱い方（acceptEditsでファイル編集を自動許可）
呼び出しプロンプトの最小例
設定後、Claude Codeのチャットで以下のように指示します。
# 基本的な呼び出し
codex-workerエージェントを使って、srcディレクトリの構造を調査してください
# 実装タスクを委譲する例
codex-workerエージェントを使って、user.tsの型定義を確認し、
対応するバリデーション関数を実装してください
# 分析タスクを委譲する例
codex-workerエージェントを使って、このリポジトリで未使用の
importが含まれるファイルをリストアップしてくださいハマりやすいポイントと対処法（導入時の注意事項）
この記事の最大の差別化ポイントです。設定作業では、実際に複数のハマりどころがありました。同じ経験をする読者のために、先回りして解説します。出典: GitHub / leonardsellem
mcpServers は settings.json ではなく .mcp.json に書く
最も多いハマりポイントです。Claude Codeには .claude/settings.json という設定ファイルがあります。しかし、MCPサーバーの設定は settings.json ではなく .mcp.json に書く必要があります。
settings.json にMCPの設定を書いても、Claude Codeはそれを読み込みません。必ず以下のように分けて管理してください。
- MCPサーバーの設定 →
.mcp.json（プロジェクトルート） - Claude Codeの動作設定 →
.claude/settings.json
Codex連携で使えるモデルに制約がある（ChatGPT PlusはGPT-5.4のみ）
筆者がハマったポイントです。Codexコマンドで --model gpt-4.1-mini を指定したところ、エラーになりました。ChatGPT Plusのアカウントでは、利用可能なモデルに制約があります。
具体的には、ChatGPT PlusアカウントではOAuth認証経由で使えるモデルが限られています。筆者の環境では gpt-5.4 は動作しました。一方、gpt-4.1-mini は使えませんでした。モデルエラーが出た場合は、まず gpt-5.4 を試してみてください。
# 動作確認済みの指定方法
codex exec --model gpt-5.4 "このリポジトリのREADMEを要約してください"Notion MCPの認証エラーがCodex起動時に邪魔する
複数のMCPサーバーを設定している場合に起こりやすい問題です。Codexの mcp-server コマンドを使う場合、Codex自体の ~/.codex/config.toml に設定したMCPサーバーの認証状態が影響することがあります。
たとえば、Codexの設定にNotionのMCPサーバーを追加していて認証が切れていた場合、Codex起動時にエラーが出ることがあります。以下のコマンドでNotionへの認証を更新してください。
# Codex経由でNotionのMCP認証を更新する
codex mcp login notionまた、エラーの原因を切り分けるために、まずはCodexのMCP設定を最小限にして試すことをおすすめします。
Codexが起動できても役割定義が曖昧だと効果が薄い
接続成功で満足してしまうと、実際の効果が薄くなります。たとえば、エージェント定義の description フィールドが曖昧だと、Claudeはいつ・なぜCodexを使うべきかを判断できません。その結果、Claude自身が処理してしまいます。
効果的な description の書き方は以下のとおりです。「〜のときに使う」という具体的な条件を明記してください。
# 曖昧な例（NGパターン）
description: "Codexを使うエージェント"
# 具体的な例（OKパターン）
description: "ファイル横断的なコード調査・実装・構造分析をCodexに委譲するエージェント。
大規模リポジトリの調査や、コード実行が必要なタスクに積極的に使う。"
おすすめの役割分担はClaudeが司令塔、Codexが実行役
設定が完了したら、次は役割設計です。どのタスクをどちらに任せるかを明確にすると、コストも品質も最適化できます。なお、筆者が試行錯誤した結果、以下の分担が最も効果的でした。
Claudeに向いている仕事（文章・設計・レビュー・ストーリーテリング）
Claudeが得意とするのは「上流の知的整理」です。具体的には以下のタスクです。
- 要件整理・設計書の作成
- 日本語の文章化・ブログ記事の執筆
- コードレビューのフィードバック文章化
- 複数案の比較・トレードオフの整理
- 読者への共感・ストーリーテリング
特に日本語の文章品質では、Claudeに強みがあります。また、読者の気持ちを汲み取った説明も得意です。
Codexに向いている仕事（コード実行・体系的分析・構造設計・ファイル操作）
Codexが得意とするのは「実務寄りの実行タスク」です。具体的には以下のタスクです。
- 大規模リポジトリのファイル横断調査
- コードの実装・リファクタリング
- 構造化された出力（JSON・Markdown形式）の生成
- ファイルの作成・編集・削除
- テストの実行と結果の分析
特に体系的な分析が必要なタスクでは、Codexの強みが発揮されます。また、実際にコードを動かして検証する場面にも向いています。
役割を混ぜると何が起きるか
一方、役割を明確にせず、同じタスクを両方に任せると問題が起きます。具体的には以下のデメリットがあります。
- どちらか一方の強みが活かせず、出力品質が下がる
- コスト（トークン使用量）が二重にかかる
- コンテキストが肥大化してClaudeの上限に達しやすくなる
つまり、役割分担を曖昧にするほど、マルチAI構成のメリットが薄れます。最初に「Claudeがやること・Codexがやること」を決めておくと効果的です。
実務で使えるユースケース3選
設定が完了した後の使い道を示します。以下の3つのユースケースは、実際に試して効果を確認できたものです。
大規模リポジトリの構造調査をCodexに任せる
数百ファイルが存在するリポジトリを一から把握するのは大変です。そこで、Codexに構造調査を任せます。
# Codexへの依頼プロンプト例
codex-workerエージェントを使って、このリポジトリの以下を調査してください。
1. 主要なディレクトリの役割
2. エントリーポイントとなるファイル
3. 外部依存ライブラリの一覧
結果は箇条書きでまとめてください。Claudeは調査方針の指示と結果のレビューを担当します。一方、Codexは実際のファイル読み込みと分析を担当します。この分業により、Claudeのコンテキストを節約できます。
実装前の技術選定をClaude、検証コード作成をCodexに分ける
新機能を実装する際、技術選定の議論にはClaudeを使います。複数の選択肢のトレードオフを整理し、最終判断を下すのがClaudeの役目です。そして決定した技術での検証コード作成はCodexに任せます。
この分業により、設計と試作を切り分けたワークフローが実現します。また、試作コードの実行結果もCodexが確認するため、Claudeは検証結果のレビューだけに集中できます。
ブログやドキュメント生成の裏でCodexに根拠収集をさせる
とつブログの記事執筆でも活用できます。たとえば、技術記事を書く際にClaudeが本文を執筆します。その裏でCodexにコードサンプルの動作確認や、関連ファイルの情報収集をさせます。
この構成により、記事の正確性が向上します。また、執筆と検証を並行して進められるため、作業効率も上がります。生成AI関連の記事を書く際にも、このワークフローが活用できます。
Claude CodeとCodexを連携するときの運用のコツ
設定だけで終わらず、継続して使いこなすためのコツを紹介します。小さな工夫で、長期的な運用効率が大きく変わります。
エージェントごとに役割を狭く保つ
万能エージェントを1つ作るより、「調査用・実装用・レビュー用」のように分けた方が安定します。理由は2つあります。まず、descriptionが具体的になり、Claudeが適切に委譲できます。さらに、エージェントの動作が予測しやすくなりデバッグしやすくなります。
たとえば、以下のように分けることを検討してください。
codex-explorer.md：ファイル調査専用（読み取り専用ツールのみ）codex-implementer.md：コード実装専用（書き込みも許可）codex-reviewer.md：コードレビュー専用（読み取り専用）
出力形式を固定するとレビューしやすい
エージェント定義のシステムプロンプトに出力形式を明記します。たとえば「結論→根拠→変更候補」のように構造を固定します。そうすることで、Codexからの返答を素早くレビューできます。
出力形式が毎回バラバラだと、読み取りに時間がかかります。また、Claudeが次のアクションを決めるのも難しくなります。フォーマットを固定するだけで、作業全体のスムーズさが向上します。
コストと使用量を抑える考え方
「重い調査はCodex、最終判断はClaude」という原則を持つと、無駄打ちを減らせます。具体的には以下のように考えます。
- 大量のファイルを読む作業 → Codexに任せる（Claudeのコンテキストを消費しない）
- 最終的な文章や判断 → Claudeが担当する
- 繰り返し実行するタスク → Codexのシェルスクリプト化を検討する
また、Codexのモデルは必要最小限のものを選びます。すべてのタスクで高性能モデルを使う必要はありません。IT技術関連の知識としても、コスト設計は重要な視点です。
よくある疑問（FAQ）
Claude CodeのMCP設定はsettings.jsonではだめですか？
だめです。Claude Codeは settings.json のMCPサーバー設定を読み込みません。必ず .mcp.json（プロジェクトルート）に記述してください。あるいはコマンドで追加する場合は claude mcp add --scope project を使います。こうすることで .mcp.json に自動保存されます。
Codex CLIは本当にMCPサーバーとして使えますか？
使えます。codex mcp-server コマンドで起動すると、CodexはstdioベースのMCPサーバーとして動作します。起動すると利用可能なツール一覧がログに出力されます。Claude Codeはこのサーバーに接続してツールを呼び出せます。ただし、GeminiはまだMCPサーバー化できないため、この方法はCodex専用の機能です。
Claude Codeのサブエージェント定義はどこに置きますか？
プロジェクトごとのエージェントは .claude/agents/ に置きます。すべてのプロジェクトで使いたい場合は ~/.claude/agents/ に置きます。どちらもYAMLフロントマター付きのMarkdownファイルです。
Codex連携で使えないモデルがあるのはなぜですか？
Codex CLIはOAuth認証を通じてOpenAIに接続します。ChatGPT Plusアカウントの場合、OAuth経由で利用可能なモデルがAPIとは異なります。そのため、gpt-4.1-mini など一部モデルが使えない場合があります。現時点では gpt-5.4 の使用をおすすめします。
Notion MCPエラーが出るときは何を確認すべきですか？
以下の手順で確認してください。まず、Codex CLIの設定ファイル（~/.codex/config.toml）を開き、どのMCPサーバーが設定されているか確認します。次に、codex mcp list で各サーバーの認証状態を確認します。Notionが認証切れの場合は codex mcp login notion で再認証します。それでも解決しない場合は、Codexの設定からNotionを一時的に削除して動作確認してください。
あわせて読みたいおすすめ書籍
マルチAIエージェント構成やLLMエージェント開発をさらに深めたい方には、以下の書籍がおすすめです。
まとめ
この記事では、Claude Code Codex MCP連携の設定手順と運用のコツを解説しました。要点を整理します。
- Codex CLIは
codex mcp-serverコマンドでMCPサーバーとして起動できる。これを知っているかどうかで設定の難易度が大きく変わる - MCPサーバーの設定は
settings.jsonではなく.mcp.jsonに書く。ここを間違えると接続できない - サブエージェントは
.claude/agents/のMarkdownファイルで定義する。MCPサーバー設定と別物である点に注意する - Claudeには文章・設計・レビューを任せ、Codexにはコード実行・構造分析・ファイル操作を任せると役割分担が最適化される
- ChatGPT PlusアカウントではOAuth経由で使えるモデルに制約がある。現時点では
gpt-5.4の使用を推奨する - Notion MCPエラーが出た場合は
codex mcp login notionで再認証する
ClaudeとCodexそれぞれの強みを活かした役割分担を設計することで、使用量とコストの最適化が実現できます。ぜひ自分のプロジェクトで試してみてください。
引用・出典
- カスタムサブエージェントの作成 – Claude Code 公式ドキュメント（Claude Code Docs、2026年3月14日閲覧）
- MCP サーバーの設定 – Claude Code 公式ドキュメント（Claude Code Docs、2026年3月14日閲覧）
- codex-mcp-server – OpenAI Codex CLI 用 MCP サーバーラッパー（GitHub / tuannvm、2026年3月14日閲覧）
- codex-subagents-mcp – Codex CLI 向けサブエージェント MCP サーバー（GitHub / leonardsellem、2026年3月14日閲覧）
- Configuring MCP Tools in Claude Code（Scott Spence Blog、2026年3月14日閲覧）
コメント