2026 Codex MCP 配置教程：添加 Server、config.toml 与 OAuth

先给结论：添加、检查、调用分三步

初次添加优先使用 CLI，成功后用列表和 TUI 检查，不要一开始就把大段 TOML、Token 和 Full Access 一起复制进去。

# 1. 添加一个 STDIO MCP Server
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 2. 查看已经配置的 Server
codex mcp list

# 3. 进入 Codex TUI 后查看当前状态与工具
/mcp

上面的 Context7 是 OpenAI 当前文档使用的示例。真正配置前仍应查看 Server 自己的仓库、安装说明、权限和维护状态；示例出现于官方文档不等于 OpenAI 对第三方 Server 的持续安全担保。

先选传输：STDIO 还是 Streamable HTTP

STDIO Server 不是“更安全的本地插件”：它仍可能读取文件、运行进程或访问网络，能力取决于它暴露的工具和当前 Sandbox。远程 HTTP 也不自动等于不可信；关键是服务主体、认证方式、实际工具和批准范围是否清楚。

方法一：使用 codex mcp add 添加 Server

CLI 可以减少 TOML 拼写错误，适合第一次配置。通用 STDIO 形式为：

codex mcp add <server-name> \
  --env VAR1=VALUE1 \
  --env VAR2=VALUE2 \
  -- <server-command> <arg1> <arg2>

1. 核对 Server 的官方安装说明

   确认包名、仓库、维护者、所需 runtime 和最小版本；不要仅凭短视频评论区复制命令。

2. 先在测试环境运行命令

   了解它会下载什么、读取什么、监听什么端口。npx -y 会自动确认包执行，使用前要先核对包名。

3. 使用清楚的 Server 名称

   名称会出现在 codex mcp list、/mcp 和错误信息中，避免使用 server1、test 等难以追踪的名字。

4. 添加后立即检查

   先看是否列出、是否启用、提供哪些工具，再让它接触真实仓库或账号。

需要 OAuth 的远程 Server，添加配置后单独运行：

codex mcp login <server-name>

浏览器授权页出现的服务域名和权限应与预期一致。不要把 OAuth callback、授权码或 Token 发到聊天、Issue 或截图中。

方法二：在 config.toml 精细配置

Codex 默认把 MCP 配置与其他设置一起保存在 ~/.codex/config.toml。可信项目也可以使用项目级 .codex/config.toml；项目未被信任时，不应假定项目配置会生效。

STDIO Server 示例

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

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

command 是启动命令；args 是参数；cwd 可以限制启动目录；env 设置指定值；env_vars 转发已有环境变量。不要把真实 Token 直接写进准备提交到 Git 的配置。

Streamable HTTP Server 示例

[mcp_servers.example_remote]
url = "https://mcp.example.com/mcp"
bearer_token_env_var = "EXAMPLE_MCP_TOKEN"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60

bearer_token_env_var 填的是环境变量名称，不是 Token 值。当前官方配置还支持 http_headers 静态 Header 和 env_http_headers 环境变量 Header；只有 Server 文档明确要求时再配置。

OAuth、Bearer Token 与环境变量怎么选

如果 OAuth 提供方要求固定回调，可配置顶层 mcp_oauth_callback_port 或 mcp_oauth_callback_url。OpenAI 当前文档说明 callback URL 还会附加 Server 专用 callback ID；注册重定向地址时必须以当前官方说明和服务商设置为准。

不要把“连接成功”直接等同于“所有工具自动批准”

当前 Codex MCP 配置可以限制 Server 是否启用、哪些工具可见，以及工具调用的默认审批方式：

[mcp_servers.example]
url = "http://localhost:3000/mcp"
enabled = true
enabled_tools = ["search", "read"]
disabled_tools = ["delete"]
default_tools_approval_mode = "prompt"

[mcp_servers.example.tools.search]
approval_mode = "approve"

• enabled_tools 是允许列表；disabled_tools 在允许列表之后应用。
• default_tools_approval_mode 当前支持 auto、prompt、writes 与 approve。
• tools.<tool>.approval_mode 可以单独覆盖一个工具的行为。
• required = true 会让启用的 Server 初始化失败时阻止启动，只适合确实必须可用的组织级依赖。

配置名称只是策略入口，不能替代 Server 对工具的正确标记。首次接入未知 Server 时，优先只开放当前任务需要的只读工具并保留提示；不要为了减少确认次数默认批准写入、删除、付款、发布或权限变更。

配置完成后如何验证，而不是直接拿生产数据测试

1. 检查配置是否被读取

   运行 codex mcp list，确认名称、状态和预期 Server 一致。

2. 在 TUI 中查看 /mcp

   确认当前会话实际看到哪些 Server 与工具；配置文件里存在不等于当前 host 已加载成功。

3. 先调用一个低风险只读工具

   使用公开文档或测试项目，确认输入、输出、审批和日志符合预期。

4. 核对数据边界

   确认没有意外读取其他目录、账号、仓库、浏览器会话或环境变量。

5. 记录版本和来源

   保存 Codex、Server、runtime 和包版本；自动使用 latest 依赖时尤其需要可追溯。

6. 失败时保留第一条错误

   记录 Server stderr、退出码或 HTTP 状态，再进入启动、握手、认证或工具超时分流。

ChatGPT 桌面端、Codex CLI 与 IDE 会共用配置吗

OpenAI 当前文档说明，同一个 Codex host 上的 ChatGPT 桌面端、Codex CLI 和 IDE 扩展共享 MCP 配置。配置一次后可以在这些客户端之间切换，不必分别复制一遍。

“同一个 host”是关键：本机、WSL、SSH 远端、Dev Container 和另一台电脑可能拥有不同的 home、runtime、PATH 与配置文件。Windows 本机 CLI 里配置的 STDIO 命令不会自动出现在 WSL；远程 SSH 扩展也不能假定能启动本机路径下的 Server。

ChatGPT 网页里的 MCP 与本地 Codex 有什么不同

ChatGPT 网页可以使用由 Plugin 提供的远程 MCP-backed tools；本地 Codex 客户端则可以直接连接配置在 host 上的 MCP Server。托管 Plugin 工具可能有不同的认证、安装和权限能力，不能把一段本地 [mcp_servers] TOML 当作网页插件安装方式。

Plugin 自带 MCP Server 怎么控制

安装的 Plugin 可以在 manifest 中捆绑 MCP Server，用户配置不需要重复写传输命令；仍可以在 plugins.<plugin>.mcp_servers.<server> 下控制启用状态、工具范围和审批。先确认 Server 来源于 Plugin 还是手写配置，避免创建同名重复连接。

安装 MCP Server 前的 10 项安全清单

1. 找到维护者的官方仓库或文档，核对包名、域名和发布记录。
2. 阅读安装命令和依赖，不运行来源不明的脚本、二进制或复制粘贴命令。
3. 查看 Server 提供的全部工具，特别关注写入、删除、发布、支付和权限管理。
4. 只开放任务需要的目录、仓库、账号和工具；从只读与提示模式开始。
5. Token 使用环境变量或批准的凭证机制，不提交到 Git、Issue、聊天或截图。
6. 远程 Server 核对 HTTPS 域名、服务主体、隐私政策与数据保留。
7. STDIO Server 核对 command、args、cwd、runtime 和 PATH。
8. 在非生产项目做首次测试，观察真实读取、写入和网络请求。
9. 记录版本并定期重新审查；热门仓库、下载量和视频推荐都不是安全证明。
10. 不再使用时禁用或删除 Server，并撤销 OAuth 或 Token，而不是只隐藏 UI。

Sandbox 与 Approval 仍然有效。Server 能列出某个工具不代表它必然能越过 Codex、操作系统或组织策略；相反，工具通过审批也不代表第三方 Server 本身已经可信。权限问题请进入Codex Sandbox 与 permission denied 排查。

Codex MCP 配置常见问题

Codex MCP 怎么添加？

优先使用 codex mcp add server-name -- server-command；添加后运行 codex mcp list，进入 TUI 后用 /mcp 检查。需要细粒度字段时再编辑 config.toml。

Codex MCP 配置文件在哪里？

默认是 ~/.codex/config.toml。可信项目也可使用项目级 .codex/config.toml。本机、WSL、SSH 与容器可能使用不同 host 和 home，应在实际运行环境检查。

Codex MCP 使用 JSON 还是 TOML？

Codex 的用户配置使用 TOML，每个手动 Server 放在 [mcp_servers.<server-name>] 表中。不要把其他客户端的 JSON 配置原样粘贴到 Codex。

Codex MCP 支持 STDIO 和 HTTP 吗？

支持本地 STDIO Server 和远程 Streamable HTTP Server。STDIO 使用 command/args，HTTP 使用 url 并可配 OAuth、bearer token 环境变量或 Header。

Codex MCP 配置后怎么查看是否成功？

运行 codex mcp list，在 TUI 使用 /mcp 查看当前 Server 与工具，再用公开测试数据调用一个低风险只读工具。

Codex VS Code 扩展需要单独配置 MCP 吗？

同一个 Codex host 上，桌面端、CLI 与 IDE 扩展共享 MCP 配置；Local、WSL、SSH、容器或不同电脑属于不同环境时要分别核对。

MCP OAuth 怎么登录？

配置支持 OAuth 的 HTTP Server 后运行 codex mcp login server-name。核对授权域名和 scopes，不转发 callback、授权码、Cookie 或 Token。

Token 应该直接写进 config.toml 吗？

不建议。Bearer Token 应通过 bearer_token_env_var 引用环境变量；敏感 Header 优先使用 env_http_headers。不要把真实值提交到仓库。

MCP Server 可以临时关闭吗？

可以设置 enabled = false，无需立即删除整段配置。若已经授权远程服务，还应按服务商流程撤销 OAuth 或 Token。

添加 MCP Server 会消耗更多 Codex 额度吗？

MCP 工具可能增加上下文和任务步骤，但配置失败、命令不存在、OAuth 401/403 或 tool timeout 不是靠充值直接修复的问题。先解决技术错误，再根据 Usage Dashboard 判断真实用量。

网上的 MCP 配置可以直接复制吗？

不应直接复制整份。至少核对维护者、包名或域名、命令、环境变量、工具列表、审批方式、配置日期和当前官方字段，再只合并任务需要的部分。