接入 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 中加载。
外部工具输出被当作不可信输入处理。