18. MCP集成

本节目标：理解 MCP 协议的作用，学会在 config.toml 中配置 STDIO 和 Streamable HTTP 两种 MCP 服务器，掌握工具审批策略和常用 MCP 服务器的接入。

MCP 是什么

MCP（Model Context Protocol，模型上下文协议）是一个开放协议，让 AI 模型能和外部工具、服务做标准化交互。

打个比方：Codex 本身只会读写本地文件、跑终端命令。但你想让它读 Figma 设计稿、查 Sentry 错误日志、操作 GitHub PR—这些它原生做不到。MCP 就是那座桥，让 Codex 连上这些外部服务，获得新能力。

ChatGPT 桌面应用、Codex CLI 和 IDE 扩展都支持 MCP 服务器，而且共享同一份配置。你在 config.toml 里配好一次，三个客户端都能用，不用重复设置。

两种传输方式

MCP 服务器有两种传输方式，对应两种部署形态：

传输方式	怎么跑	典型场景
STDIO	以本地进程运行，通过命令启动	文件系统、本地数据库、GitHub CLI
Streamable HTTP	通过网络地址访问	Figma 远程服务、Sentry API

Note

Codex 还支持 Server instructions—MCP 服务器初始化时返回的 instructions 字段会被 Codex 读取，作为 server 级指导。如果你自己构建 MCP 服务器，把跨工具的工作流、约束和速率限制写在 instructions 里，前 512 个字符放最重要的信息。

在 config.toml 中配置

MCP 配置写在 ~/.codex/config.toml（用户级）或项目级 .codex/config.toml 里。每个 MCP 服务器用 [mcp_servers.<server-name>] 表来配。

STDIO 服务器

STDIO 服务器以本地进程运行。你需要指定启动命令和参数：

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

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

各字段说明：

字段	必填	说明
`command`	是	启动 server 的命令
`args`	否	传给 server 的参数
`env`	否	为 server 设置的环境变量
`env_vars`	否	允许并转发的环境变量
`cwd`	否	启动 server 时的工作目录

Streamable HTTP 服务器

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`	是	server 地址
`bearer_token_env_var`	否	读取 bearer token 的环境变量名
`http_headers`	否	静态 header 名和值的映射
`env_http_headers`	否	header 名与环境变量名的映射，值从环境读取

通用配置项

不管是 STDIO 还是 HTTP，都支持以下配置：

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true
required = false

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

配置项	默认值	说明
`startup_timeout_sec`	`10`	server 启动超时（秒）
`tool_timeout_sec`	`60`	工具调用超时（秒）
`enabled`	`true`	设为 `false` 可禁用而不删除配置
`required`	`false`	设为 `true` 后，server 启动失败则 Codex 也启动失败
`enabled_tools`	全部	工具允许列表
`disabled_tools`	空	工具拒绝列表（在 `enabled_tools` 之后应用）
`default_tools_approval_mode`	无	默认审批行为：`auto`/`prompt`/`writes`/`approve`

Tip

disabled_tools 在 enabled_tools 之后应用。所以即使你把某个工具加进了 enabled_tools，再在 disabled_tools 里加上它，它还是会被禁用。这个设计让你能先开一个大范围白名单，再精确排除几个。

OAuth 认证

需要登录的 MCP 服务器走 OAuth 认证。先用命令行登录：

codex mcp login <server-name>

这会启动 OAuth 登录流程。如果 OAuth 提供商要求固定 callback 端口，在 config.toml 顶层设置：

mcp_oauth_callback_port = 5555

auth 字段控制认证方式：

oauth（默认）：读取已保存的 MCP OAuth 凭据
chatgpt：让可信的第一方 ChatGPT 会话认证，OAuth 作为回退

Note

如果没有可用凭据，Codex 仍会尝试无认证连接。所以不是所有 MCP 服务器都需要 OAuth—公开的文档服务可能不需要认证就能用。

在桌面 App 中配置

除了编辑 config.toml，也可以在 ChatGPT 桌面 App 的界面里配：

打开 Settings（设置）
选择 MCP servers
点 Add server
输入名称，选 STDIO 或 Streamable HTTP
填写 server 的命令或 URL
保存后点 Restart

在输入框里输入 /mcp 可以查看已连接的 MCP 服务器状态。

工具审批策略

MCP 服务器暴露的工具，默认每次调用前都会问你。你可以按需调整审批策略：

# 整个 server 的默认审批行为
default_tools_approval_mode = "prompt"

# 按工具单独覆盖
[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"

[mcp_servers.chrome_devtools.tools.screenshot]
approval_mode = "prompt"

审批模式	行为
`auto`	自动执行，不问
`prompt`	每次都问你
`writes`	只读工具自动执行，写操作才问你
`approve`	自动批准

Warning

approve 意味着自动放行，不给你看就执行了。只对你完全信任的工具用这个模式。一般推荐 prompt 或 writes，在安全和效率之间取平衡。

常用 MCP 服务器

MCP 生态正在快速增长，以下是几个常用的：

MCP 服务器	用途	传输方式
Context7	连接最新开发者文档	STDIO
Figma	访问 Figma 设计稿	HTTP
Playwright	通过 Playwright 控制浏览器	STDIO
Chrome DevTools	控制和检查 Chrome	HTTP
Sentry	访问 Sentry 错误日志	HTTP
GitHub	管理 PR、Issue 等 GitHub 功能	STDIO
OpenAI Docs MCP	搜索和读取 OpenAI 开发者文档	HTTP

配置示例：文件系统

[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]

配置示例：GitHub

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "your-token-here" }

Warning

把 token 直接写在配置文件里不安全。推荐用环境变量：先在 shell 里 export GITHUB_PERSONAL_ACCESS_TOKEN=xxx，然后在配置里用 env_vars = ["GITHUB_PERSONAL_ACCESS_TOKEN"] 转发。

插件提供的 MCP 服务器

安装的插件也可以在插件清单中打包 MCP 服务器。这类服务器由插件启动，你不需要手动配传输命令，只需控制启用状态和工具策略：

[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"

Note

插件打包的 MCP 服务器和你在 config.toml 里手动配的，使用方式是一样的。区别只是谁来启动它—手动配的你指定命令，插件打包的由插件自动启动。

故障排除

MCP 服务器不工作，按这个顺序排查：

命令对不对：手动跑一下 command + args，看有没有报错
依赖装了没：比如 npx 需要 Node.js，python 需要装好
环境变量设了没：需要 token 的服务器，检查环境变量是否存在
超时够不够：慢服务器加 startup_timeout_sec 和 tool_timeout_sec
看调试信息：启动时加 --verbose 看详细日志

codex --verbose

小结

你想干啥	怎么做
接本地工具	配 STDIO 服务器，指定 `command` + `args`
接远程服务	配 Streamable HTTP 服务器，指定 `url`
限制可用工具	用 `enabled_tools` / `disabled_tools`
控制审批策略	`default_tools_approval_mode` 或按工具 `approval_mode`
OAuth 登录	`codex mcp login <server-name>`
查看已连接服务器	输入 `/mcp`
临时禁用	`enabled = false`
排查问题	`codex --verbose` 看详细日志

MCP 让 Codex 不再局限于本地文件和终端命令。配好 Figma 就能让它看设计稿，配好 Sentry 就能查错误日志，配好 GitHub 就能管 PR。记住一条：MCP 服务器暴露的工具，默认每次调用都问你—这是安全设计。只有你完全信任的工具，才考虑调成自动批准。

下一章讲 Skills 技能系统—怎么把一套固定的工作流打包成 Codex 的「专项本事」。