CodexのMCP設定ガイド｜config.toml・CLI・Desktop・IDEを安全に分ける

先に結論：Codex MCPは、設定面と権限面を分けると事故を減らせる

OpenAIの現行MCP Docsでは、ChatGPT desktop app、Codex CLI、IDE extensionが、同じCodex hostのMCP設定を共有すると説明されています。つまり、CLIで追加したserverがdesktopやIDEでも見える可能性があります。便利な反面、個人用の強いtoolや認証済みserverを、別の作業面にもそのまま持ち込む境界が生まれます。

一方、ChatGPT webはlocal Codexの設定ファイルを読まず、WorkのPluginsを入口にremote MCP-backed toolsを使います。Codexのlocal configとChatGPT webのpluginを同じMCP設定だと決めつけず、host、設定ファイル、認証、tool policyを最初に分けて記録します。

Codexが対応するMCP serverの範囲

config.tomlの範囲：user設定とtrusted project設定

CodexのMCP設定はconfig.tomlに置きます。公式Docsでは、通常のuser設定を~/.codex/config.toml、project単位の設定を.codex/config.tomlとして説明し、project設定はtrusted projectsに限定しています。どちらを使うかは、個人の全repoで使うserverか、そのrepoだけで使うserverかで決めます。

project configをversion管理する場合でも、tokenやsecret実値をファイルへ入れません。共有するのはserverの役割、commandや接続先の抽象的な定義、必要なら環境変数名までにし、実値はhost側の安全なcredential経路へ分けます。

Codex configの優先順位：CLI・project・profileを分ける

現行のConfig basicsでは、CodexはCLI flagと`--config` overrideを最優先に、projectの`.codex/config.toml`、`--profile`で選ぶprofile、user config、system config、built-in defaultの順で値を解決します。project configはproject rootからcurrent working directoryへ積み重なり、closest winsですが、trusted projectでだけ読み込まれます。MCP serverが見えないときは、ファイルがあるかだけでなく、どのlayerが最後に値を決めたかを確認します。

• project configへproviderやauthを強制する前提を置かず、どの設定layerが値を決めたかを`--profile`、CLI flag、user configとあわせて確認する。
• `required = true`は便利なhealth checkではなく、serverが初期化できないとstartup / resume自体を止める設定なので、復旧手順を持つserverだけで使う。
• MCPのtool allowlistとapproval modeは、project configがtrustedかどうか、user-level serverが残っていないかとは別の軸として点検する。

• 全hostの設定を書き換える前に、1回だけの検証は専用flagまたは`--config`で行い、TOMLのquoteとdot notationの解釈を確認する。
• 旧profile tableを残したまま新しいprofile fileを追加せず、Codex version、profile file、`--profile`指定、実効値を一緒に記録する。
• `CODEX_HOME`は設定ファイルだけでなくauth、履歴、ログ、cacheを含み得るため、MCPのcredentialや会話をGit・CI artifact・共有repoへ持ち込まない。

CLI・TUI・desktop・IDEの設定導線

• desktop appではSettingsのMCP serversからserver名、STDIOまたはStreamable HTTP、commandまたはURLを入力し、保存後にRestartする
• Codex CLIではcodex mcp add、codex mcp list、codex mcp loginを使い、利用中のserverはTUIの/mcpで確認する
• IDE extensionではgear menuから追加し、extensionをRestartして有効serverとOAuth要否を確認する
• config.tomlを直接編集するときは、userとprojectのどちらを変更したか、他のhostへ共有されるかを差分で確認する
• ChatGPT webではPluginsがremote toolの入口なので、local Codex configへ追加しただけで使えると期待しない

codex mcp list
codex mcp login <server-name>
codex mcp --help

CLIのhelpや画面にserverが出ても、起動成功・認証成功・tool call成功・安全な結果は同じではありません。まずlistで構成、loginで認証の入口、TUIやhost画面でenabledとapprovalを分け、読み取り用の小さなtoolから確認します。

STDIOの設定：command・cwd・envを最小にする

STDIO serverはlocal processとして起動するため、PATH、command、args、cwd、環境変数、終了時のログを確認します。projectを開いたshellとCodex hostが使うshellが違う場合、同じcommandでも起動結果が変わることがあります。commandの全権限を最初から許可せず、読み取りtoolとtest用repoで小さく確認します。

[mcp_servers.readonly_server]
command = "YOUR_MCP_SERVER_COMMAND"
args = ["--mode", "readonly"]
env_vars = ["MCP_TOKEN"]
cwd = "YOUR_PROJECT_DIRECTORY"
enabled_tools = ["search", "read"]
disabled_tools = ["write", "delete"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true

• commandとargsは実行されるprocessの範囲として確認し、未確認のwrapperやscriptを足さない
• env_varsは転送を許す環境変数名のallowlistとして扱い、値やtokenをrepoへ書かない
• cwdは対象repoやsandboxの範囲を狭くし、全ユーザーフォルダを作業範囲にしない
• startup timeoutとtool timeoutを分け、hung processや長い外部処理を無制限に待たない
• enabled_toolsとdisabled_toolsを両方使う場合、disabled_toolsがenabled_toolsの後に適用される前提を確認する

Streamable HTTPの設定：接続先・Bearer・OAuthを分ける

Streamable HTTP serverでは、接続先のorigin、認証方式、header、timeout、scopeを別々に管理します。Bearer tokenを環境変数から送る設定と、Codexが保存したOAuth credentialを使う設定は同じではありません。接続できないときに認証を全体的に緩めたり、toolを全部enableしたりせず、まずserver、issuer、scope、対象resourceを確認します。

tool policy：enabled_tools・disabled_tools・approval modeの順番

Codex Docsでは、enabled_toolsがallowlist、disabled_toolsがdenylistとして案内され、disabled_toolsはenabled_toolsの後に適用されます。さらにserver全体のdefault_tools_approval_modeと、tool単位のapproval_modeを設定できます。名前の設定だけで安全になるのではなく、最終的に実行可能なtool集合と承認挙動を表にしてから使います。

server instructions：最初の512文字を運用境界として読む

CodexはMCP serverの初期化時に返されるinstructionsを、server-wide guidanceとしてtoolと一緒に読みます。公式Docsでは、Codexがtoolを選ぶときに重要な情報が届くよう、最初の512文字をself-containedにするようserver作者へ案内しています。client側では、instructionsを便利な説明文としてだけでなく、cross-tool workflow、制約、rate limit、禁止事項の候補として読み、repoのAGENTS.mdや人間の権限設定と矛盾しないか確認します。

OAuth loginとcredential：Codex設定に実値を置かない

OAuth対応serverでは、Codex CLIのcodex mcp loginが認証の入口になります。Bearer tokenを使う場合も、Docsにあるbearer_token_env_varのように環境変数名と実値を分けます。OAuthのissuer、resource、scope、redirect、token保存は接続先の仕様に従い、MCP OAuth記事で確認するCIMD・issuer・PKCEなどのprotocol境界と、Codex hostのlogin画面を混同しません。

• config.toml、project config、Git差分、CI artifactへaccess token、client secret、refresh tokenを残さない
• serverごとにscopeとcredentialを分け、同じtokenを別のauthorization serverや環境へ流用しない
• login後はserver list、enabled状態、tool policy、auth済みのhostを確認する
• 認証失敗とtool権限不足を分け、全scope付与やapproval無効化を解決策にしない
• credentialを消す、再認証する、接続を止める手順を人間が実行できるようにする

Plugin-provided MCP serversはuser configと別管理

OpenAI Docsでは、installed PluginがMCP serverをbundleする場合、そのserverのtransport commandはpluginから起動され、user configで起動commandを設定するのではないと説明されています。一方で、`plugins.<plugin>.mcp_servers.<server>`の下で、plugin配下のserverについてenabled状態やtool policyを設定できます。Pluginを入れたこと、MCP serverが起動したこと、toolを許可したことを三つに分けて確認します。

MCPの実行環境：local STDIO・remote STDIO・Streamable HTTP

• `env_vars`の文字列はlocal environment、`source = "remote"`はremote executor environmentという境界を確認し、tokenをlocalからremoteへ暗黙に転送しない。
• `env_http_headers`はheader名と環境変数名を分ける設定なので、static `http_headers`へsecret実値を置かない。
• credential sourceが解決しない場合に認証なしで接続できるserverもあり得るため、接続成功を認証成功と扱わず、server側の要求を確認する。
• `enabled = false`はserverを削除せず無効化する設定、`required = true`は起動できないとstartup failureにする設定として、停止と必須化を分ける。

OAuth callbackはbase URLではなく、実際のredirect URIを登録する

MCP OAuthで固定portが必要な場合は`mcp_oauth_callback_port`、remote Devbox ingressやcustom pathが必要な場合は`mcp_oauth_callback_url`を設定できます。Docsでは、Codexがbase callback URLへserver固有のcallback IDを追加してredirect_uriを作るため、OAuth providerへ登録するのはbase hostだけでなく、実際に生成される完全なredirect URIだと案内しています。callbackのport、path、query、server識別子が変われば認証の戻り先も変わるため、設定変更後に登録値とlocal / remote bindingを再確認します。

OAuth serverが`scopes_supported`を広告する場合、Codexはlogin時にserver提示scopeを優先し、そうでなければconfig.tomlのscopeへfallbackします。scopeを全許可にしてcallbackエラーを回避するのではなく、serverのscope、resource、redirect URI、credential storageを一つずつ確認します。

Codex MCPのトラブル切り分け順

導入前の最小チェックリスト

• ChatGPT desktop app、Codex CLI、IDE extension、ChatGPT webのどのhostで使うか記録した
• user configとtrusted project configのどちらに置くか、共有範囲を決めた
• STDIOかStreamable HTTPか、command・cwd・url・auth・timeoutを分けて確認した
• enabled_toolsとdisabled_toolsの最終集合を確認し、read-onlyから始めた
• default approval modeとtool単位のoverrideを確認し、write・delete・deployをpromptまたは除外にした
• token、secret、refresh tokenをconfig、repo、ログ、artifactへ残していない
• server instructionsの制約、rate limit、cross-tool workflowをAGENTS.mdや人間のレビューと照合した
• codex mcp list、login、TUIの/mcp、hostのRestart後に接続状態とtool数を確認した
• 失敗時にserverをdisable、credentialをrevoke、差分を戻す手順がある

まとめ：Codex MCPは、接続より先に共有範囲とtool policyを決める

CodexのMCPは、ChatGPT desktop app、Codex CLI、IDE extensionで設定を共有できる一方、ChatGPT webのWork Pluginsとは別の面があります。導入時は、config.tomlの範囲、trusted project、STDIO／Streamable HTTP、auth、server instructions、enabled／disabled tools、approval mode、OAuth credentialを分けて確認します。read-only・最小tool・prompt承認から始め、hostをまたいだ表示、差分、ログ、revoke手順まで確認できてから、外部side effectのあるtoolへ広げてください。

Codex CLIのMCP commandは、登録・認証・診断を分ける

CLI commandが表示されたことを成功・安全と扱わない

• `codex mcp list`は登録されたserverの確認、`get`は設定entryの確認、`login`はOAuth認証の入口であり、serverの起動成功、tool callの成功、外部side effectの安全性をそれぞれ証明しない。
• `codex mcp login` / `logout`はOAuth対応のStreamable HTTP serverに限る。stdio serverのcommand起動やBearer tokenの環境変数設定を、OAuth loginだけで完了したとは扱わない。
• `--env`、`--bearer-token-env-var`、configの`env_vars`は環境変数名と実値を分けるための入口であり、secretの表示・記録・子processへの継承を無条件に安全にする機能ではない。
• `--strict-config`で未知のkeyを止めても、既知の設定が意図したscope・approval・networkを持つとは限らない。Codex version、profile、project trust、MCPの最終tool集合を別に確認する。
• Developer commandsのmaturity表示でStableとExperimentalを分ける。app-server、execpolicy、debug系などExperimental commandを、通常のMCP接続確認や本番運用の前提にしない。

ChatGPT webのcomposerで`/`を入力して出るslash commandは、ChatGPT desktop appやCodex CLIのcommand setを公開するものではありません。`/mcp`などのTUI操作、`codex mcp`、desktopのSettings、WorkのPluginsは別の入口として扱い、どのhostがどのconfigとcredentialを読んでいるかを先に記録します。