Codex 如何连接 MCP Server

大家好，我是 Codex 中文网的站长宇哥。

这篇教程适合谁

如果你已经能正常打开 Codex，但发现它只能读取当前仓库里的文件，不能直接查 GitHub issue、不能操作浏览器、不能访问公司内部工具，那么你就会遇到 MCP 的使用场景。

MCP 的全称是 Model Context Protocol。你可以把它理解成一套给 AI 工具接入外部能力的协议：外部服务通过 MCP Server 暴露工具、资源或提示模板，Codex 再在任务中调用这些能力。OpenAI 官方 Codex 文档把 MCP 放在自定义和扩展能力里讲，核心目的不是让你多装几个插件，而是让 Codex 在合适边界内拿到更准确的上下文。

这篇文章不追求把所有 MCP Server 都讲完，而是先把接入流程、检查方法和排错顺序讲清楚。后面你接 GitHub、浏览器、数据库或内部 API，思路都是同一套。

先判断你是否真的需要 MCP

不是所有需求都应该上 MCP。很多新手一看到 MCP 就想马上接一堆 Server，最后工具列表很热闹，真正调试时反而不知道是哪一层出问题。

适合 MCP 的场景通常有这些：

• Codex 需要访问当前仓库之外的数据，例如 GitHub issue、Notion 文档、内部知识库。
• Codex 需要执行一个专门工具，例如浏览器自动化、数据库只读查询、设计稿读取。
• 你希望把公司内部系统包装成标准工具，而不是每次都把接口说明复制给 Codex。
• 某些数据经常变化，不能靠写在提示词或 AGENTS.md 里解决。

不一定需要 MCP 的场景也很常见：

• 只是想让 Codex 遵守项目代码风格，优先写 AGENTS.md。
• 只是想设置默认模型、审批策略或沙箱，优先写 config.toml。
• 只是一次性让 Codex 参考一段文档，直接贴到任务里更简单。

简单说，MCP 适合连接外部活数据和外部工具；项目规则和写作规范，不要硬塞给 MCP。

接入前的准备清单

开始前先确认这几件事，能省掉很多时间：

• Codex CLI 可以正常运行，执行 codex --help 能看到命令说明。
• 你知道要接入的是 stdio 类型 Server，还是 streamable HTTP Server。
• MCP Server 的启动命令可以单独运行。
• 需要的环境变量已经准备好，例如 token、API key、服务地址。
• 你清楚这个 Server 会访问哪些目录、账号或网络服务。

官方 CLI 里提供了 codex mcp 子命令，可以管理外部 MCP Server。你可以先运行：

codex mcp --help

常用子命令包括：

• codex mcp list：查看当前已经配置的 MCP Server。
• codex mcp get <name>：查看某个 Server 的配置和状态。
• codex mcp add <name> -- <command>：添加 stdio 类型 Server。
• codex mcp add <name> --url <url>：添加 streamable HTTP 类型 Server。
• codex mcp remove <name>：移除某个 Server。
• codex mcp login <name>：对支持登录的 Server 执行认证。

如果你还没有任何配置，codex mcp list 可能只显示内置或插件提供的 Server，也可能为空，这都是正常的。

stdio Server 怎么接

stdio Server 是本地启动一个进程，通过标准输入输出和 Codex 通信。很多 Node.js、Python 或本地命令型 MCP Server 都属于这一类。

添加命令的基本格式是：

codex mcp add <name> -- <command> <args>

例如你要添加一个通过 npx 启动的 Server，命令结构通常类似：

codex mcp add demo-server -- npx -y some-mcp-server

如果 Server 需要环境变量，可以用 --env：

codex mcp add demo-server --env DEMO_TOKEN=your_token -- npx -y some-mcp-server

真实项目里不要把敏感 token 随手贴到教程、README 或截图里。更稳妥的方式是把 token 放在 shell 环境、系统密钥管理或专门的本地配置中，再让 Server 从环境变量读取。

添加完成后先不要急着做复杂任务，先查状态：

codex mcp list
codex mcp get demo-server

如果状态不是 enabled，或者命令、参数、环境变量显示不符合预期，先处理配置，再进入 Codex 对话。

HTTP Server 怎么接

streamable HTTP Server 适合已经部署成 HTTP 服务的 MCP。例如公司内部工具、远程知识库服务、托管型 MCP 服务等。

添加方式是：

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

如果服务需要 bearer token，可以通过环境变量指定 token 来源：

export DOCS_MCP_TOKEN="your_token"
codex mcp add docs-server --url https://example.com/mcp --bearer-token-env-var DOCS_MCP_TOKEN

这种方式的优点是本地不用安装很多依赖，团队也更容易统一服务版本。缺点是你要额外关注网络可达性、登录状态、服务端权限和超时问题。

如果 HTTP Server 支持 OAuth，Codex CLI 也提供了 codex mcp login <name> 这类登录入口。实际是否可用取决于该 MCP Server 的实现和认证配置。

配置文件和命令行该怎么选

对新手来说，我建议先用 codex mcp add 管理配置，因为它会降低手写配置出错的概率。等你理解字段含义后，再去看 ~/.codex/config.toml 或项目级 .codex/config.toml。

大致原则是：

• 个人电脑长期使用的 MCP，放用户级配置。
• 某个仓库专用、团队共享的 MCP，考虑项目级配置。
• token、密钥、个人账号信息，不要提交进仓库。
• 临时测试参数，可以用 -c key=value 覆盖。

需要特别注意的是，项目级 .codex/config.toml 只有在项目被信任时才会加载。这个设计是为了避免随便打开一个仓库就自动加载陌生配置。也就是说，你在项目里写了 MCP 配置，但 Codex 没有加载时，要先确认当前项目是否已被信任。

第一次验证怎么做

添加 MCP 后，最忌讳立刻让 Codex 做“大而全”的任务。推荐按三个小步骤验证：

第一步，只查配置：

codex mcp list
codex mcp get demo-server

第二步，让 Codex 在对话里描述它能看到哪些工具。提示词可以写得很克制：

请列出当前可用的外部工具名称，不要调用任何工具，不要修改文件。

第三步，让 Codex 调用一个低风险能力。例如只读读取一个文档标题、查询一个公开 issue、打开一个本地页面截图。不要一上来就让它写数据库、批量创建 issue 或修改生产数据。

这样分层验证的好处是：如果失败，你能知道是配置没加载、Server 没启动、认证失败，还是工具本身调用失败。

常见 MCP Server 类型

教程站第一阶段可以优先覆盖这些类型，因为它们离开发者最近：

• 文件系统类：让 Codex 访问指定目录或结构化资源，适合多仓库、文档库、脚本目录。
• GitHub 类：读取 issue、PR、commit、release，适合根据线上任务改代码。
• 浏览器类：打开页面、点击、截图、检查 DOM，适合前端验收和视觉测试。
• 数据库类：做只读查询、分析表结构，适合排查业务数据，但权限一定要控制。
• 内部 API 类：把公司内部工具包装成标准工具，适合团队长期复用。

初期不要一次性接太多。先接一个你每天都会用到的 Server，把启动、认证、权限、调试链路跑稳，再逐步扩展。

权限边界怎么设计

MCP 最大的价值是给 Codex 增加能力，最大的问题也是增加能力。接入前一定要想清楚边界。

我通常会按这个顺序检查：

• 能只读就先只读，不要默认给写权限。
• 能限定目录就限定目录，不要把整个主目录暴露出去。
• 能用测试账号就不用生产账号。
• 能把危险操作拆成需要人工确认的流程，就不要让工具直接执行。
• 能记录工具调用日志，就保留日志，方便复盘。

尤其是数据库和内部系统，不要为了图方便给一个全权限 token。Codex 本身会遵守任务和审批约束，但工具能力一旦过大，误操作成本也会变高。

常见问题 FAQ

codex mcp list 看不到新 Server 怎么办？

先确认你添加 MCP 的 Codex 环境和当前运行 Codex 的环境是不是同一个。有些人同时装了桌面 App、CLI、测试版 CLI，结果配置写到了一个位置，实际启动的是另一个入口。

然后执行：

codex mcp get <name>

如果能查到配置，但对话里看不到工具，重启 Codex 会话再试。如果还是不行，再检查项目级配置是否因为未信任项目而没有加载。

Server 启动失败怎么办？

先把启动命令单独复制出来运行，不要一开始就在 Codex 里调。比如你的配置是 npx -y some-mcp-server，那就先在终端直接执行它，看看是不是依赖下载失败、Node 版本不对、环境变量缺失或网络被拦。

HTTP MCP 一直认证失败怎么办？

优先检查 token 环境变量是否真的存在：

printenv DOCS_MCP_TOKEN

不要在公开终端截图里展示完整 token。只需要确认变量不为空即可。然后检查服务端是否要求 OAuth、bearer token 名称是否正确、URL 是否写到 MCP 入口路径。

要不要把 MCP 配置提交到仓库？

公共的、无密钥的项目级配置可以提交；含有个人账号、token、内网地址或机器路径的配置不要提交。团队场景更推荐提交一个示例文件，例如 .codex/config.example.toml，真实密钥由每个人本地配置。

MCP 和 AGENTS.md 有什么区别？

AGENTS.md 适合写规则，例如代码风格、测试命令、提交规范、文章开头固定文案。MCP 适合提供工具和数据，例如查 GitHub、开浏览器、读外部文档。一个是“告诉 Codex 怎么做”，一个是“给 Codex 新能力”。

参考官方文档

继续深入时，建议从这几个官方页面开始：

• Codex MCP 文档
• Codex CLI 文档
• Codex 配置文档
• Codex 配置参考

总结

Codex 接 MCP 的关键不是“装得越多越强”，而是把一个外部能力接得稳定、可控、可验证。先确认需求，再选择 stdio 或 HTTP，再用 codex mcp list 和 codex mcp get 做基础检查，最后用低风险任务验证工具可用。

后续本站会把 GitHub MCP、浏览器 MCP、文档库 MCP 和数据库只读 MCP 分别拆成独立教程，每篇都尽量给出可复现的配置和排错路径。