Codex MCPの設定方法と使い方｜config.toml・おすすめサーバー・トラブル対策まで

記事入稿も、公開予約も、AIで。
人とAIの理想的な協業体制を実現するヘッドレスCMS「NILTO」

コンテンツ運用の「時間不足」「アイデア枯渇」「人手不足」をAIが解決。

フェンリルの国産ヘッドレスCMS『NILTO』新機能「NILTO MCP」はAIエージェントと協業して情報収集から入稿・承認・公開予約まで自動化し、リードタイムとコストを削減。

現在全プランでテクニカルプレビュー提供中。
今ならあなたのフィードバックがNILTOに反映されるチャンスです。

NILTO MCPを詳しく見る

Codex MCPとは？基本概念をわかりやすく解説

MCPの概要

MCP（Model Context Protocol）は、AIモデルと外部ツール・データソースを接続するためのオープンプロトコルです。JSON-RPCをベースにツール呼び出しやイベント通知を行う仕組みで、Anthropicが提唱し、現在はOpenAI・Google・Microsoftなど複数の企業・ツールが対応を進めています。

よく「AIにとってのUSB-C」と表現されますが、まさにその通りで、MCPという共通規格に対応したサーバー（ツール）をつなぐだけで、AIエージェントの能力を拡張できます。

Codex CLIでMCPサーバー使用するとなにが変わる？

Codex CLIは、OpenAIが提供するターミナルベースのコーディングエージェントです。単体でもコード生成・編集・レビューなど強力な機能を持ちますが、MCPに対応したことで以下のような拡張が可能になりました。

ライブラリの最新ドキュメント参照（Context7など）
Webブラウザの操作（Playwright MCP）
GitHub / GitLab Issue・PR操作の自動化
データベースへのクエリ実行
コード静的解析（Serenaなど）
プロジェクト管理ツール連携（Asanaなど）

Codex MCPの2つの動作モード

Codex CLIにおけるMCPには、2つの方向性があります。

① MCPクライアントとしてのCodex（Codexが外部ツールを使う）

Codex CLIが外部のMCPサーバーに接続し、そのツール群を利用するモードです。たとえばContext7を接続すれば、ライブラリの最新ドキュメントを参照しながらコーディングできます。多くの方がイメージする「Codex + MCP」はこちらの使い方です。

② MCPサーバーとしてのCodex（他のツールがCodexを使う）

codex mcp-server コマンドでCodex自体をMCPサーバーとして公開するモードです。Claude CodeやOpenAI Agents SDKなど、別のMCPクライアントからCodexの能力を呼び出せます。マルチエージェント構成を組む際に活用します。

対応トランスポート

Codexは以下の2種類のMCPトランスポートをサポートしています。

STDIOサーバー: ローカルプロセスとして起動し、標準入出力でやり取りするタイプ（例: Context7、Playwright）
Streamable HTTPサーバー: URLでアクセスするリモートサーバータイプ（例: GitLab、OpenAI Docs MCP）

Codex CLIのインストールと初期設定

MCPの設定に入る前に、Codex CLIのセットアップが必要です。

前提条件

Node.js 18以上（推奨: LTS最新版）
ChatGPT Plus / Pro / Business / Edu / Enterpriseのいずれかのプラン（Free/Goは期間限定で試用可）

インストール

# npmでグローバルインストール
npm install -g @openai/codex

# またはHomebrewでインストール（macOS）
brew install --cask codex

# アップデート（npm版）
npm install -g @openai/codex@latest

# アップデート（Homebrew版）
brew update && brew upgrade --cask codex

認証

codex

初回起動時に「Sign in with ChatGPT」を選択し、ブラウザでログインします。ChatGPTサブスクリプションの範囲内で利用する場合、別途API料金は発生しません。

注意: OPENAI_API_KEY を設定してAPI経由で利用する場合は、ChatGPTサブスクリプションとは別にAPI従量課金が発生します。

料金とレート制限の目安

Codex CLIはChatGPTのプランに含まれますが、利用量には上限があります。上限はプランやタスクの規模・モデルによって変動し、数値も更新される可能性があります。

最新の目安はOpenAIの料金ページ（Codex / ChatGPT plans）を参照してください。制限に近づいた場合は、/status コマンドで使用量とリセット時刻を確認できます。

MCPサーバーの設定方法

MCPサーバーを設定する方法は3つあります。

方法① CLIコマンドで追加（最も簡単）

codex mcp add コマンドを使えば、config.tomlを手動で編集する必要がありません。

# STDIOサーバーの追加
codex mcp add <サーバー名> -- <起動コマンド>

# 例: Context7を追加
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 環境変数を設定する場合
codex mcp add github --env GITHUB_TOKEN=your-token -- npx -y @modelcontextprotocol/server-github

追加後の確認や管理には以下のコマンドを使います。

# MCPサーバーの一覧表示
codex mcp list

# JSON形式で一覧表示
codex mcp list --json

# 特定サーバーの設定確認
codex mcp get context7

# JSON形式で確認
codex mcp get context7 --json

# サーバーの削除
codex mcp remove context7

# ヘルプ表示
codex mcp --help

Codexのターミナル上では /mcp コマンドでも接続状態を確認できます。

方法② config.tomlを直接編集

より細かい制御が必要な場合は、設定ファイルを直接編集します。

設定ファイルの場所:

OS	パス
macOS / Linux	`~/.codex/config.toml`
Windows	`C:\Users\<ユーザー名>\.codex\config.toml`

ファイルが存在しない場合は新規作成してください。

設定の優先順位:

Codexは以下の順に設定を読み込みます（上が優先）。

CLIオプション（-c key=value）
プロジェクトスコープ: .codex/config.toml（信頼されたプロジェクトのみ）
ユーザースコープ: ~/.codex/config.toml
ビルトインデフォルト

MCPサーバーの設定構文:

# STDIOサーバーの場合
[mcp_servers.サーバー名]
command = "実行するコマンド"        # 必須
args = ["引数1", "引数2"]          # オプション
env = { "KEY" = "value" }         # オプション: 環境変数
env_vars = ["ANOTHER_SECRET"]     # オプション: 親プロセスから引き継ぐ環境変数
cwd = "/path/to/server"           # オプション: 作業ディレクトリ
startup_timeout_sec = 10.0        # オプション: 起動タイムアウト（秒、デフォルト10）
tool_timeout_sec = 60.0           # オプション: ツール実行タイムアウト（秒、デフォルト60）
enabled = true                    # オプション: false で無効化（設定を残したまま）
required = false                  # オプション: true で起動時の必須サーバーに指定
enabled_tools = ["tool1", "tool2"] # オプション: 許可するツールのホワイトリスト
disabled_tools = ["slow-tool"]    # オプション: 拒否するツールのブラックリスト

# Streamable HTTPサーバーの場合
[mcp_servers.サーバー名]
url = "https://example.com/mcp"   # 必須
bearer_token_env_var = "TOKEN"    # オプション: Bearer認証に使う環境変数名
http_headers = { "X-Custom" = "value" }  # オプション: HTTPヘッダー

コピペ用 config.toml 設定例

すぐに使える実用的な設定例です。必要な部分だけコピーして ~/.codex/config.toml に貼り付けてください。API_KEY等のプレースホルダは自分のキーに置き換えてください。

# ~/.codex/config.toml
# モデル・基本設定
model = "gpt-5-codex"
model_reasoning_effort = "medium"

# 機能フラグ
[features]
shell_tool = true

# Context7（ドキュメント参照）— 導入必須
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

# Playwright（ブラウザ操作・テスト自動化）
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp"]

# Serena（コード静的解析・LSPベース）
[mcp_servers.serena]
command = "uvx"
args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]

方法③ CLIオプションで一時的に指定

プロジェクト固有のMCPサーバーを一時的に使いたい場合は、-c オプションが便利です。

# Playwrightだけ一時的に追加して起動
codex -c "mcp_servers={"playwright"={"command"="npx",args=["-y", "@playwright/mcp@latest"]}}"

# Serenaを一時的に追加
codex -c "mcp_servers.serena={command="uvx",args=["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"]}"

プロジェクト固有のMCP設定

Codexはグローバル設定（~/.codex/config.toml）に加えて、プロジェクト単位でMCPサーバーを設定できます。

方法①: プロジェクトルートに .codex/config.toml を配置

プロジェクトのルートディレクトリに .codex/config.toml を作成すると、そのプロジェクトでのみ有効な設定を追加できます。

# Playwright設定例
[mcp_servers.playwright]
command = "npx"
args = ["-y", "@playwright/mcp"]

注意点:

プロジェクトスコープの設定は、信頼されたプロジェクト（trusted projects） でのみ読み込まれます。未信頼のプロジェクトでは自動的にスキップされます。
.codex/ ディレクトリには認証情報なども書き込まれるため、.gitignore に追加してリポジトリにコミットしないようにしましょう。

方法②: CODEX_HOME 環境変数を使う

CODEX_HOME=./.codex codex

読み込みディレクトリ自体を変更する方法です。ただし、ワークアラウンド的な手法であり、今後公式にプロジェクト固有MCP設定が改善される可能性があります。

方法③: -c オプション + エイリアス

プロジェクトごとに異なるMCPを使いたいが、config.tomlのコミットは避けたい場合に有効です。

# .zshrc にエイリアスを登録
alias codex-pw="codex -c "mcp_servers.playwright={command=\"npx\",args=[\"-y\", \"@playwright/mcp@latest\"]}""

IDE拡張機能でのMCP設定

Codex MCPはCLIだけでなく、VS Code / Cursor などのIDE拡張機能でも利用できます。CLIとIDE拡張機能は同じconfig.tomlを共有しているため、一度MCPを設定すればどちらからでもそのまま使えます。

IDE拡張機能のインストール

Visual Studio Code Marketplaceからインストール
Cursor などのVS Codeフォークでも動作
インストール後、サイドバーにCodexアイコンが表示される

IDEからMCP設定を開く

IDE拡張機能の右上にある歯車アイコンをクリックし、「Codex Settings > Open config.toml」 を選択すると、config.tomlがエディタ上で開きます。ここでMCPサーバーの追加・編集が可能です。

IDE拡張機能の承認モード

MCPツールの利用時には承認が求められます。IDE拡張機能では3つのモードがあります。

Auto（デフォルト）: 作業フォルダ内は自動で進めるが、範囲外やネットワーク等は確認が入る
Read-only: ファイル閲覧はできるが、編集やコマンド実行は承認が必要（「相談モード」）
Full Access: すべての操作を承認なしで実行（リスクあり）

MCPツールの承認を省略する

環境によっては、MCP/Appツールの承認に「Allow and remember（許可を記憶）」のようなオプションが表示され、同一セッション中の繰り返し承認を省略できます。

Windows環境での設定ガイド

Windows環境では、PATHの解決がうまくいかずエラーになることが多く報告されています。

よくあるエラーと原因

MCP client for "context7" failed to start: program not found
MCP client for "playwright" failed to start: request timed out

原因はWindowsでは npx や node のパスが自動解決されないことです。

解決策: フルパスを指定する

PowerShellでパスを確認します。

where.exe npx
where.exe node

config.tomlにフルパスを記述します。

[mcp_servers.context7]
command = "C:\\Program Files\\nodejs\\npx.cmd"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
SYSTEMROOT = "C:\Windows"

ポイントとして、npx ではなく npx.cmd のフルパスを指定すること、SYSTEMROOT 環境変数を設定すること、初回はパッケージダウンロードに時間がかかるため事前に手動実行しておくことが重要です。

Codex自体をMCPサーバーとして公開する方法

Codex CLIは自身をMCPサーバーとして公開し、他のAIエージェントから利用させることもできます。

基本的な起動方法

codex mcp-server

stdio経由でJSON-RPCをやり取りするMCPサーバーが起動します。主に codex（新規セッション開始）と codex-reply（既存セッション継続）の2つのツールが公開されます。

Claude CodeからCodexを呼び出す

claude mcp add -s user codex -- codex mcp-server
claude mcp list

接続後、Claude Codeで「Codex MCPを使って現在のコードの改善点を分析してください。」と入力すると、Claude Codeがプロンプトを整理した上でCodexに渡すため、二段構えの分析が得られます。

トラブルシューティング

MCPサーバーが起動しない

「program not found」エラー: npxやuvxにPATHが通っているか確認。Windowsの場合はフルパスを指定。

「request timed out」エラー: startup_timeout_secを延長（デフォルト10秒→30〜60秒に変更）。

[mcp_servers.heavy_server]
command = "npx"
args = ["heavy-mcp-server"]
startup_timeout_sec = 60.0

config.tomlの形式エラーでCodexが起動しない

他のエージェントの .mcp.json をそのまま config.toml にコピーするとエラーになります。JSONとTOMLは形式が異なるため、必ずTOML形式に変換してください。設定の確認には /debug-config スラッシュコマンドも使えます。

セキュリティに関する注意事項

Web検索機能のリスク

Codexの web_search 機能には disabled（無効）、cached（キャッシュのみ、デフォルト）、live（リアルタイム検索）の3段階があります。liveモードはプロンプトインジェクションのリスクがあるため注意が必要です。cachedモードはOpenAIが管理するインデックスから結果を返すため、ライブモードより安全ですが、それでもWeb検索結果は信頼されていない情報として扱う必要があります。

APIキーの管理

config.tomlにAPIキーを直接記述する場合、このファイルをGitにコミットしないよう注意してください。bearer_token_env_var や env_vars を使い、環境変数経由でトークンを渡す方法が推奨されます。

よくある質問（FAQ）

Q. Codex MCPとは何ですか？

Codex MCPとは、OpenAIのコーディングエージェント「Codex CLI」におけるMCP（Model Context Protocol）の対応機能のことです。MCPを使うことで、Codexに外部ツールを接続して機能を拡張できます。

Q. MCPサーバーは無料で使えますか？

多くのMCPサーバーはオープンソースで無料です。Context7、Playwright、Serenaなどは無料で利用できます。一部のサーバーはAPIキーが必要で、利用量に応じた課金が発生する場合があります。

Q. Codex MCPの設定がうまくいかないときは？

まず codex mcp list で接続状態を確認してください。「program not found」ならPATHの問題、「request timed out」ならタイムアウト設定の延長を試みてください。

Q. config.tomlとJSON形式（.mcp.json）の違いは？

Codex CLIはTOML形式（config.toml）、Claude Codeなどの他のエージェントはJSON形式（.mcp.json）を使います。形式が異なるため、他エージェントの設定をそのままコピーすると起動エラーになります。

Q. IDE拡張機能とCLIでMCPの設定を共有できますか？

はい。CLIとIDE拡張機能は同じ ~/.codex/config.toml を読み込むため、一度設定すればどちらからでも同じMCPサーバーを利用できます。

まとめ

Codex MCPは、Codex CLIの能力を大幅に拡張する仕組みです。

MCPの基本: Codex CLIは「MCPクライアント」と「MCPサーバー」の両方の役割を持つ
設定方法: codex mcp add コマンド、config.toml直接編集、-c オプションの3つ
IDE対応: CLIとIDE拡張機能はconfig.tomlを共有
おすすめサーバー: Context7は必須級。用途に応じてPlaywright、Serena、GitHub MCPなどを追加
Windows対策: npx.cmd のフルパス指定と SYSTEMROOT 環境変数の設定が必要
マルチエージェント: codex mcp-server でCodex自体をMCPサーバーとして公開可能
プロジェクト固有設定: .codex/config.toml でプロジェクト単位のMCP設定が可能

MCPエコシステムは急速に拡大しており、業界全体で標準化が進んでいます。まずはContext7から導入し、開発ワークフローに合わせて少しずつ拡張していくのがおすすめです。

記事入稿も、公開予約も、AIで。
人が行う作業にサヨナラできるヘッドレスCMS「NILTO」

コンテンツ運用における「時間がない」「アイデアが枯渇した」「人手が足りない」といったお悩みはありませんか？

これからのコンテンツ管理は、AIエージェントがサポートする時代です。

フェンリルが提供する国産ヘッドレスCMS『NILTO』の新機能「NILTO MCP（Model-Context-Protocol）」は、 AIエージェントによる高度なコンテンツ運用の自動化を可能にします。

プロンプトの指示で情報収集から原稿入稿、承認依頼、公開予約までを一気通貫で対応し、施策にかかるリードタイムと作業コストを劇的に削減します。

現在は、テクニカルプレビューとして全プランでご利用いただけます。

皆様が利用されたフィードバックを元にブラッシュアップを行っていますので、今ご利用いただければ、あなたの貴重なご意見がNILTOに反映されるチャンスです。
このタイミングでぜひご利用ください。