Codex 接入 MCP 服务器

这篇适合谁、读完能做到什么

如果你希望 Codex 能访问团队的工单系统、文档站点或浏览器工具，就需要接入 MCP 服务器。读完这篇，你能用命令行或配置文件添加一个服务器，确认它已经连上，处理 OAuth 登录，并限制 Codex 能调用哪些工具。^[1]

MCP 在 Codex 里是做什么的

MCP（Model Context Protocol，模型上下文协议）让 Codex 使用其他系统的工具和信息。MCP 服务器会列出自己提供的工具，并处理 Codex 发来的请求，比如查一张工单，或者取回一段文档。^[1]

Codex 支持两种服务器。STDIO 服务器作为本地进程运行，由一条命令启动；Streamable HTTP 服务器则通过一个地址访问。^[1] 桌面 App、CLI 和 IDE 扩展读取的是同一套 MCP 配置，配一次就能在这几个客户端之间切换，不用重复设置。^[1]

配置文件放在哪里

默认的配置文件是 ~/.codex/config.toml。如果只想让某个项目用某个服务器，就把它写进项目里的 .codex/config.toml。项目级配置只对受信任的项目生效。^[1]

用命令行添加服务器

添加 STDIO 服务器时，运行 codex mcp add，后面依次跟服务器名、可选的 --env 参数，以及 -- 之后的启动命令：

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

举个例子，Context7 是一个免费的开发者文档 MCP 服务器，可以这样添加：^[1]

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

运行 codex mcp list 可以查看已经配置的服务器。在终端界面里输入 /mcp，则显示当前处于激活状态的服务器。^[1]

在桌面 App 和 IDE 里添加

在桌面 App 中，打开设置，选择 MCP servers，点击 Add server，选 STDIO 或 Streamable HTTP，填入命令或地址，保存后点 Restart。在输入框里输入 /mcp，可以列出已连接的服务器。^[1]

IDE 扩展里，打开齿轮菜单，选 MCP servers，再点 Add server，然后填写名称、传输方式和地址。保存后点击 Restart extension。^[1]

两种服务器的配置差别

STDIO 服务器的关键在启动方式：command 指定启动命令，args 传入参数，cwd 设定启动目录，env 和 env_vars 负责传递环境变量。Streamable HTTP 服务器的关键在访问方式：url 指向服务器地址，认证可以用 bearer token、请求头或 OAuth。超时、启用和工具过滤等选项见后面的小节。^[1]

在 config.toml 里配置服务器

每个服务器对应一个 [mcp_servers.<server-name>] 表。参考页面列出了所有支持的选项。^[1] 对于 STDIO 服务器，command 必填；args、env、env_vars 和 cwd 可选。^[1] 下面这段配置让 Context7 在启动时带上一个环境变量：

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

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

env_vars 既可以写普通的变量名，也可以写带 source 的对象。普通变量名和 source = "local" 从 Codex 所在的本地环境读取；source = "remote" 从远程执行环境读取，只适用于远程的 STDIO 服务器。^[1]

对于 Streamable HTTP 服务器，url 必填。bearer_token_env_var 指定一个环境变量名，变量的值会作为 bearer token 发送；http_headers 设置固定的请求头，env_http_headers 则从环境变量里取请求头的值。^[1] auth 默认为 oauth，使用保存的 MCP OAuth 凭据。设为 chatgpt 时，会使用当前的 ChatGPT 会话，但只对受信任的 ChatGPT 官方源生效，并以保存的 OAuth 作为后备。^[1]

http_headers_helper 指向一条本地命令，它输出 JSON 格式的请求头。它只适用于从本机访问的 HTTP 服务器，不适用于 STDIO 服务器或远程执行环境。Codex 会缓存这些请求头；同源的 POST 请求返回 401 或 403 后，它会刷新一次，而且只有请求头的值变了才会重试。^[1]

超时、启用与停用

startup_timeout_sec 默认 10 秒，tool_timeout_sec 默认 60 秒。把 enabled = false 写上，可以停用一个服务器而不删除配置。^[1] 设置 required = true 后，如果服务器没有就绪，启动会失败。默认的 startup_readiness 为 "connection"，要求实时连接；设为 "catalog" 时，有效的工具缓存也能让启动通过，但调用工具仍然需要实时连接。^[1]

顶层的 mcp_optional_startup_grace_ms 默认为 1000 毫秒，决定 Codex 在构建初始工具列表时，等待可选服务器的时长。设为 0，则会一直等到每个服务器自己的启动超时。必需的服务器始终使用各自的超时设置。^[1]

限制 Codex 能用哪些工具

enabled_tools 是允许列表，disabled_tools 是拒绝列表，在允许列表之后应用，所以一个工具要先通过允许列表，还不能被拒绝列表排除。这些规则都写在各自服务器的表里，每个服务器可以有不同的限制。default_tools_approval_mode 可选 auto、prompt、writes 和 approve，其中 writes 会对没有标记为只读的工具要求审批。^[1] 对单个工具，可以用 tools.<tool>.approval_mode 覆盖审批方式，用 tools.<tool>.output_token_limit 限制它的输出 token 数。^[1] 下面是一个同时用到这些选项的 Streamable HTTP 服务器：

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after 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

OAuth 服务器怎么登录

需要 OAuth 的服务器，运行 codex mcp login <server-name>。如果机器上没有本地浏览器，加上 --no-browser。在浏览器里打开命令打印的授权地址，登录后把完整的回调地址粘贴回终端，即使浏览器打不开回调页面也要这样做。^[1]

如果授权服务器要求预先注册的客户端，添加服务器时把客户端 ID 传进去：

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

机密客户端还要加 --oauth-client-secret。Codex 会把密钥写进 config.toml 的 mcp_servers.example.oauth.client_secret，所以这个文件要保持私密，不要提交到版本库。^[1] 注册回调地址时，使用 codex mcp add 打印出的完整地址。只有在需要自定义回调时，才设置 mcp_oauth_callback_url 或 mcp_oauth_callback_port。^[1] 授权范围用配置里的 mcp_servers.<server-name>.scopes 设置；如果只想为某次登录指定，就给 codex mcp login 加 --scopes。^[1]

可以先试的服务器

文档列举的常见服务器有 OpenAI Docs MCP、Context7、Figma、Playwright、Chrome DevTools、Sentry 和 GitHub。^[1]

常见问题

服务器启动慢或失败。 调大 startup_timeout_sec，或者把 mcp_optional_startup_grace_ms 设为 0，让 Codex 等满超时时间。^[1]
工具调用超时。 在该服务器上调大 tool_timeout_sec。^[1]
希望 Codex 调用工具前先询问。 把 default_tools_approval_mode 设为 prompt，或者给单个工具设置 approval_mode。^[1]
配置写好了，工具却不出现。 先用 codex mcp list 或终端里的 /mcp 确认服务器已经列出，再检查 enabled_tools 和 disabled_tools 是否把它过滤掉了。^[1]