Model Context Protocol

ChatGPT 桌面應用、Codex CLI 和 IDE 擴充套件支援 MCP server， 並為同一 Codex 主機共享 MCP 設定。

以下支援的伺服器功能適用於在 Codex 主機上設定的 MCP server。託管的外掛工具可能具有不同的功能。

支援的 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 桌面應用中設定

1. 開啟 設定（Settings），然後選擇 MCP server（MCP servers）。
2. 選擇 新增 server（Add server）。
3. 輸入名稱，選擇 STDIO 或 Streamable HTTP，然後提供 伺服器命令或 URL。
4. 儲存伺服器，然後選擇 重啟（Restart）。

伺服器列表會顯示哪些伺服器已啟用，以及哪些伺服器需要 OAuth。OAuth 伺服器需要登入時，選擇 身分驗證（Authenticate）。在輸入框中鍵入 /mcp 即可檢視已連線的伺服器。

在 ChatGPT 網頁版中使用由 MCP 支援的工具

在另一臺裝置上繼續使用 Work Cloud 的本機電腦存取功能進行對話，不會安裝外掛，也不會授予對已連線帳戶的存取權限。

在 Work Cloud 的本機電腦存取功能中，Agent Security 中的企業級 mcp_servers TOML 要求適用於本機執行器。雲容器繼續使用 Work Cloud 策略。本機 MCP server 和傳輸方式在雲端可能不可用；請分別檢查連線和身分驗證。

對於 Work Cloud 本機電腦存取功能中的企業鉤子：

• 企業鉤子。 如果你的工作區啟用了此功能，Work Cloud 的本機電腦存取功能便支援管理員定義的 MCP 鉤子，這些鉤子在雲端協調器（編排器）上執行，回應受支援的生命週期事件和工具事件。雲端編排不支援命令鉤子，也不支援來自本機設定或外掛的鉤子，即使工具在本機執行也是如此。
• 稽核。 在依賴這些鉤子之前，請測試回呼連線，確認它們接收的事件，並檢查失敗會如何影響任務。MCP 鉤子不提供完整的 Compliance API 稽核記錄。
• 限制： 雲端編排不支援命令鉤子，也不支援來自本機設定或外掛的鉤子，即使工具在本機執行也是如此。此功能不為個人使用者提供鉤子支援。當編排和執行都在本機進行時，現有受支援的鉤子仍可在僅限本機的 Work 和 Codex 對話中使用。管理員仍可在 Agent Security 中為這些工作流程設定受支援的託管鉤子。

有關支援範圍，請參閱鉤子和設定參考。

在託管的 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 擴充套件中設定

1. 開啟齒輪選單，然後選擇 MCP server（MCP servers）。
2. 選擇 新增 server（Add server）。
3. 輸入名稱，選擇 STDIO 或 Streamable HTTP，並提供伺服器的 命令或 URL。
4. 儲存伺服器，然後選擇 重啟擴充套件（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-client

對於機密客戶端，還需傳入 --oauth-client-secret。請從環境變數中 讀取金鑰：

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

此選項要求客戶端 ID 和金鑰均非空。Codex 會將金鑰儲存為 config.toml 中的 mcp_servers.example.oauth.client_secret。請妥善保管該檔案， 不要將其納入版本控制。

Codex 會顯示需要向提供方註冊的完整回呼 URL：

OAuth callback URL: http://127.0.0.1/callback

Codex 會將回呼與客戶端 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 設定和 授權伺服器後設資料：

回退不會修改已儲存的回呼 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 格式錯誤，或者公佈頒發者支援卻未在後設資料中提供頒發者， 也會直接導致失敗。請參閱 對使用者進行身分驗證。

在 config.toml 中設定 mcp_servers.<server-name>.scopes，以選擇伺服器的 OAuth 作用域。如需在某次登入時覆蓋這些作用域，請執行codex mcp login <name> --scopes read,write。如果兩者均未設定，Codex 會在可用時使用伺服器宣告的 OAuth 作用域。

空列表（scopes = []）仍會讓 OAuth 庫自行選擇作用域。當授權伺服器支援時，該庫還可能新增 offline_access。

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 CLI 會使用由 ChatGPT 託管、 針對該 MCP server 的後設資料文件：

https://chatgpt.com/oauth/codex/<callback_id>/client.json

Codex 會根據 MCP server URL 派生 <callback_id>，並將其包含在 迴環重定向 URI 中，例如 http://127.0.0.1:<port>/callback/<callback_id>。後設資料文件會註冊 不含埠的匹配迴環 URI。按照 RFC 8252 的要求，授權伺服器必須接受登入時選擇的 埠，同時精確匹配主機和路徑。自訂 回呼主機、路徑或查詢參數需要使用 DCR 或已設定的 OAuth 客戶端 ID。

Codex CLI 還支援一個穩定的共享 CIMD 文件：

https://chatgpt.com/oauth/codex/client.json

當授權伺服器滿足以下條件時，Codex CLI 會使用帶有共享 /callback 路徑的穩定文件：宣告 authorization_response_iss_parameter_supported: true，在後設資料中提供有效的 issuer，並在授權回應中包含匹配的 iss。 不使用頒發者繫結回應的伺服器會使用 針對特定回呼的文件。

要為單次 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 和問題單）。