接入 MCP 工具和上下文

Model Context Protocol（MCP）把 Codex 連線到外部工具和上下文。你可以用 MCP 讀第三方文件，也可以操作開發工具，例如瀏覽器、Figma、GitHub 或 Sentry。

MCP 不只是“多一點資料”。帶寫許可權或外部動作的 MCP server 會擴大風險邊界，必須先看 token、工具白名單、審批和日誌。

MCP

官方 Codex MCP 配置說明。

MCP tools guide

理解 tool、resource、prompt 和許可權差異。

Config basics

MCP 配置跟隨 config.toml 載入層和專案 trust 邊界。

兩類 server

flowchart LR
    Codex["Codex"] --> Stdio["STDIO server"]
    Codex --> HTTP["Streamable HTTP server"]
    Stdio --> Local["local command"]
    HTTP --> Remote["remote service"]

STDIO servers 作為本地程序執行，由命令啟動。適合本機文件、瀏覽器、開發工具或需要本地環境的整合。

Streamable HTTP servers 透過地址訪問，適合遠端託管系統。它們可以使用 bearer token，也可以走 OAuth。伺服器支援 OAuth 時，用：

codex mcp login <server-name>

配置位置

Codex 把 MCP 配置和其他配置一起放在 config.toml：

~/.codex/config.toml

專案級配置可以放在：

.codex/config.toml

專案級配置只會在 trusted projects 中載入。CLI 和 IDE extension 共享配置，配好後不用重複設定。

用 CLI 管理

新增 STDIO server：

codex mcp add <server-name> --env VAR=VALUE -- <stdio server-command>

示例：

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

檢視命令：

codex mcp --help

TUI 中用 /mcp 檢視 active MCP servers。

用 config.toml 管理

每個 server 使用 [mcp_servers.<server-name>] table。

STDIO server 常見欄位：

command
args
env
env_vars
cwd
experimental_environment

HTTP server 常見欄位：

url
bearer_token_env_var
http_headers
env_http_headers

通用控制項：

startup_timeout_sec
tool_timeout_sec
enabled
required
enabled_tools
disabled_tools

OAuth callback 需要固定埠或 URL 時，再配置 mcp_oauth_callback_port 和 mcp_oauth_callback_url。

最小樣例

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

HTTP server：

[mcp_servers.docs]
url = "https://example.com/mcp"
bearer_token_env_var = "DOCS_MCP_TOKEN"
enabled_tools = ["search", "read"]

不要把 token 直接寫進配置。用環境變數、secret store 或系統憑據管理。

選擇 MCP server

常見選擇：

OpenAI Docs MCP：搜尋和閱讀 OpenAI developer docs。
Context7：連線開發者文件。
Figma：訪問 Figma designs。
Playwright：控制和檢查瀏覽器。
Chrome Developer Tools：檢查 Chrome。
Sentry：訪問 production error context。
GitHub：管理 pull requests、issues 和 review data。

優先接只讀工具。寫入型工具必須先定義審批、日誌和回復方式。

驗收清單

server 能啟動或認證成功。
token 不在儲存庫、日誌和 prompt 中出現。
enabled_tools / disabled_tools 收窄到任務需要。
timeout 合理，失敗時能定位是啟動、認證還是工具呼叫問題。
專案級 MCP 只在 trusted project 中載入。
外部工具輸出被當作不可信輸入處理。