MCP：把 Codex 连接到外部工具和上下文

适用场景

这篇手册适合想让 Codex 连接外部工具、私有上下文或团队服务的用户。比如读取内部文档、查询任务系统、访问数据库只读接口，或调用你自己写的本地工具。

OpenAI 官方文档说明，Codex 支持 Model Context Protocol，简称 MCP。MCP server 可以为 Codex 提供工具和资源，让 Codex 在任务中读取更多上下文或执行外部动作。

步骤 1：先判断是否真的需要 MCP

不要一开始就配置 MCP。先判断任务能不能用更简单方式完成。

适合 MCP 的场景：

• 需要读取外部系统的实时数据。
• 需要连接团队内部工具。
• 需要让 Codex 调用一个结构化 API。
• 需要把重复工具能力提供给多个项目。

不适合 MCP 的场景：

• 一次性粘贴一小段公开资料就能解决。
• 只是让 Codex 读当前代码库。
• 只是需要一套固定工作流，这种更适合 Skill。

步骤 2：理解 stdio 和 HTTP MCP

Codex 常见 MCP server 有两类：stdio 和 HTTP。

stdio MCP 通常在本机启动一个命令行进程，Codex 通过标准输入输出和它通信。它适合本地脚本、内部工具、文件系统辅助工具。

HTTP MCP 通过 URL 提供服务，适合远程工具、团队共享服务或已有 Web API 包装。

选择建议：

• 本地工具优先 stdio。
• 团队共享服务优先 HTTP。
• 需要 OAuth 或集中权限管理时，优先考虑官方支持的远程方式。

步骤 3：用命令添加 MCP server

如果官方文档给出了添加命令，可以使用 codex mcp add。

示例结构：

codex mcp add my-tool -- command-to-start-server

不同 server 的命令不同，不要直接复制陌生命令。先确认它会启动什么程序、读取哪些文件、访问哪些网络资源。

步骤 4：在 config.toml 中配置 MCP

也可以在 Codex 配置文件中管理 MCP。常见位置包括全局配置和项目配置：

~/.codex/config.toml
your-project/.codex/config.toml

一个概念性结构如下：

[mcp_servers.my_tool]
command = "my-mcp-server"
args = ["--stdio"]

实际字段以官方文档和具体 MCP server 说明为准。项目级配置适合团队共享；全局配置适合你个人常用工具。

步骤 5：控制 MCP 工具权限

添加 MCP 后，Codex 可能会看到新的工具。工具可能只是读取数据，也可能会创建、修改或发送内容。

配置前要问清楚：

• 这个 server 暴露了哪些 tools？
• 哪些 tool 是只读？
• 哪些 tool 会写入、发送或删除数据？
• 是否需要 OAuth、Bearer token 或其他凭证？
• 凭证应该放在哪里，是否会被项目提交？

如果工具可能产生外部副作用，任务提示词中要写清楚审批边界。

步骤 6：用小任务测试 MCP

配置完成后，不要直接交给 Codex 大任务。先做只读测试：

请列出当前可用的 MCP 工具，并说明每个工具能读取或执行什么。
不要调用会写入或发送数据的工具。

确认工具列表和权限符合预期后，再让 Codex 执行具体任务。

常见错误

不要把 API key 写进项目仓库。凭证应放在安全的环境变量、系统凭据或官方推荐位置。

不要添加来源不明的 MCP server。它可能读取本地文件或访问外部服务。

不要把 MCP 当成万能入口。如果只是固定流程，用 Skill 更轻；如果只是安装能力，用 Plugin 更适合分发。

不要忽略外部副作用。创建任务、发送消息、修改文档、删除数据都需要明确授权。

小结

MCP 的价值是把 Codex 连接到结构化外部上下文和工具。正确流程是：先判断必要性，选择 stdio 或 HTTP，按官方方式配置，检查工具权限，用只读任务测试，最后再交给 Codex 做实际工作。