← 返回 AI 指南
Codex 配置 MCP 教程：一条命令添加 MCP Server封面图
AI 编程约 7 分钟

Codex 配置 MCP 教程：一条命令添加 MCP Server

AI 指南··◉ 0 浏览

Codex 添加 MCP server 只需要一条命令：codex mcp add <名称> -- <启动命令>，或者直接编辑 ~/.codex/config.toml 写入 [mcp_servers.<名称>] 配置段。本文基于 Codex CLI 0.151.0 实测（macOS），带你 3 分钟完成 Codex 接入 MCP 工具的全流程，并附验证方法与常见报错排查。

先给一个时效坐标：截至 2026 年 9 月 18 日，npm 上 @openai/codex 最新版本已经是 0.155.0（本文的实测过程是在 0.151.0 上跑的，命令与配置格式在新版本里保持兼容）。从 0.151.0 到 0.155.0 之间，Codex 仓库里仍在大改 MCP 相关逻辑，最新一次提交就是「Keep MCP policy evaluation consistent with turn environments」，说明 MCP 还是活跃迭代的功能，升级前建议留意 release notes。

Codex 给 MCP server 选 STDIO 还是 HTTP 的决策流程图

本文目录

  1. Codex 支持哪两类 MCP server
  2. 方法一：codex mcp add 一条命令接入（推荐）
  3. 方法二：config.toml 手动配置（精细控制）
  4. 验证 MCP 是否接入成功
  5. 常用参数速查表
  6. 实测：接入 Context7 全过程
  7. 常见报错与排查
  8. Codex 和 Claude Code 的 MCP 配置有什么区别
  9. 常见问题 FAQ

Codex 支持哪两类 MCP server

MCP（Model Context Protocol）是把外部工具和数据接入 AI 编程助手的协议。Codex 支持两类 MCP server：

  • STDIO 类型：本地进程方式启动，比如用 npx 运行一个 npm 包。适合 Context7、Playwright 这类本地工具。
  • Streamable HTTP 类型：通过一个 URL 访问远程服务，支持 Bearer Token 和 OAuth 认证。适合 Figma、Sentry 这类云端服务。

配置一次，三端通用：Codex CLI、ChatGPT 桌面版和 VS Code 等 IDE 扩展共享同一份 MCP 配置，改一处即可（官方 MCP 文档 明确说明，我们也在装有 ChatGPT 桌面版的机器上实测验证了这一点）。

方法一：codex mcp add 一条命令接入（推荐）

最快的 codex 添加 mcp server 方式是 CLI 命令：

codex mcp add <server名称> -- <启动命令>

例如接入 Context7（免费的最新开发文档查询 MCP server）：

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

带环境变量时用 --env 参数：

codex mcp add my-server --env API_KEY=xxx -- npx -y some-mcp-server

HTTP 类型的远程 server 直接传 --url：

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

方法二：config.toml 手动配置（精细控制）

如果需要更精细的控制（超时时间、工具白名单、审批模式），直接编辑配置文件。全局配置在 ~/.codex/config.toml；也可以在可信项目里放 .codex/config.toml 做项目级配置。

STDIO 类型示例（本地进程）：

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

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

HTTP 类型示例（远程服务，以 Figma 为例）：

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

支持 OAuth 的 server（如 GitHub 官方 MCP），添加后执行 codex mcp login <名称> 完成一次授权登录即可。

验证 MCP 是否接入成功

三种验证方式：

  • 命令行：codex mcp list 查看已配置的 server 列表；
  • 交互界面：在 Codex TUI 里输入 /mcp 查看当前活跃的 MCP server；
  • 对话验证：直接让 Codex 使用对应工具，比如"用 context7 查一下 React 的文档"。

常用参数速查表

参数 作用 默认值
command + args STDIO server 的启动命令（必填） 无
url HTTP server 的地址（必填） 无
env 给 server 进程设置环境变量 无
startup_timeout_sec server 启动超时时间 10 秒
tool_timeout_sec 单次工具调用超时时间 60 秒
enabled 设为 false 可临时停用而不删除 true
enabled_tools / disabled_tools 工具白名单 / 黑名单 无
bearer_token_env_var HTTP server 的 Token 环境变量名 无

实测：接入 Context7 全过程

我们在 macOS（Apple Silicon）+ codex-cli 0.151.0 环境下完整跑了一遍，全程不到 1 分钟：

第 1 步：执行添加命令

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

终端立即返回：Added global MCP server 'context7'.

第 2 步：用 list 验证

执行 codex mcp list，输出表格里出现了 context7，状态为 enabled。一个小发现：这台机器装了 ChatGPT 桌面版，列表里同时显示了桌面版自带的 node_repl、computer-use 等 server，说明 CLI 和桌面版确实读的是同一份配置。

第 3 步：查看配置详情

codex mcp get context7 返回：transport 为 stdio，command 为 npx，args 为 -y @upstash/context7-mcp，末尾还贴心地提示了删除命令 codex mcp remove context7。

第 4 步：检查配置文件

打开 ~/.codex/config.toml，文件末尾自动追加了这段（命令行方式本质上就是帮你写这个文件）：

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

实测踩坑：npm 默认源在国内网络较慢，如果 npx 第一次启动超时，把 startup_timeout_sec 调到 20～30 即可解决。

codex mcp add 命令实测输出

codex mcp list 与 get 验证实测输出

config.toml 中的 MCP 配置示例

Codex 接入 MCP server 的两种方式总览

Codex CLI 版本变化与 MCP 配置兼容性说明图

常用 MCP server 推荐清单

MCP Server 类型 用途
Context7 STDIO 查询最新的开发框架文档
Playwright STDIO 控制和检查浏览器
Chrome DevTools HTTP/STDIO 调试 Chrome 页面
Figma HTTP 读取 Figma 设计稿
GitHub STDIO/HTTP 管理 PR、Issue 等
Sentry HTTP 查询线上错误日志
OpenAI Docs MCP STDIO 搜索 OpenAI 官方文档

常见报错与排查

1. 提示 server 启动超时 npx 第一次运行需要下载包，国内网络慢容易超过默认 10 秒启动超时。在 config.toml 里把 startup_timeout_sec 调大到 30 或 60。

2. codex 命令不存在 安装后没刷新 PATH。关闭终端重新打开，或检查环境变量。npm 全局安装的用户确认 npm root -g 对应的 bin 目录在 PATH 里。注意 @openai/codex 要求的 Node 版本是 16 及以上，Node 太老也会装不上。

3. npx 下载慢或失败 给 npm 配置镜像源，或者把 npx -y 包名 换成全局安装后的命令路径。

4. 配置写完不生效 检查 TOML 语法：每个 server 一个 [mcp_servers.名称] 段；args 在 TOML 里是数组写法（方括号 + 引号），不能照抄 JSON 的写法；项目级 .codex/config.toml 只在可信项目里生效。改完用 codex mcp list 确认。

5. OAuth 登录跳转失败 执行 codex mcp add 时终端会显示需要向服务商注册的回调地址（形如 http://127.0.0.1/callback），要填完全一致的回调 URL。

6. 升级后 MCP 行为变了 Codex 的 MCP 实现仍在频繁更新（0.151.0 到 0.155.0 期间就有多次 MCP 相关提交），升级后如果工具列表或审批行为有变化，先回看对应版本的 release notes 和官方 MCP 文档，再回滚到上一版本对比排查。

Codex 和 Claude Code 的 MCP 配置有什么区别

Codex 与 Claude Code MCP 配置差异对比

对比项 Codex Claude Code
配置文件 ~/.codex/config.toml（TOML 格式） ~/.claude.json / .mcp.json（JSON 格式）
配置段名 [mcp_servers.名称] "mcpServers": { "名称": {} }
快捷命令 codex mcp add claude mcp add
传输类型 STDIO + Streamable HTTP STDIO + SSE + HTTP
多端共享 CLI / 桌面版 / IDE 扩展共享一份配置 CLI 与桌面版各自管理

从 Claude Code 迁移过来的用户注意：Codex 用的是 TOML 而不是 JSON，mcp_servers 里的键名和 JSON 版本一致，但值的写法不同（比如 args 是 TOML 数组）。更多 AI 编程工具的使用技巧，可以看看我们知识论坛里的 Claude Code 实战经验帖。

配置完成后的检查清单

Codex 接入 MCP 工具的核心就两步：一条 codex mcp add 命令快速添加，或编辑 ~/.codex/config.toml 做精细控制；然后用 codex mcp list 或 TUI 里的 /mcp 验证。遇到启动超时就调大 startup_timeout_sec，遇到配置不生效优先检查 TOML 语法。配置一次，CLI、桌面版、IDE 扩展三端通用。

Codex 已收录在AI345 的 AI 工具导航里，配置好 MCP 后如果需要搭配其他 AI 开发工具，可以在导航里按分类查找。

延伸阅读：

参考资料：

最后更新：2026 年 9 月 18 日 · 实测基于 Codex CLI 0.151.0，已核对至 npm 最新版 0.155.0 · 作者：AI345 AI 指南编辑部

常见问题

Codex 支持 MCP 吗？

支持。Codex CLI、ChatGPT 桌面版和 IDE 扩展都支持 MCP server，三者共享同一份配置文件，配置一次即可在三端使用。

Codex 添加 MCP server 的命令是什么？

`codex mcp add -- `，例如 `codex mcp add context7 -- npx -y @upstash/context7-mcp`。远程 HTTP 服务用 `--url` 参数指定地址。

Codex 的 MCP 配置文件在哪里？

全局配置在 `~/.codex/config.toml`，项目级配置放在项目根目录的 `.codex/config.toml`（仅对可信项目生效）。

Codex 的 MCP 工具调用超时怎么改？

在 config.toml 对应 server 段里加 `tool_timeout_sec = 120`（默认 60 秒），启动慢的服务再加 `startup_timeout_sec = 30`（默认 10 秒）。

Codex 配置了 MCP 但列表里没有，怎么办？

依次检查：配置文件路径是否正确（`~/.codex/config.toml`）、TOML 段名是否写成 `[mcp_servers.名称]`、命令是否能在终端直接运行。改完执行 `codex mcp list` 验证。

Codex 和 Claude Code 的 MCP 配置能通用吗？

协议互通、server 可以共用，但配置文件不通用。Codex 用 TOML 格式的 `~/.codex/config.toml`，Claude Code 用 JSON 格式的 `~/.claude.json`，需要分别配置。

评论 (0)

?
0/1

还没有评论，来发第一条吧

网站上的服务均为第三方提供，
请用户注意自行甄别。

北京酷讯互动科技有限公司

备案京ICP备2024094994号-29

© 2026 AI345 · All Rights Reserved

用户服务协议·隐私政策