Codex 配置 MCP 教程（CLI 与 config.toml）

浏览：1次阅读

Codex 配置 MCP 最快的方法是一条 codex mcp add 命令：本地服务用 -- 接启动命令，远程服务用 --url 填地址，配置会写进 ~/.codex/config.toml，CLI、IDE 插件和 ChatGPT 桌面应用共用这一份。下面按 OpenAI 官方文档把命令行和 config.toml 两种写法、常见报错一起讲清楚。

图片来源：OpenAI 官方文档 Model Context Protocol

MCP（Model Context Protocol，模型上下文协议）让 Codex 调用外部系统的工具和资料，比如查最新的开发文档、读 Figma 设计稿、用 Playwright 控制浏览器、看 Sentry 日志、管理 GitHub 的 PR 和 Issue。官方文档列出的常用服务器就有 OpenAI Docs MCP、Context7、Figma、Playwright、Chrome DevTools、Sentry、GitHub 等。

Codex 支持两类 MCP 服务器：

STDIO 服务器：在你电脑上以本地进程运行，由一条命令启动，可以传环境变量。
Streamable HTTP 服务器：通过网址访问，支持 Bearer Token 和 OAuth 登录。

开始前请先装好 Codex CLI 并能正常对话，还没装的可以看 Codex CLI Windows 安装与接入 API 教程。MCP 配置和你用官方账号登录还是接第三方 API 无关，两种方式都能用。

基本语法如下，双横线 -- 前面是 Codex 自己的参数，后面是启动服务器的命令：

# 基本语法
codex mcp add < 名称 > --env VAR1=VALUE1 --env VAR2=VALUE2 -- < 启动命令 >

# 示例：添加 Context7（查询最新开发文档的 MCP 服务）codex mcp add context7 -- npx -y @upstash/context7-mcp

用 npx 启动的服务需要电脑上先装好 Node.js。需要密钥的服务，用 --env 把密钥作为环境变量传给服务器。

服务商给的是网址时，用 --url：

codex mcp add example --url https://mcp.example.com

如果服务要求预先注册的 OAuth 客户端，再加上 --oauth-client-id（机密客户端还要 --oauth-client-secret，建议从环境变量读取，不要把密钥明文写进命令历史）。添加时 Codex 会显示要在服务商后台登记的回调地址，照着登记即可。

codex mcp list           # 列出已配置的服务器
codex mcp login < 名称 >   # 对支持 OAuth 的服务器发起登录
codex mcp --help         # 查看全部 MCP 子命令
/mcp                     # 在 codex 交互界面里查看当前启用的服务器

Codex CLI 终端界面。图片来源：openai/codex GitHub 仓库

想更细地控制超时、工具白名单、审批方式，就直接改配置文件。全局配置在 ~/.codex/config.toml（Windows 在用户目录下的 .codex\config.toml）；也可以在项目里建 .codex/config.toml，只对这个项目生效，但 只有被信任的项目才会读取。

每个服务器写成一个 [mcp_servers. 名称] 表。

[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（必填，启动命令）、args（参数）、env（直接写入的环境变量）、env_vars（从本机环境转发的变量名）、cwd（工作目录）。

[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 填的是 环境变量名，不是 Token 本身，Codex 会读取这个变量放进 Authorization 头；固定请求头写在 http_headers，要从环境变量取值的请求头写在 env_http_headers。

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]   # 在 enabled_tools 之后生效
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

startup_timeout_sec：服务器启动超时，默认 10 秒。
tool_timeout_sec：单次工具调用超时，默认 60 秒。
enabled = false：临时停用某个服务器，不用删配置。
required = true：这个服务器起不来时，让 Codex 直接启动失败，方便发现问题。
default_tools_approval_mode：可选 auto、prompt、writes、approve，其中 writes 只对没有标记为只读的工具弹确认。

很多 MCP 服务的说明只给了 Claude Desktop、Cursor 用的 mcpServers JSON。Codex 不读这种 JSON，要手动改成 TOML："mcpServers": {"xxx": {...}} 对应 [mcp_servers.xxx]，command、args 原样照搬，env 对象写成 [mcp_servers.xxx.env] 子表。Claude Code 用户可以对照看 Claude Code 配置 MCP 教程，两边的思路一样，只是文件格式不同。

官方说明 ChatGPT 桌面应用、Codex CLI 和 IDE 插件共用同一份 MCP 配置，在一处配好，换客户端不用重配。图形界面操作是：

ChatGPT 桌面应用：打开 Settings，选 MCP servers；IDE 插件：点齿轮菜单，选 MCP servers。
点 Add server，填名称，选 STDIO 或 Streamable HTTP，再填启动命令或网址。
保存后，桌面应用点 Restart，IDE 插件点 Restart extension。
需要 OAuth 的服务器，在列表里点 Authenticate 登录。

STDIO 服务第一次用 npx -y 启动时要先下载依赖，网络慢时很容易超过默认的 10 秒。把 startup_timeout_sec 调到 30 到 60，或者先在终端手动运行一次启动命令，把包下载好再进 Codex。另外，可选服务器在构建初始工具列表时只等 mcp_optional_startup_grace_ms（默认 1000 毫秒），慢的服务会晚一点才出现，用 /mcp 再确认一下。

项目级配置只对被信任的项目生效。先确认你在 Codex 里已经信任了这个目录；不想折腾的话，把配置放到全局的 ~/.codex/config.toml。还要检查 TOML 语法，比如字符串要加双引号、数组用方括号。

401 一般是没登录或 Token 没读到：支持 OAuth 的服务运行 codex mcp login 名称；用 Token 的服务，检查 bearer_token_env_var 写的是变量名，并且这个环境变量在启动 Codex 的终端里确实存在。403 通常是权限或 OAuth 授权范围不够，可以在 config.toml 里用 scopes 指定范围，或运行 codex mcp login 名称 --scopes read,write 重新登录。

用预注册客户端时，服务商后台登记的回调地址必须和 codex mcp add 显示的完全一致。远程开发机等特殊环境可以用 mcp_oauth_callback_url 和 mcp_oauth_callback_port 自定义回调地址和端口。

执行时间长的工具（比如浏览器自动化、大批量查询）可以单独调高 tool_timeout_sec。如果是模型本身限流报 429，那和 MCP 无关，可以看 Codex 报错 429 的原因和解决方法。

不会。Codex 用 config.toml，Claude Code 用 ~/.claude.json 和 .mcp.json，需要分别配置。

在它的配置里加 enabled = false 就能停用，不用删除；只想屏蔽其中几个工具，用 disabled_tools。

能。插件自带的服务器不能改启动命令，但可以在 [plugins."插件名".mcp_servers. 服务器名] 下面控制开关、工具白名单和审批方式。

正文完