AIコーディングガイド

Codex CLI に MCP サーバーを設定する:config.toml の書き方と接続確認

Codex 公開:

Codex CLI で MCP サーバーを使うための設定方法を解説します。config.toml の [mcp_servers] セクションの書き方、環境変数の渡し方、codex mcp コマンドによる追加と一覧、接続できないときの確認手順を紹介します。

検証日 2026年9月7日 仕様変更が早い分野です。最新の公式ドキュメントも併せてご確認ください。
#Codex#Codex CLI#MCP#config.toml#連携
目次
  1. config.toml に書く
  2. codex mcp コマンドで追加する
  3. 接続を確認する
  4. 使い方の例
  5. Claude Code・Gemini CLI との設定の違い
  6. まとめ

MCP(Model Context Protocol)サーバーを Codex CLI に接続すると、ブラウザ操作、ドキュメント検索、Issue 管理などを Codex が自分で判断して実行できるようになります。Codex の MCP 設定は config.toml に集約されており、Claude Code や Gemini CLI とは書き方が異なります。

この記事では、config.toml への書き方、コマンドによる追加、接続確認とトラブル時の切り分けをまとめます。

KEY POINT

この記事で分かること

  • [mcp_servers.名前] セクションの書き方(stdio 方式)
  • 環境変数・トークンの安全な渡し方
  • 接続確認と、動かないときの切り分け手順

config.toml に書く

~/.codex/config.toml に、サーバーごとにセクションを追加します。

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_TOKEN}" }
キー意味
commandサーバーを起動するコマンド
argsコマンドの引数(配列)
envサーバープロセスに渡す環境変数

env に書いた値は、サーバーの起動時に渡されます。トークンは直接書かず、シェルの環境変数から読ませるのが原則です。

トークンを config.toml に直接書かない

config.toml はバックアップや dotfiles の共有で外部に出やすいファイルです。env にはトークンそのものではなく、${GITHUB_TOKEN} のように環境変数の参照を書き、実体はシェルの環境変数に置いてください。環境変数の展開に対応していないバージョンの場合は、ラッパースクリプトを command に指定して、スクリプト内で環境変数を読む方法があります。

codex mcp コマンドで追加する

手で TOML を書く代わりに、コマンドで追加することもできます。

codex mcp add playwright -- npx @playwright/mcp@latest
codex mcp list
codex mcp remove playwright

追加した内容は config.toml に書き込まれるため、後から手で編集して構いません。サブコマンドの対応状況はバージョンで異なるので、codex mcp --help で確認してください。

接続を確認する

Codex を起動し、対話中に /mcp を実行すると、登録されたサーバーと提供ツールの一覧が表示されます。一覧に出ない、または接続エラーになる場合は次の順で切り分けます。

  1. サーバーを単体で起動する: npx @playwright/mcp@latest をターミナルで直接実行し、エラーが出ないか確認します。npm のダウンロード失敗や Node.js のバージョン不足はここで分かります。
  2. 環境変数を確認する: echo $GITHUB_TOKEN で値が入っているか確認します。Codex を起動したシェルに環境変数がなければ、サーバーにも渡りません。
  3. TOML の構文を確認する: 配列のカンマ漏れ、クォートの閉じ忘れが多い原因です。/status で設定が読み込まれているか確認します。
  4. サンドボックスのネットワーク制限: MCP サーバー自体は Codex のサンドボックス外で動きますが、Codex が実行するコマンドがネットワークを使う場合は network_access の設定が影響します(approval mode と sandbox 設定の違い)。

用語解説

stdio 方式: Codex がサーバーをサブプロセスとして起動し、標準入出力で通信する方式です。ローカルで動く MCP サーバーの多くがこの方式です。リモートサーバー(HTTP)への対応状況は公式ドキュメントで確認してください。

使い方の例

MCP サーバーが接続されていれば、指示の中で自然に使われます。

  • Playwright: 「開発サーバーを起動して、ログイン画面のスクリーンショットを撮って確認して」
  • Context7: 「Prisma の最新ドキュメントを参照して、複合ユニーク制約の書き方を確認してから実装して」
  • GitHub: 「Issue #42 の内容を読んで、修正方針を提案して」

ツールの実行には承認ポリシーが適用されます。Codex が MCP ツールを使おうとして確認が出た場合、内容を見て許可します。

Claude Code・Gemini CLI との設定の違い

ツール設定ファイル形式
Codex~/.codex/config.tomlTOML の [mcp_servers.名前]
Claude Code.mcp.json / ~/.claude.jsonJSON の mcpServers
Gemini CLI~/.gemini/settings.json / .gemini/settings.jsonJSON の mcpServers

指定する内容(command / args / env)は共通なので、1 つのツールで動いた設定は他のツールにも書き換えるだけで使えます。Claude Code の設定は Claude Code に MCP サーバーを追加する方法、Gemini CLI は Gemini CLI に MCP サーバーを追加する を参照してください。最初に入れるサーバーの候補は コーディング AI で最初に入れるべき MCP サーバー にまとめています。

まとめ

  • ~/.codex/config.toml の [mcp_servers.名前] に command / args / env を書く
  • トークンは環境変数から読ませ、config.toml に直接書かない
  • /mcp で接続状態を確認し、動かないときはサーバー単体起動 → 環境変数 → TOML 構文の順で切り分ける
  • command / args / env の内容は Claude Code や Gemini CLI と共通なので流用できる

よくある質問

Codex の MCP 設定はどこに書きますか?
~/.codex/config.toml の [mcp_servers.名前] セクションです。codex mcp add コマンドで追加すると自動的に書き込まれます。
Claude Code の .mcp.json をそのまま使えますか?
形式が異なるため、そのままでは使えません。command / args / env の内容を TOML に書き直す必要があります。
MCP サーバーのツールは承認なしで実行されますか?
承認ポリシーに従います。on-request では Codex が必要と判断したときに確認が入ります。

参考にした一次情報

この記事は公式ドキュメントを基に AI が下書きを作成し、運営者が内容を確認して公開しています。誤りを見つけた場合はお問い合わせからお知らせください。

関連記事