Model Context Protocol
Model Context Protocol
讓 Codex 存取第三方工具和上下文
Model Context Protocol (MCP) 將模型連線到工具和上下文。使用它可以 讓 ChatGPT 或 Codex 存取第三方文件，或使其能夠 與瀏覽器或 Figma 等開發者工具互動。
ChatGPT 網頁端可以使用外掛提供、由遠端 MCP 支援的工具。安裝外掛後， Chat 和 Work 可以使用其中捆綁的連接器和遠端 MCP 工具。 開啟 Plugins 標籤頁即可瀏覽和管理可用工具。本機 Codex 客戶端也可以直接連線 MCP server 並共享其設定。
ChatGPT 桌面應用、Codex CLI 和 IDE 擴充套件支援 MCP server， 並為同一 Codex 主機共享 MCP 設定。
以下支援的伺服器功能適用於在 Codex 主機上設定的 MCP 伺服器。託管的外掛工具可能具有不同的功能。
支援的 MCP 功能
- STDIO 伺服器：作為本機程序執行的伺服器（由命令啟動）。
- 環境變數
- 可流式傳輸的 HTTP 伺服器：通過地址存取的伺服器。
- Bearer token 身份驗證
- OAuth 身份驗證，包括 Client ID Metadata Documents (CIMD) 和 Dynamic Client Registration (DCR)
- 適用於可信第一方伺服器的 ChatGPT 會話身份驗證
- 伺服器指令：Codex 會讀取初始化期間傳回的 MCP
instructions欄位，並將其作為伺服器級指南，與伺服器工具配合使用。
如果你為 Codex 建置或維護 MCP server，請使用 instructions 來說明適用於整個伺服器的跨工具工作流程、約束和速率限制。請讓前 512 個字元自成一體，以便 Codex 在決定如何使用伺服器時能夠獲得最重要的指導。
將 Codex 連線到 MCP server
Codex 將 MCP 設定與其他 Codex 設定一起儲存在 config.toml 中。預設位置為 ~/.codex/config.toml，但你也可以使用 .codex/config.toml 將 MCP server 限定到專案範圍（僅限可信專案）。
ChatGPT 桌面應用、Codex CLI 和 IDE 擴充套件共享此設定。 設定 MCP server 後，你可以在這些客戶端之間切換， 無需重新設定。
在 ChatGPT 桌面應用中設定
- 開啟 Settings，然後選擇 MCP servers。
- 選擇 Add server。
- 輸入名稱，選擇 STDIO 或 Streamable HTTP，然後提供 伺服器命令或 URL。
- 儲存伺服器，然後選擇 Restart。
伺服器列表會顯示哪些伺服器已啟用，以及哪些伺服器需要 OAuth。OAuth 伺服器需要登入時，選擇
Authenticate。在輸入框中鍵入 /mcp
即可檢視已連線的伺服器。
在 ChatGPT 網頁版中使用由 MCP 支援的工具
在託管的 ChatGPT Work 對話中，安裝外掛即可使用其 捆綁的連接器和遠端 MCP 工具。安裝後，Chat 和 Work 均可 使用這些工具。工作區管理員可以控制可用的外掛和工具。
ChatGPT 網頁版不會讀取本機 Codex 設定檔，也不會提供本機 Codex 命令選單。開啟 Plugins 標籤頁即可瀏覽和管理可用 工具。
使用 CLI 設定
新增 MCP server
codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>例如，要新增 Context7（一個面向開發者文件的免費 MCP server），可以執行以下命令：
codex mcp add context7 -- npx -y @upstash/context7-mcp其他 CLI 命令
執行 codex mcp list 可檢視已設定的伺服器。要檢視所有可用的 MCP
命令，請執行 codex mcp --help。對於支援 OAuth 的伺服器，請執行
codex mcp login <server-name>。
終端介面 (TUI)
在 codex TUI 中，使用 /mcp 可檢視當前啟用的 MCP server 。
在 IDE 擴充套件中設定
- 開啟齒輪選單，然後選擇 MCP servers。
- 選擇 Add server。
- 輸入名稱，選擇 STDIO 或 Streamable HTTP，並提供伺服器的 命令或 URL。
- 儲存伺服器，然後選擇 Restart extension。
MCP server 列表會顯示哪些伺服器已啟用，以及哪些伺服器需要 OAuth。 當 OAuth 伺服器要求登入時，請選擇 Authenticate。
使用 config.toml 設定
如需更精細的控制，請編輯 ~/.codex/config.toml 或專案範圍的
.codex/config.toml。請參閱設定參考，
其中提供了所有受支援 MCP 選項的可搜尋列表。
在設定檔中，使用 [mcp_servers.<server-name>] 表設定每個 MCP server 。
STDIO 伺服器
command（必填）：啟動伺服器的命令。args（可選）：傳遞給伺服器的參數。env（可選）：為伺服器設定的環境變數。env_vars（可選）：允許並轉發的環境變數。cwd（可選）：啟動伺服器時使用的工作目錄。experimental_environment（可選）：設為remote，以便在遠端執行器環境可用時通過該環境啟動 stdio 伺服器。
env_vars 可以包含普通變數名或帶有來源的物件：
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]字串條目和 source = "local" 從 Codex 的本機環境讀取。
source = "remote" 從遠端執行器環境讀取，並且需要
遠端 MCP stdio。
Streamable HTTP 伺服器
url（必填）：伺服器地址。auth（可選）：在已設定的 bearer token 和 授權標頭之後嘗試的身份驗證方式。使用oauth（預設值）可採用已儲存的 MCP OAuth 憑據。使用chatgpt可針對受信任的 第一方 ChatGPT 源使用當前 ChatGPT 會話，並以已儲存的 OAuth 作為回退方案。bearer_token_env_var（可選）：用於存放 bearer token 的環境變數名稱，該令牌將通過Authorization傳送。http_headers（可選）：標頭名稱到靜態值的對映。env_http_headers（可選）：標頭名稱到環境變數名稱的對映（值從環境中取得）。http_headers_helper（可選）：輸出由標頭名稱和字串值組成的 JSON 物件的本機命令， 例如{"X-Auth": "temporary-token"}。 支援從本機環境建立的 HTTP MCP 連線；不支援 stdio 伺服器或通過遠端執行環境建立的連線。
Codex 會為該連線快取輔助程式生成的標頭。同源 POST
傳回 401 或 403 後，Codex 會重新整理一次標頭，並且僅當
輔助程式傳回的值發生變化時才重試。顯式 bearer token 和 OAuth 憑據
優先於輔助程式提供的 Authorization 標頭。
如果 OAuth 403 回應報告權限範圍不足，則不會觸發
輔助程式重新整理。
如果無法解析任何憑據來源，Codex 可以在不進行
身份驗證的情況下連線伺服器。單獨執行 codex mcp login <server-name> 以啟動 MCP
OAuth 登入。
其他設定選項
startup_timeout_sec（可選）：伺服器啟動的超時時間（秒）。預設值：10。tool_timeout_sec（可選）：伺服器執行工具的超時時間（秒）。預設值：60。enabled（可選）：設為false可在不刪除伺服器的情況下將其停用。required（可選）：設為true，可在這個已啟用的伺服器無法初始化時讓啟動失敗。enabled_tools（可選）：工具允許列表。disabled_tools（可選）：工具拒絕列表（在enabled_tools之後應用）。default_tools_approval_mode（可選）：此伺服器所提供工具的預設核准行為。 支援的值包括auto、prompt、writes和approve。writes模式會對未標記為只讀的工具發起核准請求。tools.<tool>.approval_mode（可選）：針對單個工具覆蓋核准行為。tools.<tool>.output_token_limit（可選）：單次工具輸出的正數 token 預算， 不包括標準的 20% 序列化餘量。它會覆蓋模型為該工具設定的 預設輸出截斷預算。
頂層 mcp_optional_startup_grace_ms 設定用於控制 Codex
在建置初始工具目錄時等待可選 MCP server 的時長。
預設值為 1000 毫秒。將其設為 0，即可改為等待每臺伺服器各自的
startup_timeout_sec。必需伺服器仍使用各自的啟動
超時時間。
OAuth 客戶端註冊和回撥
當授權伺服器要求使用預註冊的 OAuth 客戶端時，請在新增 MCP server 時提供 其客戶端 ID：
codex mcp add example --url https://mcp.example.com --oauth-client-id my-clientCodex 會顯示需要向提供方註冊的完整回撥 URL：
OAuth callback URL: http://127.0.0.1/callbackCodex 會將回調與客戶端 ID 一並儲存在 config.toml 中，供後續
登入使用：
[mcp_servers.example]
url = "https://mcp.example.com"
[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"僅當授權伺服器公佈
authorization_response_iss_parameter_supported: true 並在後設資料中提供
issuer 時，新新增的預註冊客戶端才會使用穩定的回撥。如果未公佈頒發者支援，Codex 會附加伺服器專用的
回撥 ID，例如 http://127.0.0.1/callback/XuuuHAzzHOni。未儲存回撥的現有客戶端
將繼續使用其包含特定回撥 ID 的重定向。
登入期間，回撥選擇取決於 OAuth 設定和 授權伺服器後設資料：
| OAuth 設定 | 頒發者支援 | 使用的回撥 |
|---|---|---|
有 callback_url，無 client_id |
支援 | 使用設定的回撥進行客戶端註冊。 |
有 callback_url，無 client_id |
不支援 | 使用設定的回撥進行客戶端註冊，並在末尾附加伺服器專用的回撥 ID。 |
client_id 和 callback_url |
支援 | 複用設定的回撥；授權回應必須包含匹配的 iss。 |
client_id 和以正確回撥 ID 結尾的 callback_url |
不支援 | 原樣複用設定的回撥。 |
client_id 和缺少正確回撥 ID 的 callback_url |
不支援 | 忽略設定的回撥。Codex 使用 mcp_oauth_callback_url；若未設定，則使用 http://127.0.0.1/callback，並在末尾附加回調 ID。 |
有 client_id，但未設定 callback_url |
支援或不支援 | Codex 使用全域或預設回撥，並在末尾附加伺服器專用的回撥 ID。 |
回退不會修改已儲存的回撥 URL。Codex 根據 MCP server URL（包括其路徑和查詢字串） 派生回撥 ID。自動登入和顯式登入 採用相同的選擇規則。
需要自訂回撥路徑或遠端
Devbox 入口 URL 時，請設定 mcp_oauth_callback_url。當提供方支援頒發者識別時，新新增的預註冊客戶端會原樣使用該 URL。
否則，它們會使用設定的 URL，並在末尾附加伺服器專用的回撥 ID。請始終註冊
codex mcp add 顯示的確切回撥。
對於不含埠的 http://127.0.0.1 回撥，Codex 會從其顯示和儲存的
URL 中省略監聽埠，然後在授權期間插入當前使用的監聽埠。
此替換不適用於 localhost、IPv6 主機、
HTTPS URL 或已包含埠的回撥。根據
RFC 8252 第 7.3 節，授權伺服器必須接受可變的環回埠。
設定 mcp_oauth_callback_port 可選擇固定的全域監聽埠，也可以設定
mcp_servers.<server-name>.oauth.callback_port 為單個伺服器覆蓋該埠。
回撥 URL 中的顯式埠不會設定監聽器。對於
直接環回回調，請使用不含埠的 http://127.0.0.1，或者為回撥 URL 和監聽器設定相同的
顯式埠。代理回撥可以有意使用與本機監聽器
埠不同的外部 URL 埠。本機回撥 URL 繫結到本機介面；非本機回撥 URL
繫結到 0.0.0.0。
Codex 會在交換授權碼之前驗證傳回的所有 iss。如果
iss 不匹配，始終會拒絕該回應。公佈頒發者支援後，
缺少 iss 也會導致回應被拒絕。上述兩種失敗均不會交換授權碼，也不會
回退到其他回撥。回撥 URL 格式錯誤，或者公佈頒發者支援卻未在後設資料中提供頒發者，
也仍屬於不可恢復的失敗。請參閱
對使用者進行身份驗證。
如果 MCP server 公佈 scopes_supported，Codex 會在 OAuth 登入期間優先使用這些
由伺服器公佈的作用域。否則，Codex 將回退到
config.toml 中設定的作用域。
OAuth 客戶端註冊
Codex 支援 OAuth Client ID Metadata Documents (CIMD)
和 Dynamic Client Registration (DCR)。預設情況下，當授權伺服器通告
client_id_metadata_document_supported: true、在
token_endpoint_auth_methods_supported 中包含 none，且回撥使用受支援的
環回 URL 時，Codex 會自動選擇 CIMD。否則，Codex 會在 DCR 可用時使用 DCR。已設定的 OAuth 客戶端
ID 始終具有優先權，並會跳過客戶端註冊。
對於 CIMD，Codex 會使用專用於該 MCP 伺服器、由 ChatGPT 託管的後設資料文件：
https://chatgpt.com/oauth/codex/<callback_id>/client.jsonCodex 會根據 MCP server URL 派生 <callback_id>，並將其包含在
環回重定向 URI 中，例如
http://127.0.0.1:<port>/callback/<callback_id>。後設資料文件會註冊
不含埠的匹配環回 URI。按照
RFC 8252 的要求，授權伺服器必須接受登入時選擇的
埠，同時精確匹配主機和路徑。自訂
回撥主機、路徑或查詢參數需要使用 DCR 或已設定的 OAuth
客戶端 ID。
對穩定共享 CIMD 文件的支援正在開發中，即將推出：
https://chatgpt.com/oauth/codex/client.json當授權伺服器通告
authorization_response_iss_parameter_supported: true、在其後設資料中提供有效的
issuer，並且授權回應中包含匹配的 iss 時，Codex 將使用帶有共享 /callback 路徑的穩定文件。
未提供與頒發者繫結的回應的伺服器將繼續使用
回撥專用文件。
要為單次 CLI 登入選擇註冊方式，請使用
--oauth-client-registration：
codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr預設值為 auto。註冊方式選擇僅適用於當前登入，
不會儲存在 config.toml 中。
config.toml 範例
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]
[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"[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"] # applied after 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"
output_token_limit = 30000外掛提供的 MCP server
已安裝的外掛可以在其外掛清單中捆綁 MCP server 。這些
伺服器從外掛啟動，因此使用者設定無需設定其
傳輸命令。使用者設定仍可在 plugins.<plugin>.mcp_servers.<server> 下控制啟用/停用狀態和工具策略。
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]
[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"外掛提供的 HTTP MCP server 也可以在 .mcp.json 中宣告 OAuth 設定。
外掛清單使用駝峰式欄位名 clientId、callbackUrl 和
callbackPort：
{
"mcpServers": {
"sample": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"clientId": "my-pre-registered-client",
"callbackUrl": "http://127.0.0.1/callback/registered"
}
}
}
}外掛提供的 MCP server 與其他
MCP server 採用相同的回撥選擇規則。如果外掛提供了 clientId，其提供方不支援
與頒發者繫結的回撥，並且 callbackUrl 缺少伺服器專用的回撥
ID，Codex 會在登入時忽略該 URL，改用 mcp_oauth_callback_url；若未設定，
則使用 http://127.0.0.1/callback，並在末尾附加回調 ID。
設定的 callbackUrl 保持不變。
外掛的 oauth.callbackPort 會覆蓋全域
mcp_oauth_callback_port；如果兩者均未設定，Codex 會選擇臨時埠。
嵌入 callbackUrl 的埠不會選擇監聽埠。對於使用固定埠的
直接環回回調，請將這兩個值設定為一致：
{
"callbackUrl": "http://127.0.0.1:4321/callback/registered",
"callbackPort": 4321
}對於遠端入口或其他代理，如果代理將請求轉發到設定的 監聽器，回撥 URL 埠可以有意與本機監聽器埠不同。
實用 MCP server 範例
MCP server 列表仍在不斷增長。以下是一些常見範例：
- OpenAI Docs MCP：搜尋和閱讀 OpenAI 開發者文件。
- Context7：連線最新的開發者文件。
- Figma Local 和 Remote：存取你的 Figma 設計。
- Playwright：使用 Playwright 控制和檢查瀏覽器。
- Chrome Developer Tools：控制和檢查 Chrome。
- Sentry：存取 Sentry 日誌。
- GitHub：管理
git所支援範圍之外的 GitHub 功能（例如 PR 和問題單）。