发布日期：2026-10-19

Codex 接入 MCP（Model Context Protocol）就是把外部工具或数据源挂进 Codex，让编码任务按需调用它们。2026 年 10 月，OpenAI 官方提供了一个可直接使用的只读 Docs MCP 地址 https://developers.openai.com/mcp，支持搜索和读取开发者文档，但不会代替用户调用 OpenAI API。本教程先跑通 HTTP 文档服务器，再解释本地 STDIO、远程鉴权、OAuth、工具审批和常见故障排查。

先用官方 Docs MCP 跑通第一条链路

官方 Docs MCP 是一个无需先准备第三方账号的只读 HTTP 服务，适合验证 Codex 的 MCP 配置是否生效。

在终端执行：

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp list

第一条命令会把服务器写入 Codex 配置，第二条命令用于确认它已经出现在服务器列表中。OpenAI 官方示例也允许直接编辑 ~/.codex/config.toml：

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

保存后重新打开 Codex 会话，再在 TUI 中输入 /mcp 查看当前连接和工具目录。这里的“已连接”只说明服务器完成初始化，最好继续做一次真实调用，例如：

查找 Responses API tools 的请求字段，列出必填字段，并附上对应的 OpenAI 官方文档页面。

如果返回内容能指向官方页面，说明传输、工具发现和结果回传都已经走通。这个验证步骤比只看配置文件更可靠。

config.toml 放在哪里，影响谁？

Codex 默认从 ~/.codex/config.toml 读取 MCP 配置，也支持受信任项目中的 .codex/config.toml。前者适合个人常用服务器，后者适合只对某个项目开放的工具。

同一台 Codex 主机上的 ChatGPT 桌面应用、Codex CLI 和 IDE 扩展共享这套 MCP 配置，因此在一个客户端完成设置后，其他客户端可以复用。项目级配置有信任边界，仓库里出现新的 .codex/config.toml 时，应先确认它来自可信项目，再启动其中的服务器。

STDIO、Streamable HTTP 和 OAuth 到底怎么选

三种概念经常被混在一起：STDIO 描述服务器如何启动，Streamable HTTP 描述服务器如何访问，OAuth 描述访问服务器时如何完成授权。

STDIO：Codex 在本机启动一个进程

STDIO 服务器由 command 启动，args、env、env_vars 和 cwd 用来补充参数、环境变量和工作目录。一个本地服务的配置可以写成下面这样，路径和命令需要替换成你实际安装的服务器：

[mcp_servers.my_local_server]
command = "node"
args = ["./server.mjs"]
cwd = "/path/to/mcp-project"
env_vars = ["LOCAL_TOKEN"]

env_vars 是允许转发给 STDIO 进程的环境变量名，机密值放在操作系统环境中，不要把真实 Token 写进仓库。若服务器依赖固定环境变量，也可以用 env 直接写非机密配置。

Streamable HTTP：Codex 访问一个地址

HTTP 服务器至少需要 url。如果服务要求 Bearer Token，可以只把环境变量名写进配置：

[mcp_servers.company_docs]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "COMPANY_MCP_TOKEN"

Codex 还支持 http_headers 和 env_http_headers。前者适合固定的非敏感请求头，后者适合从环境变量取值。若服务器不要求鉴权，直接配置 url 即可，不能因为看到 HTTP 就默认添加 OAuth。

OAuth：服务器声明需要登录时再用

对于支持 OAuth 的 MCP 服务器，使用：

codex mcp login company_docs

Codex 官方指南还覆盖预注册 Client ID、回调地址和动态注册等情况。实际登录前先看服务器的授权元数据和提供方要求；不要把 OAuth 回调地址、Client Secret 或访问 Token提交到 Git。OpenAI Docs MCP 的基础接入是公开只读 HTTP，不需要把 OAuth 步骤加进去。

把工具权限收紧到可控范围

连接成功后，下一步是限制工具范围和审批方式，而不是把所有能力一次性放开。官方配置支持 enabled_tools 白名单、disabled_tools 黑名单，以及 default_tools_approval_mode。

例如，先只允许两个工具，并对未标记为只读的工具保留审批：

[mcp_servers.company_docs]
url = "https://mcp.example.com/mcp"
enabled_tools = ["search", "fetch"]
default_tools_approval_mode = "writes"

当同一服务器既有查询工具又有写入工具时，writes 模式会要求对非只读工具进行确认。更细的控制可以写到 tools.<tool>.approval_mode。这一步能让“能调用”变成“只调用允许的工具”。

连接失败，按这四步排查

第一步先运行 codex mcp list，确认服务器确实写入了当前使用的配置文件。CLI 读取的是用户级配置还是项目级配置，往往就是问题所在。

第二步在 TUI 输入 /mcp，确认工具目录已经出现。服务器出现在列表里但没有工具，通常要回到初始化日志和服务端返回内容检查，而不是继续重复提问。

第三步按传输方式检查字段：STDIO 看 command、args、cwd 和环境变量；HTTP 看 url、请求头和网络可达性。不要把 HTTP 地址填到 command，也不要把本地启动命令填到 url。

第四步再看鉴权和超时。官方默认的 startup_timeout_sec 是 10 秒，tool_timeout_sec 是 60 秒，可以针对慢启动或慢工具单独调整：

[mcp_servers.company_docs]
url = "https://mcp.example.com/mcp"
startup_timeout_sec = 20
tool_timeout_sec = 90

调大超时只能覆盖启动或执行确实较慢的情况，不能修复错误地址、失效 Token 或服务器没有实现对应工具的问题。若只是临时停用服务器，可以设 enabled = false，不必删除整段配置。

这套配置适合怎样的日常工作流

对需要频繁查 SDK 字段、配置参数和版本差异的开发任务，Docs MCP 可以把“打开浏览器搜索”变成“在当前任务中调用只读文档工具”。本地 STDIO 更适合需要访问本机文件、脚本或开发环境的服务；远程 HTTP 更适合团队共享的文档、工单或内部知识库；OAuth 则留给服务器明确要求用户授权的场景。

MCP 只负责连接工具和数据，模型、代码权限和审批策略仍由 Codex 当前配置决定。先用只读服务器验证链路，再逐个增加工具和权限，出现问题时更容易判断是配置、进程、鉴权还是工具本身。

本文数据截至 2026 年 10 月 19 日，配置字段和命令以 OpenAI 官方 MCP 指南、Docs MCP 页面及配置参考为准。

参考资料