MCP（Model Context Protocol）是让 Codex 接入第三方工具和文档的标准协议。通过 MCP，你可以把 Figma 设计稿、Sentry 日志、GitHub、浏览器调试工具等接入 Codex，让它在一个任务里跨多个系统工作。本文覆盖 CLI 快速添加、config.toml 精细配置、OAuth 流程，以及常用服务器推荐。

Codex MCP 配置指南

MCP（Model Context Protocol）把模型和工具、上下文来源连接起来。在 Codex 里配置 MCP 后，可以让它访问第三方文档、操控浏览器、连接 Figma 设计稿，甚至直接管理 GitHub 的 PR 和 Issue。

CLI 和 IDE 扩展共享同一份 MCP 配置，配置一次就能在两端用。

---

支持的服务器类型

类型	说明	认证方式
STDIO 服务器	本地进程，通过命令启动	环境变量
Streamable HTTP 服务器	远程服务，通过 URL 访问	Bearer Token / OAuth

---

方式一：用 CLI 添加（推荐上手方式）

# 基本格式
codex mcp add <server-name> -- <启动命令>

# 示例：添加 Context7（免费的开发者文档 MCP）
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 带环境变量
codex mcp add my-server --env API_KEY=your-key -- npx some-server

# 查看所有 MCP 命令
codex mcp --help

在 TUI 里输入 /mcp 查看当前已连接的服务器。

OAuth 登录：

codex mcp login <server-name>

---

方式二：编辑 config.toml（精细配置）

配置文件路径：

• 全局：~/.codex/config.toml
• 项目级（仅受信任项目）：.codex/config.toml

在 IDE 扩展里：设置（齿轮图标）→ MCP settings → Open config.toml

STDIO 服务器（本地进程）

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

可用字段：

字段	必填	说明
command	✓	启动服务器的命令
args	-	命令参数
env	-	为服务器设置的环境变量
env_vars	-	转发给服务器的宿主机环境变量
cwd	-	服务器启动时的工作目录

HTTP 服务器（远程服务）

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

可用字段：

字段	必填	说明
url	✓	服务器地址
bearer_token_env_var	-	Bearer Token 的环境变量名
http_headers	-	固定请求头
env_http_headers	-	从环境变量里读取请求头值

通用配置项

字段	默认值	说明
startup_timeout_sec	10	服务器启动超时（秒）
tool_timeout_sec	60	工具调用超时（秒）
enabled	true	设为 false 可临时禁用而不删除
required	false	设为 true 则启动失败时 Codex 也失败
enabled_tools	-	工具白名单
disabled_tools	-	工具黑名单（在白名单之后应用）

工具白名单/黑名单示例

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot", "console"]
disabled_tools = ["screenshot"]   # 白名单后再排除
startup_timeout_sec = 20
tool_timeout_sec = 45

---

OAuth 配置

Codex 支持 OAuth 认证的 MCP 服务器。登录命令：

codex mcp login <server-name>

如果 OAuth provider 需要固定回调端口或 URL：

# 顶层配置，不在任何 [mcp_servers.*] 块里
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

• 本地回调 URL（localhost）绑定在 loopback
• 非本地 URL 绑定在 0.0.0.0，允许远程回调

---

常用 MCP 服务器推荐

服务器	功能	安装命令
Context7	最新开发者文档（React、Next.js、Supabase 等）	codex mcp add context7 -- npx -y @upstash/context7-mcp
OpenAI Docs MCP	搜索读取 OpenAI 开发者文档	参考官方文档
Figma Local	访问 Figma 设计稿	参考官方文档
Playwright	控制浏览器（自动化测试/UI 调试）	npx @playwright/mcp
Chrome DevTools	控制和检查 Chrome	参考官方文档
Sentry	访问 Sentry 错误日志	参考官方文档
GitHub	管理 GitHub PR、Issue（超出 git 范围的操作）	参考官方文档

---

常见问题

Q: 项目级 .codex/config.toml 和全局 ~/.codex/config.toml 有什么区别？

A: 项目级配置只对特定仓库生效，而且只有"受信任项目"才能用——Codex 首次打开该目录时会提示你是否信任。全局配置对所有项目生效。推荐把团队共享的 MCP 工具放到项目级，个人工具放全局。

Q: 能限制某个 MCP 服务器只开放部分工具给 Codex 用吗？

A: 可以，用 enabled_tools 做白名单，disabled_tools 做黑名单（黑名单在白名单之后应用）。这样可以避免 Codex 意外调用有副作用的工具。

Q: MCP 服务器连接失败怎么排查？

A: 先检查 startup_timeout_sec（默认只有 10 秒，本地 npm 包首次安装可能超时，可以调大到 30+）。HTTP 服务器排查时看 codex 的错误输出里是否有认证失败提示。设置 required = true 可以在服务器无法初始化时让 Codex 直接报错而非静默跳过。