Codex 怎麼配置 MCP：codex mcp add 命令、config.toml 寫法與常見問題

本文根據 OpenAI 官方 Codex 文檔（原 developers.openai.com/codex，現已遷到 learn.chatgpt.com/docs）的《Model Context Protocol》《Config basics》《Configuration Reference》和命令參考整理，資料核對於 2026-10-07。示例裏的第三方伺服器（Context7、Figma 等）是官方文檔自己舉的例子，使用前請看各自的說明。

適用於誰

• 想讓 Codex 查最新的開發文檔、操作瀏覽器、讀 Figma 設計稿、看 Sentry 日誌的人；
• 搜「codex mcp 配置」「codex mcp add」「config.toml 怎麼寫」的 CLI / IDE / 桌面 App 用戶；
• 配好了 MCP 但 Codex 裏看不到工具、或者啟動報超時的人。

還沒裝 Codex 的先看 Codex 入門教學。

結論先說

1. MCP（Model Context Protocol） 是把第三方工具和上下文接給模型的協議。本地的 Codex（桌面 App、CLI、IDE 插件）可以直接連 MCP 伺服器；ChatGPT 網頁版則通過安裝插件（Plugins）使用遠程 MCP 工具，不讀本地配置文件。
2. 配置只寫一處：都存在 config.toml 裏，預設是 ~/.codex/config.toml（Windows 是 %USERPROFILE%\.codex\config.toml）；桌面 App、CLI、IDE 插件共用這份配置，配一次三處都能用。
3. 最快的方法是命令行：codex mcp add 名字 -- 啟動命令（本地進程型）或 codex mcp add 名字 --url 地址（HTTP 型）。
4. 配完用 codex mcp list 查看，會話裏輸入 /mcp 確認工具已加載。
5. MCP 伺服器不是越多越好：每個伺服器都會往消息裏加上下文、多耗額度，不用的設成 enabled = false。

兩類 MCP 伺服器

另外，Codex 會讀取 MCP 伺服器初始化時返回的 instructions 字段，作為使用這個伺服器的整體指引。

方法一：用 codex mcp 命令添加

添加本地（STDIO）伺服器，-- 後面是啟動命令，可以用 --env 傳環境變量：

bash
codex mcp add <名字> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <啟動命令>

官方文檔舉的例子是 Context7（查開發文檔的免費 MCP 伺服器）：

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

添加 HTTP 伺服器：

bash
codex mcp add example --url https://mcp.example.com

如果伺服器用 Bearer Token，可以加 --bearer-token-env-var 環境變量名，Codex 會把這個環境變量的值放進 Authorization 頭；需要預先註冊 OAuth 客戶端的，加 --oauth-client-id 客戶端ID，Codex 會顯示要在服務商那邊登記的回調地址。

其他常用子命令（來自官方命令參考）：

方法二：在桌面 App 或 IDE 插件裏添加

• ChatGPT 桌面 App：Settings（設定）→ MCP servers → Add server，填名字，選 STDIO 或 Streamable HTTP，填啟動命令或網址，儲存後點 Restart。需要登入的伺服器會標出來，點 Authenticate 完成授權。輸入框裏打 /mcp 可以看到已連接的伺服器。
• IDE 插件：齒輪選單 → MCP servers → Add server，步驟同上，儲存後點 Restart extension。

兩處添加的伺服器都寫進同一份 config.toml，換客戶端不用重配。

方法三：直接編輯 config.toml

想精細控制時直接改文件。每個伺服器一個 [mcp_servers.<名字>] 表。也可以在項目裏放 .codex/config.toml，只對這個項目生效——但只有你信任（trust）的項目才會加載項目級配置。IDE 插件裏可以通過齒輪 → Codex Settings → Open config.toml 打開。

STDIO 伺服器的寫法

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"         # 直接寫給這個伺服器的變量

可選字段還有 cwd（啟動目錄）。

HTTP 伺服器的寫法

toml
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

可選字段：env_http_headers（從環境變量取請求頭）、auth（預設 oauth 使用已儲存的 OAuth 憑據）、scopes（OAuth 申請的權限範圍）。如果一個憑據都沒解析到，Codex 會嘗試不帶認證連接；要登入請單獨運行 codex mcp login <名字>。

建議：Token 一律通過環境變量引用（bearer_token_env_var、env_vars），不要把密鑰明文寫進 config.toml，尤其是會提交到 Git 的項目級配置。

通用選項：超時、開關、工具白名單與審批

toml
[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"
output_token_limit = 30000

另外，頂層的 mcp_optional_startup_grace_ms 控制建立工具列表時等待「非必需」伺服器的時間，預設 1000 毫秒。

官方安全說明裏還提到：聲明瞭「破壞性」標註的 MCP 工具調用總是需要審批（除非工具同時聲明瞭只讀）。審批和沙箱怎麼搭配，見 Codex 權限與沙箱設定。

官方文檔列出的常用 MCP 伺服器

OpenAI Docs MCP（查 OpenAI 開發者文檔）、Context7（最新開發文檔）、Figma（本地 / 遠程兩種）、Playwright（控制瀏覽器）、Chrome DevTools、Sentry（看日誌）、GitHub（管理 PR 和 Issue）。安裝插件時，插件也可以自帶 MCP 伺服器，這類伺服器的開關和工具策略寫在 plugins.<插件>.mcp_servers.<伺服器> 下。

常見問題

Q：配好了，會話裏卻看不到工具？

依次檢查：codex mcp list 裏有沒有它、enabled 是不是 false；項目級 .codex/config.toml 只在信任的項目裏加載；改完配置後重啟會話（桌面 App 點 Restart，IDE 點 Restart extension）；會話裏輸入 /mcp verbose 看伺服器詳情。

Q：啟動超時怎麼辦？

STDIO 伺服器第一次用 npx 之類命令啟動時可能要先下載依賴，比預設的 10 秒久。可以把 startup_timeout_sec 調大，或者先在終端裏單獨運行一次啟動命令，確認它本身能正常運行、沒有報錯。

Q：需要 OAuth 的伺服器怎麼登入？

運行 codex mcp login <名字>，在瀏覽器完成授權；桌面 App / IDE 裏點 Authenticate。服務商要求預先登記回調地址的，以 codex mcp add 時顯示的地址為準，原樣登記。

Q：codex mcp-server 命令沒了？

是的。官方已移除 codex mcp-server 命令和獨立的 codex-mcp-server 程序，也就是「把 Codex 當成 MCP 伺服器給別的程序用」這條路不再支持，集成方需要改用 Codex app server（實驗性，使用自己的 JSON-RPC 協議）。這和「讓 Codex 連接外部 MCP 伺服器」是兩回事，後者繼續支持，用 codex mcp 管理。

Q：ChatGPT 網頁版能用我在 config.toml 裏配的 MCP 嗎？

不能。網頁版不讀本地 Codex 配置，要在 Plugins 裏安裝帶 MCP 工具的插件，詳見 ChatGPT 插件與連接應用。

Q：MCP 會多耗額度嗎？

會。官方定價頁的省額度建議裏專門寫了「限制 MCP 伺服器數量」，不用時就停用，見 Codex 額度與使用限制。

參考資料

• 官方文檔：Model Context Protocol（Codex）— https://learn.chatgpt.com/docs/extend/mcp
• 官方文檔：Config basics — https://learn.chatgpt.com/docs/config-file/config-basic
• 官方文檔：Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
• 官方文檔：命令行參考（codex mcp 子命令）— https://learn.chatgpt.com/docs/developer-commands
• 官方文檔：Codex MCP server removal — https://learn.chatgpt.com/docs/mcp-server
• Codex 官方定價頁（省額度建議）— https://learn.chatgpt.com/docs/pricing
• openai/codex 官方倉庫 — https://github.com/openai/codex