ai-tools-kbMarkdown が正

facts ／Codex ／mcp

stable4 日前 · 2026-08-09

Model Context Protocol

概要

モデルとツール・コンテキストをつなぐプロトコル。サードパーティのドキュメントへのアクセスや、ブラウザ・Figma といった開発ツールとの連携に使う。ローカルの Codex クライアントは MCP サーバーに直接接続でき、ChatGPT web は plugin が供給するリモートの MCP ベースツールを使う。

仕様

対応する機能

ChatGPT desktop app / Codex CLI / IDE extension が MCP サーバーに対応し、同じ Codex ホストであれば MCP 設定を共有する。以下は Codex ホストに設定した MCP サーバーに対する対応範囲で、hosted な plugin ツールは異なる機能を持ちうる。

  • STDIO サーバー（コマンドで起動するローカルプロセス）: 環境変数に対応
  • Streamable HTTP サーバー（アドレスでアクセス）: Bearer token 認証、OAuth 認証、信頼された first-party サーバー向けの ChatGPT セッション認証
  • Server instructions: 初期化時に返る MCP の instructions フィールドを読み、そのサーバーのツールと併せてサーバー全体の指針として使う
    • サーバー作者向けの指針として、instructions にはツール横断のワークフロー・制約・レートリミットを書き、先頭 512 文字だけで自己完結させることが推奨されている

設定の場所

  • MCP 設定は他の Codex 設定と同じ config.toml に入る。既定は ~/.codex/config.toml
  • .codex/config.toml でプロジェクトにスコープすることもできる（trusted なプロジェクトのみ）
  • ChatGPT desktop app / Codex CLI / IDE extension はこの設定を共有するため、設定後はクライアントを切り替えても再設定は要らない
  • ChatGPT web はローカルの Codex 設定ファイルを読まず、ローカルのコマンドメニューも公開しない。ChatGPT Work の Plugins から管理する

サーフェスごとの設定手順

サーフェス手順
ChatGPT desktop appSettings > MCP servers > Add server で名前・STDIO または Streamable HTTP・コマンドまたは URL を入力し、保存して Restart。サーバー一覧に有効状態と OAuth 要否が出る。composer で /mcp を打つと接続中のサーバーを確認できる
Codex CLIcodex mcp add <server-name> --env VAR1=VALUE1 -- <stdio server-command>。codex mcp list で一覧、codex mcp --help で全コマンド、codex mcp login <server-name> で OAuth ログイン。TUI では /mcp
IDE extension歯車メニュー > MCP servers > Add server。保存して Restart extension
ChatGPT Work（web）plugin をインストールして、そのバンドル connector とリモート MCP ツールを使う。ワークスペース管理者が利用可能な plugin とツールを制御できる

STDIO サーバーの設定

キー必須説明
commandはいサーバーを起動するコマンド
argsいいえ渡す引数
envいいえサーバーに設定する環境変数
env_varsいいえ許可して転送する環境変数
cwdいいえサーバーを起動する作業ディレクトリ
experimental_environmentいいえremote にすると、利用可能なときリモート executor 環境で stdio サーバーを起動する
  • env_vars はプレーンな変数名か、source を持つオブジェクトを含められる
  • 文字列エントリと source = "local" は Codex のローカル環境から読む。source = "remote" はリモート executor 環境から読み、remote MCP stdio を必要とする

Streamable HTTP サーバーの設定

キー必須説明
urlはいサーバーのアドレス
authいいえ設定済みの bearer token と authorization ヘッダーの後に試す認証。oauth（既定）は保存済みの MCP OAuth 資格情報、chatgpt は信頼された first-party の ChatGPT オリジンに対して現在の ChatGPT セッションを使い、保存済み OAuth にフォールバックする
bearer_token_env_varいいえAuthorization に載せる bearer token の環境変数名
http_headersいいえヘッダー名 → 静的な値
env_http_headersいいえヘッダー名 → 環境変数名（値は環境から取る）
  • 資格情報のソースがどれも解決しない場合、Codex は認証なしでサーバーに接続しうる。MCP OAuth ログインは codex mcp login <server-name> で別途行う

共通のオプション

キー既定説明
startup_timeout_sec10サーバー起動のタイムアウト（秒）
tool_timeout_sec60ツール実行のタイムアウト（秒）
enabled—false で設定を消さずに無効化
required—true で、この有効なサーバーが初期化できないとき起動を失敗させる
enabled_tools—ツールの allow list
disabled_tools—ツールの deny list。enabled_tools の後に適用される
default_tools_approval_mode—このサーバーのツールの既定の承認挙動。auto / prompt / writes / approve。writes は read-only とマークされていないツールで確認を求める
tools.<tool>.approval_mode—ツール単位の上書き

OAuth のコールバック

  • OAuth プロバイダが固定のコールバックポートを要求する場合、トップレベルの mcp_oauth_callback_port を設定する。未設定なら ephemeral ポートにバインドする
  • 特定のコールバック URL が必要な場合（リモート Devbox の ingress URL やカスタムパスなど）は mcp_oauth_callback_url を設定する。Codex はこれをベース URL として、サーバー固有のコールバック ID を末尾に付けて redirect_uri を作る。OAuth プロバイダには、ベースのホストやパスだけでなく、付加されるコールバック ID と設定したパス・クエリ・ポートを含む完全な redirect_uri を登録する
  • ローカルのコールバック URL（localhost など）はローカルインターフェースにバインドされ、非ローカルのコールバック URL は 0.0.0.0 にバインドされる
  • MCP サーバーが scopes_supported を宣言している場合、Codex は OAuth ログイン時にそのサーバー宣言のスコープを優先する。そうでなければ config.toml に設定したスコープにフォールバックする

plugin が提供する MCP サーバー

  • インストール済みの plugin は plugin マニフェストで MCP サーバーをバンドルできる。それらは plugin から起動されるため、ユーザー設定で transport コマンドを設定することはできない
  • ユーザー設定は plugins.<plugin>.mcp_servers.<server> 配下で on/off とツールポリシーを制御できる

Codex 自身を MCP サーバーとして動かす

codex mcp-server で起動し、他の MCP クライアントから接続する。tools/list に 2 つのツールが現れる。

codex — 指定したプロンプトと設定上書きで Codex セッションを実行する

プロパティ型説明
prompt（必須）string会話を開始する最初のユーザープロンプト
approval-policystringモデルが生成した shell コマンドの承認ポリシー: untrusted / on-request / never
base-instructionsstring既定の指示の代わりに使う指示
compact-promptstring会話を compact するときに使うプロンプト
configobject$CODEX_HOME/config.toml を上書きする個別の設定
cwdstringセッションの作業ディレクトリ。相対パスはサーバープロセスの現在のディレクトリから解決される
developer-instructionsstringdeveloper ロールのメッセージとして注入する指示
modelstringモデル名の上書き
sandboxstringread-only / workspace-write / danger-full-access

codex-reply — スレッド ID とプロンプトでセッションを継続する

プロパティ型説明
prompt（必須）string次のユーザープロンプト
threadId（必須）string継続するスレッドの ID
conversationIdstringdeprecated。threadId の互換エイリアス
  • threadId は tools/call レスポンスの structuredContent.threadId から取る。exec / patch の承認プロンプトの params にも threadId が含まれる
  • 最近の MCP クライアントは structuredContent があればそれだけを結果として報告することが多いが、Codex の MCP サーバーは古いクライアントのために content も返す

設定

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # enabled_tools の後に適用される
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
# plugin がバンドルする MCP サーバーのポリシーだけを制御する
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"
codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp list
codex mcp login <server-name>
codex mcp-server

関連

  • facts/codex/configuration-reference.md
  • facts/codex/config-basics.md
  • facts/codex/plugins.md
  • facts/codex/cli-reference.md
  • facts/codex/permissions.md