配置 Codex MCP，可以让 Codex 使用 Model Context Protocol（模型上下文协议）Server 暴露的工具与上下文。但 add 命令打印成功，并不表示配置已经全部完成。你还需要选择正确的 transport（传输方式）、把配置放在合适的作用域、安全认证、限制可执行工具，并验证真实连接。
本文依据 2026 年 9 月 1 日核验的 OpenAI 官方 Codex MCP 配置编写，不声称已经使用你的账号实测任何第三方 Server。Server URL、包名、认证要求与工具行为都可能变化，请始终与 Server 所有者的最新说明对照。
MCP 是工具与上下文扩展层，并不是把 Codex 嵌入应用的接口。后一个问题请看 Codex SDK、App Server 与 Exec 对比。
Codex MCP 配置会改变什么
官方 Codex MCP 文档说明，同一 Codex 主机上的 ChatGPT Desktop、Codex CLI 和 Codex IDE Extension 都可以连接 MCP Server，并共享 MCP 配置。
MCP Server 可以提供文档搜索、浏览器控制、设计数据、Issue 管理或数据库查询等工具。连接后，Codex 能看到 Server 公布的工具和 instructions。这不代表所有工具都天然安全或自动获批。MCP Server 决定自己提供什么；Codex 配置和外围权限系统决定哪些工具启用，以及哪些动作必须让人批准。
可以把配置理解为四份相互独立的合同：
- Transport： Codex 怎样连接 Server。
- Authentication： Server 接受什么身份或 Token。
- Configuration scope： 哪些 Codex 客户端或项目会加载 Server。
- Tool authority： 哪些工具启用、怎样批准调用。
添加 Server 前先准备什么
先从 MCP Server 的官方说明中收集这些信息：
- 它提供远程 URL，还是本地启动命令？
- 它指定 Streamable HTTP、STDIO，还是某种旧 transport？
- 它需要 OAuth、bearer token、自定义 header，还是无需认证？
- 本地 Server 需要什么包、二进制文件、运行时与版本？
- 哪些工具会读数据、写数据或触发外部副作用？
- Server 是否需要当前仓库、其他目录或网络权限？
运行本地 Server 命令前先检查它。STDIO 表示 Codex 会在你的机器上启动进程；从别处复制的 npx、uvx、Python 或二进制命令，会在本地策略允许的文件系统和环境范围内执行。对远程 Server，则要核验准确的 HTTPS 来源和实际控制它的组织。
第 1 步：选择 STDIO 或 Streamable HTTP
目前 Codex 主机主要支持两种 MCP transport：
按 Server 运营方的说明选择 transport。URL 不能直接当成本地启动命令使用，Server 的认证流程通常也依赖 transport。
使用 STDIO 时，需要命令、参数以及可能的环境变量；使用 Streamable HTTP 时，需要 Server URL，并可能需要 OAuth 或授权 header。OpenAI 当前文档明确列出 HTTP Server 的 bearer token 与 OAuth 支持。
第 2 步：添加 MCP Server
对本地 STDIO Server，官方 CLI 命令形状是：
双横线用于分隔 Codex 自己的选项和需要启动的 Server 命令。OpenAI 当前给出的 Context7 示例是：
不要只因为示例方便就直接复制。先向 Server 所有者核验包名与行为，也不要把长期 secret 直接写进 shell history。
对远程 Streamable HTTP Server，CLI 可以接收 URL。提供方要求预注册 OAuth Client 时，OpenAI 展示的形式是：
如果提供方不需要自定义 Client ID，请按它的最新说明操作，并用 codex mcp --help 检查你所安装版本中的准确参数。
你也可以直接在 TOML 中配置。每个 Server 都放在 [mcp_servers.<server-name>] 表格下。最小 STDIO 示例：
最小远程示例：
这些只展示配置形状，并不是可用凭据，也不代表 Agent.Space 推荐某个真实 Server。
第 3 步：选择配置作用域
Codex 默认把 MCP 配置放在：
这是主机级 Codex 配置。根据官方指南，同一 Codex 主机上的 ChatGPT Desktop、Codex CLI 和 IDE Extension 会共享它。
可信项目也可以定义：
如果某个个人工具需要有意识地跨项目使用，放在主机级文件中；如果 Server 只属于一个仓库，并且该项目可信，使用项目级配置。项目配置可能随仓库共享，因此其中只能包含可以安全地让所有授权协作者看到的设置。
不要提交 Token、静态 authorization header 或机器专属 secret。也不要因为一条项目级本地命令来自仓库，就自动信任它。允许执行前，检查命令、包来源、要求的环境变量和预期工具列表。
Codex 与 OpenCode 使用的命令和配置合同不同。如果你同时维护两个 Agent harness，可以阅读 OpenCode MCP 指南，避免把一边的配置文件直接复制到另一边。
第 4 步：认证且不提交 Secret
远程 HTTP Server 支持 OAuth 时，优先使用 OAuth。添加 Server 后运行：
Codex 支持官方文档中描述的 OAuth 发现与注册流程。Server 可以公布它支持的 scope；否则 Codex 会回退到为该 Server 配置的 scope。只申请目标工具真正需要的 scope。
使用 bearer token 时，把真实值留在环境中，在 TOML 里只引用变量名：
需要从环境读取自定义 header 时：
OpenAI 也支持静态 http_headers，但把静态 secret 放进共享配置文件通常不是好的默认做法。环境变量引用能降低误提交风险，却不能替代对环境本身、shell history、进程日志和上游 Token 的保护。
对 STDIO Server，可以用 env_vars 转发选定的现有变量，或用 env 为该进程明确设置值。转发范围越小越好。收到整套含凭据环境的本地 Server，比只收到一个窄权限 Token 的 Server 有更大的影响范围。
第 5 步：限制工具与批准方式
连接成功后，Server 可能暴露超出当前任务需要的工具。Codex 支持这样的 Server 级控制：
enabled_tools 是 allowlist（允许列表），disabled_tools 可以在 allowlist 之后继续排除工具。当前 approval mode 包括 auto、prompt、writes 与 approve；其中 writes 会对 Server 没有标为只读的工具要求批准。也可以为单个工具覆盖设置。
工具 metadata 属于信任模型的一部分，却不是无害证明。Server 可能错误标注工具，只读动作也可能暴露敏感数据，范围过大的搜索工具还可能返回不可信指令。添加新 Server 时：
- 第一条工作流只允许真正需要的工具；
- 写入和有外部副作用的工具继续要求批准；
- 批准前检查参数；
- 尽可能使用测试账号或只读上游身份；
- 设置合理的启动与工具超时，不用无限等待掩盖故障。
更完整的仓库、网络、secret 与批准边界可以参考 Coding Agent 工作区安全清单。
第 6 步：验证全部三层状态
按顺序验证。每一层回答的问题不同。
1. 配置是否存在？
运行：
确认预期 Server 名称和 transport 出现。如果没有出现，检查 Codex 实际加载了哪个 config.toml、项目是否可信，以及 TOML 是否有效。
2. Server 是否在本次 Codex Session 中活动？
启动 Codex TUI 并运行：
OpenAI 把 /mcp 记录为查看活动 MCP Server 的入口。确认认证已经完成，预期 Server 可用。如果需要 OAuth，先完成 codex mcp login <server-name>，再重新检查。
3. 一个目标工具能否完成无害动作？
让 Codex 执行一个边界很窄的只读操作，例如列出 Server 可访问的文档来源，或读取一页已知公开页面。检查：
- 选中的是预期 Server 与工具；
- 参数没有意外路径、secret 或过宽查询；
- 返回结果与来源一致；
- 没有发生写入、发消息、购买、建 Issue 等副作用。
之后才测试写工具，并使用一次性目标和明确批准。“Added”“出现在 list 中”“活动”“安全工具调用完成”是四个不同层级的证据。
常见配置问题
Server 出现在 list 中，但 Session 里不可用。 检查 /mcp；如果相关客户端的配置流程要求重启，就按要求重启；同时确认它在同一个 Codex 主机上加载了预期配置。
STDIO Server 启动失败。 只有在你信任命令时，才单独运行文档给出的命令。检查运行时和包是否存在、参数是否放在 -- 后、必要环境变量是否存在，以及配置的 cwd 是否有效。
HTTP Server 返回认证错误。 检查 URL、OAuth 登录状态、bearer-token 变量和申请的 scope。不要把 Token 粘进公开 Issue 或诊断输出。
Server 已连接，但缺少某个工具。 检查 enabled_tools、disabled_tools、Server 当前公布的工具列表和组织策略。上游改名或删除的工具，不能靠旧本地配置恢复。
错误的项目也能看到 Server。 在主机级与可信项目级配置之间移动条目。不要通过到处复制同一个 Server 和凭据来掩盖 scope 错误。
一份安全默认清单
- 使用 Server 所有者当前官方 URL 或启动命令。
- 官方提供远程 endpoint 时优先 Streamable HTTP；官方提供本地进程时使用 STDIO。
- 个人跨项目工具放入
~/.codex/config.toml；只有可信项目的可共享设置才放入.codex/config.toml。 - Secret 保存在受保护的环境变量或 OAuth 存储中，不提交到 TOML。
- 申请最小 OAuth scope 与最小上游账号权限。
- 从只读工具 allowlist 开始，并让写入工具继续要求批准。
- 分别验证配置、活动连接和一次无害只读调用。
- 如果凭据曾出现在 Prompt、日志、shell history 或 commit 中，立即轮换。
下一步怎么做
Server 通过三层验证后，为团队记录它的用途、所有者、transport、scope、必要变量、允许工具与移除方式。Server 包、URL 或公布工具变化时，重新检查这份合同。
MCP 能扩展 Codex harness，但好的配置仍然从正确的执行入口和权限边界开始。准备把它用于真实工作时，可以打开 Agent.Space，先从一个工具和审批过程都容易检查的低风险任务开始。