Codexの設定 - MCPサーバ

概要

MCP (Model Context Protocol) は、LLMと外部ツールの統合を標準化したオープンプロトコルである。

OpenAI Codex CLIは、このプロトコルに対応しており、MCPサーバを設定することにより、ドキュメント参照、ブラウザ操作、デザインツール、イシュートラッカー、GitHubリポジトリ管理など多様な外部システムと連携できる。

Codex CLIのMCP設定の主な特長を以下に示す。

• Codex CLI と IDE Extensionの設定共有

  ~/.codex/config.toml のユーザ設定はCLIとVS Code拡張機能の両方で共有される。

• TOML形式の設定ファイル

  MCPサーバはTOML形式の設定ファイルで管理される。

• 2つのトランスポート方式

  ローカルプロセス起動のSTDIO方式 と URLによるStreamable HTTP方式をサポートする。

• Skillsとの連携

  Skillsファイルから必要なMCPサーバの依存関係を宣言でき、スキル実行時に自動的にロードされる。

下表に、Codex CLIのMCP連携により接続できる主な外部システムを示す。

MCP連携の主な用途

カテゴリ	主な用途	例
ドキュメント	最新の公式ドキュメント参照	Context7
ブラウザ	ウェブ操作・スクレイピング	Chrome DevTools、Playwright
デザイン	UIデザインファイル参照	Figma
イシュー管理	タスク・課題管理	Linear、GitHub Issues
バージョン管理	リポジトリ操作	GitHub MCP
ファイルシステム	ローカルファイル操作	Filesystem MCP

設定ファイルの保存場所

MCPサーバの設定は、ユーザスコープとプロジェクトスコープの2つの場所で管理される。

設定ファイルの保存場所

スコープ	ファイルパス	説明
ユーザ (グローバル)	~/.codex/config.toml	全プロジェクトで共通のMCPサーバ設定 Codex CLIとIDE Extension (VS Code等) で共有される。
プロジェクト	.codex/config.toml	プロジェクトルートに配置するプロジェクト固有の設定 信頼済みのプロジェクトとして承認された場合のみロードされる。

プロジェクトスコープの設定ファイルは、Codexがそのプロジェクトディレクトリを信頼済みとして認識した場合にのみ読み込まれる。
これにより、クローンしたばかりの第三者リポジトリが自動的に任意のMCPサーバを起動するリスクを回避できる。

2つのトランスポート方式

Codex CLIのMCPサーバは、2つのトランスポート方式をサポートしている。

STDIOサーバ (ローカルプロセス起動)

STDIOサーバは、ローカルプロセスとして起動してstdin/stdoutで通信するトランスポート方式である。

ファイルシステム操作、コード解析ツール等、システムリソースへの直接アクセスが必要なツールに適している。

STDIOサーバの設定では、command、args、env を使用してプロセスを起動する。

TOMLサンプルを以下に示す。

 [mcp_servers.context7]
 command = "npx"
 args = ["-y", "@upstash/context7-mcp"]
 
 [mcp_servers.filesystem]
 command = "npx"
 args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
 env = { LOG_LEVEL = "info" }
 cwd = "/home/user"
 startup_timeout_sec = 15
 tool_timeout_sec = 60

HTTPサーバ (Streamable HTTP)

HTTPサーバは、URLを指定してHTTP経由で通信するトランスポート方式である。

クラウドサービスやリモートAPIへの接続に適しており、GitHub MCP等のWebサービスとの連携に使用される。

HTTPサーバの設定では、url にサーバのエンドポイントを指定する。
認証が必要な場合は、bearer_token_env_var または http_headers を使用する。

TOMLサンプルを以下に示す。

 [mcp_servers.github_mcp]
 url = "http://localhost:3000/mcp"
 bearer_token_env_var = "GITHUB_TOKEN"
 startup_timeout_sec = 15
 tool_timeout_sec = 90
 
 [mcp_servers.remote_api]
 url = "https://api.example.com/mcp"
 http_headers = { "X-Custom-Header" = "custom-value" }
 env_http_headers = { "Authorization" = "API_KEY_ENV_VAR" }
 enabled = true

TOML設定オプション

各MCPサーバで使用できる設定オプションを示す。

STDIO Server用設定

下表に、STDIOトランスポート方式で使用できる設定オプションを示す。

STDIO Server設定オプション

オプション	型	デフォルト	説明
command	文字列	(必須)	起動するコマンド 例: "npx"、"node"、"python"
args	文字列配列	[]	コマンドに渡す引数リスト 例: ["-y", "@upstash/context7-mcp"]
env	テーブル	{}	プロセスに渡す環境変数 例: { API_KEY = "value" }
cwd	文字列	(なし)	プロセスの作業ディレクトリ 省略時はCodexの作業ディレクトリを使用する。
startup_timeout_sec	整数	10	サーバ起動完了を待機する最大秒数
tool_timeout_sec	整数	60	ツール呼び出しの完了を待機する最大秒数
enabled	真偽値	true	false に設定すると、このサーバを無効化する。
required	真偽値	false	true にすると、サーバが起動できない場合にCodexの起動を中止する。

HTTP Server用設定

下表に、HTTPトランスポート方式で使用できる設定オプションを示す。

HTTP Server設定オプション

オプション	型	デフォルト	説明
url	文字列	(必須)	MCPサーバのエンドポイントURL 例: "https://api.example.com/mcp"
bearer_token_env_var	文字列	(なし)	BearerトークンとなるAPIキーを格納した環境変数名 例: "GITHUB_TOKEN"
http_headers	テーブル	{}	静的なHTTPヘッダ 例: { "X-Custom" = "value" }
env_http_headers	テーブル	{}	環境変数を参照するHTTPヘッダ 例: { "Authorization" = "TOKEN_ENV_VAR" }
startup_timeout_sec	整数	10	サーバへの初回接続確立を待機する最大秒数
tool_timeout_sec	整数	60	ツール呼び出しの完了を待機する最大秒数
enabled	真偽値	true	false に設定すると、このサーバを無効化する。

codex mcpサブコマンド

下表に、MCPサーバを管理するためのCLIサブコマンドを示す。

codex mcp サブコマンド一覧

コマンド	説明
codex mcp add <name> -- <command>	STDIOサーバをユーザ設定に追加する。
codex mcp list	設定済みのMCPサーバ一覧を表示する。
codex mcp list --json	MCPサーバ一覧をJSON形式で出力する。
codex mcp get <name>	指定したMCPサーバの設定詳細を表示する。
codex mcp get <name> --json	指定したMCPサーバの設定詳細をJSON形式で出力する。
codex mcp login <name>	指定したHTTPサーバのOAuth認証フローをブラウザで開始する。
codex mcp logout <name>	指定したHTTPサーバのOAuth認証情報をキャッシュから削除する。
codex mcp remove <name>	指定したMCPサーバをユーザ設定から削除する。

各コマンドの使用例を以下に示す。

# サーバ一覧を表示
codex mcp list

# JSON形式で出力
codex mcp list --json

# 特定サーバの詳細を確認
codex mcp get context7

# サーバを削除
codex mcp remove context7

CLI でサーバを追加する例

codex mcp add コマンドを使用して、対話なしにMCPサーバを追加できる。

基本的なコマンド形式を以下に示す。

codex mcp add <name> -- <command> [args...]

例1: Context7 (ドキュメント参照)

Context7 MCPサーバを追加する例を以下に示す。

codex mcp add context7 -- npx -y @upstash/context7-mcp

例2: 環境変数を指定してサーバを追加

--env オプションで環境変数を指定してサーバを追加する例を以下に示す。

codex mcp add my_server --env API_KEY=mykey -- node /path/to/server.js

APIキーを直接コマンドラインに記述する代わりに、シェルの環境変数から参照することも可能である。

codex mcp add my_server --env API_KEY=$MY_API_KEY -- node /path/to/server.js

例3: 複数引数 (Chrome DevTools)

Chrome DevTools MCPサーバのように複数の引数が必要な場合の例を以下に示す。

codex mcp add chrome_devtools -- npx -y @modelcontextprotocol/server-puppeteer --headless false --port 9222

追加後は、codex mcp get コマンドで設定内容を確認できる。

codex mcp get chrome_devtools

OAuth設定 (HTTPサーバ)

HTTPサーバでOAuth認証を使用する場合の設定方法を示す。

グローバル設定

OAuth認証に関するグローバル設定は、mcp_oauth_callback_port および mcp_oauth_callback_url で行う。

デフォルトでは、Codexはエフェメラルポート (OS が自動割り当てする使用中でないポート) を使用してOAuthコールバックを受け付ける。
固定ポートが必要な場合は mcp_oauth_callback_port に明示的なポート番号を指定する。

 # OAuthコールバックを受け付ける固定ポート (省略時はエフェメラルポート)
 mcp_oauth_callback_port = 3939
 
 # リバースプロキシ等を使用する場合はコールバックURLを明示指定
 mcp_oauth_callback_url = "https://example.com/callback"

サーバ設定と login コマンド

OAuth対応のHTTPサーバを設定して認証を行う手順を以下に示す。

まず、TOMLファイルにサーバを定義する。

 [mcp_servers.github_mcp]
 url = "https://api.githubcopilot.com/mcp/"
 startup_timeout_sec = 20
 tool_timeout_sec = 120

次に、以下に示すコマンドでブラウザ経由のOAuth認証フローを開始する。

codex mcp login github_mcp

コマンドを実行するとブラウザが開き、OAuthプロバイダの認証ページが表示される。
認証を完了すると、アクセストークンがローカルにキャッシュされ、以降のリクエストで自動的に使用される。

認証情報を削除する場合は以下のコマンドを実行する。

codex mcp logout github_mcp

HTTPヘッダ設定

HTTPサーバでカスタムヘッダを使用する2つの方法を示す。

静的ヘッダ (http_headers)

固定値のHTTPヘッダを設定する場合は http_headers を使用する。

設定ファイルに平文で記載される値であるため、機密情報以外のヘッダに使用することを推奨する。

 [mcp_servers.custom_service]
 url = "https://api.example.com/mcp"
 
 [mcp_servers.custom_service.http_headers]
 "X-Service-Version" = "v2"
 "X-Client-Name"     = "codex-cli"
 "Content-Type"      = "application/json"

環境変数参照ヘッダ (env_http_headers)

APIキーやトークン等の機密情報を含むヘッダは、env_http_headers を使用して環境変数から参照する。
テーブルのキーはHTTPヘッダ名、値は参照する環境変数名を指定する。

 [mcp_servers.secure_api]
 url = "https://secure.example.com/mcp"
 
 [mcp_servers.secure_api.http_headers]
 "X-Service-Version" = "v1"
 
 [mcp_servers.secure_api.env_http_headers]
 "Authorization" = "SECURE_API_TOKEN"
 "X-API-Key"     = "SECURE_API_KEY"

上記の設定では、実行時に環境変数 SECURE_API_TOKEN の値が Authorization ヘッダとして送信される。

タイムアウト設定のガイドライン

MCPサーバのタイムアウト設定には、startup_timeout_sec と tool_timeout_sec の2つのオプションがある。

• startup_timeout_sec

  サーバの起動完了またはHTTP接続確立を待機する最大秒数

  デフォルトは10秒

  npmパッケージのダウンロードが必要なSTDIOサーバや初期化処理が重いサーバは延長する。

• tool_timeout_sec

  ツール呼び出しの完了を待機する最大秒数

  デフォルトは60秒

  データベースクエリ、外部API呼び出し、ファイル処理等の処理時間に応じて調整する。

下表に、用途別のタイムアウト調整ガイドを示す。

タイムアウト設定ガイド

用途・環境	startup_timeout_sec	tool_timeout_sec	説明
高速STDIOサーバ	5〜10秒	30〜60秒	ローカルスクリプト等、すぐに起動するサーバ
npmパッケージ起動	15〜30秒	60〜120秒	初回起動時にダウンロードが発生するサーバ
HTTPサーバ	15〜30秒	60〜120秒	ネットワーク遅延を考慮した設定
Docker等大規模初期化	30〜60秒	60〜180秒	コンテナ起動等、初期化に時間がかかる環境
長時間処理ツール	10〜30秒	60〜300秒	大規模ファイル処理、長時間クエリ等

アクティブMCPサーバの確認

セッション中にアクティブなMCPサーバとツールの状態を確認する方法を示す。

Codexのチャット画面で以下のスラッシュコマンドを入力することにより、現在接続中のMCPサーバ一覧と各サーバが提供するツールの一覧を確認できる。

/mcp

詳細情報を確認する場合は、以下に示すコマンドを実行する。

/mcp verbose

/mcp verbose では、各サーバの接続状態、利用可能なツール一覧、ツールのパラメータ情報、最終接続時刻等の詳細情報が表示される。

MCPサーバ設定サンプル

代表的なMCPサーバの設定例を示す。

Context7 (ドキュメント)

最新の公式ドキュメントをCodexに提供するContext7の設定例を以下に示す。

 [mcp_servers.context7]
 command = "npx"
 args    = ["-y", "@upstash/context7-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec    = 60
 enabled  = true
 required = false

GitHub MCP (HTTP + OAuth)

GitHub MCP ServerをOAuth認証で使用する場合の設定例を以下に示す。

設定後、codex mcp login github を実行してOAuth認証を行う。

 [mcp_servers.github]
 url                 = "https://api.githubcopilot.com/mcp/"
 startup_timeout_sec = 20
 tool_timeout_sec    = 120
 enabled             = true

ローカルFilesystemサーバ

ローカルファイルシステムを操作するMCPサーバの設定例を以下に示す。

args の末尾にアクセスを許可するディレクトリパスを指定する。

 [mcp_servers.filesystem]
 command = "npx"
 args    = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
 cwd     = "/home/user"
 startup_timeout_sec = 15
 tool_timeout_sec    = 60

カスタム環境変数を使用

環境変数でAPIキーを渡すカスタムMCPサーバの設定例を以下に示す。

config.toml に平文のシークレットを記載せず、環境変数から参照することを推奨する。

 [mcp_servers.my_api_server]
 command = "node"
 args    = ["/home/user/.local/bin/my-mcp-server/index.js"]
 cwd     = "/home/user/.local/bin/my-mcp-server"
 startup_timeout_sec = 10
 tool_timeout_sec    = 60
 
 [mcp_servers.my_api_server.env]
 API_KEY      = "${MY_API_KEY}"
 API_ENDPOINT = "https://api.example.com"
 LOG_LEVEL    = "info"

セキュリティと認証

MCPサーバの認証設定とセキュリティ上の注意事項を示す。

Bearer Token認証 (bearer_token_env_var)

HTTPサーバへの認証にBearerトークンを使用する場合は bearer_token_env_var を利用する。

この設定では、指定した環境変数の値が自動的に Authorization: Bearer <value> ヘッダとして送信される。

 [mcp_servers.private_api]
 url                  = "https://private.example.com/mcp"
 bearer_token_env_var = "PRIVATE_API_TOKEN"

カスタムヘッダ認証

BearerトークンではなくAPIキーをカスタムヘッダで送信する場合は env_http_headers を使用する。

 [mcp_servers.api_key_service]
 url = "https://service.example.com/mcp"
 
 [mcp_servers.api_key_service.env_http_headers]
 "X-API-Key" = "SERVICE_API_KEY"

APIキーの安全な管理

APIキーを安全に管理するための推奨事項を以下に示す。

• config.toml に平文のAPIキーを直接記載しない。

  環境変数 (${ENV_VAR}) または bearer_token_env_var、env_http_headers を使用して参照する。

  
  

• ~/.codex/config.toml はホームディレクトリに配置されるため、パーミッションを確認する。

  chmod 600 ~/.codex/config.toml を実行して読み取り権限を制限することを推奨する。

  
  

• プロジェクトの .codex/config.toml をGitリポジトリに含める場合は、APIキー等の機密情報を記載しない。

  .gitignore に .codex/config.toml を追加することを検討する。

Codex自体をMCPサーバとして起動

Codex CLI自体をMCPサーバとして起動し、他のツールやクライアントから接続することができる。

以下に示すコマンドを実行して、Codexをstdio経由のMCPサーバとして起動する。

codex mcp serve

この機能の主な用途を以下に示す。

• 他のAIツールやMCPクライアントからCodexの機能を呼び出す。
• Claude Desktop等のMCPクライアントでCodexをツールとして使用する。
• 複数のAIエージェントを連携させるマルチエージェント構成を構築する。

Claude Desktop等からCodexをMCPサーバとして使用する場合の設定例を以下に示す。

 {
    "mcpServers": {
       "codex": {
          "command": "codex",
          "args": ["mcp", "serve"]
       }
    }
 }

codex mcp serve はダウンストリームクライアントが接続を終了するまで実行し続け、クライアント終了時に自動的に終了する。

MCPとSkillsの連携

Skillsファイルの agents/openai.yaml にMCPサーバの依存関係を宣言することにより、スキル実行時に必要なMCPサーバが自動的にロードされる。

agents/openai.yaml によるMCP依存宣言

スキルが必要とするMCPサーバを mcpServers フィールドに列挙する。

 # agents/openai.yaml
 name: my-skill
 description: ドキュメント参照とGitHub操作が必要なスキル
 
 mcpServers:
    - context7
    - github

依存MCPサーバの自動ロード

mcpServers に列挙したサーバは、スキルのトリガー時にCodexが自動的に起動・接続する。

設定ファイル (config.toml) にそのサーバが定義されていない場合のふるまいは、feature flagにより制御される。

• 不足しているMCPの自動インストール機能

  デフォルト: 有効

  設定ファイルに存在しないMCPサーバがスキルに宣言されている場合、Codexは自動的にインストールを試みる。

  この機能はデフォルトで有効になっており、必要なサーバが未設定でもスキルを実行できる。

yamlサンプル

複数のMCPサーバに依存するスキルの設定例を以下に示す。

 # agents/openai.yaml
 name: full-stack-review
 description: フルスタックコードレビュースキル。ドキュメント参照、GitHub操作、ファイルシステムアクセスを使用する。
 
 mcpServers:
    - context7
    - github
    - filesystem
 
 model: o4-mini
 temperature: 0.2

よくある設定パターン

複数のSTDIOサーバを同時に使用

複数のMCPサーバを同時に設定する場合の例を以下に示す。
各サーバは独立したプロセスとして管理される。

 [mcp_servers.context7]
 command = "npx"
 args    = ["-y", "@upstash/context7-mcp"]
 
 [mcp_servers.filesystem]
 command = "npx"
 args    = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
 
 [mcp_servers.sequential_thinking]
 command = "npx"
 args    = ["-y", "@modelcontextprotocol/server-sequential-thinking"]

起動が遅いサーバ向けのタイムアウト調整 (Docker例)

Dockerコンテナとして起動するMCPサーバや初期化に時間が掛かるMCPサーバは、startup_timeout_sec を延長する。

 [mcp_servers.db_server]
 command = "docker"
 args    = ["run", "--rm", "-i", "-e", "DATABASE_URL", "my-db-mcp-image:latest"]
 startup_timeout_sec = 60
 tool_timeout_sec    = 180
 required = false
 
 [mcp_servers.db_server.env]
 DATABASE_URL = "${DATABASE_URL}"

プロジェクトスコープのMCP

プロジェクト固有のMCPサーバは .codex/config.toml に定義して、チームで共有する。
機密情報を含まない設定のみをリポジトリにコミットすることを推奨する。

 # .codex/config.toml (プロジェクトルート)
 [mcp_servers.project_docs]
 command = "npx"
 args    = ["-y", "@upstash/context7-mcp"]
 
 [mcp_servers.project_linter]
 command = "node"
 args    = ["./tools/mcp-linter/index.js"]
 cwd     = "."
 startup_timeout_sec = 10
 tool_timeout_sec    = 30

トラブルシューティング

MCPサーバが正常に動作しない場合の対処方法を示す。

Startup Timeoutエラー

サーバの起動がタイムアウトする場合の確認事項と対処方法を以下に示す。

• 原因と確認事項

  command で指定したコマンドが正しくインストールされていない。

  npmパッケージの初回ダウンロードに時間がかかっている。

  cwd で指定したディレクトリが存在しない。

• 対処方法

  startup_timeout_sec の値を20〜60秒に増やす。

  コマンドを手動で実行して正常に起動することを確認する。

  npmパッケージの場合は事前に npx -y <package> を実行してキャッシュしておく。

# STDIOサーバを手動で起動して動作確認
npx -y @upstash/context7-mcp

# 設定内容を確認
codex mcp get context7

Tool Timeoutエラー

ツール呼び出しがタイムアウトする場合の確認事項と対処方法を以下に示す。

• 原因と確認事項

  処理に時間がかかる操作 (大規模ファイル処理、重いデータベースクエリ等) を実行している。

  ネットワーク遅延やサーバの応答が遅い。

• 対処方法

  tool_timeout_sec の値を120〜300秒に増やす。

  大規模な操作を分割して小さなリクエストに分ける。

HTTP接続失敗

HTTPサーバへの接続に失敗する場合の確認事項と対処方法を以下に示す。

• 原因と確認事項

  url で指定したエンドポイントに誤りがある。

  認証トークンが無効または期限切れである。

  ファイアウォールやプロキシが接続をブロックしている。

• 対処方法

  curl コマンドでエンドポイントへの接続を確認する。

  bearer_token_env_var に指定した環境変数が正しく設定されているか確認する。

  OAuthを使用している場合は codex mcp logout <name> を実行してから再度 codex mcp login <name> で認証し直す。

# HTTPエンドポイントへの接続確認
curl -v https://api.example.com/mcp

# 環境変数の確認
echo $GITHUB_TOKEN

# OAuth再認証
codex mcp logout github
codex mcp login github

関連ページ

• Codexの設定 - 機能
• Codexの設定 - サブエージェント
• Codexの設定 - SKILL
• MCPサーバ - Context7