Codex MCP 配置教程：为 OpenAI Codex 添加 MCP 服务器（2026）

如何为 Codex 添加 MCP 服务器

要把 MCP 服务器接入 OpenAI Codex，本地（stdio）服务器运行 codex mcp add <name> -- <command>，远程（streamable HTTP）服务器运行 codex mcp add <name> --url <https-url>，然后在 Codex 中输入 /mcp 确认已连接。每个条目都会以 [mcp_servers.<name>] 表的形式保存在 ~/.codex/config.toml 中，而这一个文件由 Codex CLI、IDE 扩展以及 ChatGPT 桌面应用中的 Codex 共享。

本文覆盖截至 2026 年 10 月的完整流程：CLI 命令、config.toml 的具体配置键、OAuth 登录、超时与工具审批，以及一个会让旧教程失效的变化——codex mcp-server（把 Codex 本身作为 MCP 服务器运行）已被移除。以下内容均已对照官方 Codex MCP 文档 和 Codex CLI 参考 核实。

Codex MCP 配置存放在哪里

Codex 把 MCP 服务器存放在它的常规配置文件中：

ChatGPT 桌面应用（已于 2026 年 7 月并入原独立的 Codex 应用）、Codex CLI 和 IDE 扩展，对同一个 Codex 主机读取的是同一份配置。在终端里配置一次服务器，它也会出现在应用和扩展中。

如果你还没有安装 CLI，macOS 和 Linux 的官方安装命令是：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

方式一：用 codex mcp add 添加服务器

CLI 是最快的方式。本地 stdio 服务器就是 Codex 作为子进程启动的任何程序——通常是 npx、uvx 或 docker 命令。把启动命令放在 -- 之后：

# Context7: up-to-date library docs for coding agents
codex mcp add context7 -- npx -y @upstash/context7-mcp

用 --env 传入环境变量（可重复使用）：

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

远程服务器用 --url 代替命令，两者互斥：

# OpenAI's public docs server (no auth)
codex mcp add openaiDocs --url https://developers.openai.com/mcp

# A server that expects a bearer token from an env var
codex mcp add example --url https://mcp.example.com/mcp --bearer-token-env-var EXAMPLE_TOKEN

codex mcp 系列的其他命令：

在交互式 codex 会话中，/mcp 列出活跃的服务器和工具，/mcp verbose 额外显示每个服务器的诊断信息，/mcp login <name> 则让你无需离开会话即可登录。

方式二：使用 ChatGPT 桌面应用或 IDE 扩展

如果你更喜欢用表单而不是终端：

• ChatGPT 桌面应用： Settings → MCP servers → Add server。输入名称，选择 STDIO 或 Streamable HTTP，填写命令或 URL，保存后选择 Restart（重启）。需要 OAuth 的服务器会显示 Authenticate（认证）按钮。
• IDE 扩展： 齿轮菜单 → MCP servers → Add server，保存后选择 Restart extension（重启扩展）。

两者写入的都是同一个 config.toml，所以可以混合使用。注意，网页版 ChatGPT 不会读取你本地的 Codex 配置——它通过已安装的插件获取 MCP 工具。如果你需要的是这个，请参阅我们的 ChatGPT MCP 配置指南。

方式三：直接编辑 config.toml

超出基础用法的配置——工具允许列表、审批模式、超时——都需要编辑文件。每个服务器对应一个表。

stdio 服务器

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]          # forward this variable from your shell

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"         # set a fixed value for the server

stdio 配置键：command（必填）、args、env（固定值）、env_vars（允许从你的环境中转发的变量名）以及 cwd（工作目录）。

streamable HTTP 服务器

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

HTTP 配置键：url（必填）、bearer_token_env_var（以 Authorization: Bearer ... 发送）、http_headers（静态请求头）、env_http_headers（请求头名称映射到环境变量名）、http_headers_helper（一个输出 JSON 请求头对象的本地命令，在遇到 401 或 403 后刷新一次），以及 auth——默认为 oauth，也可设为 chatgpt，以便对受信任的第一方服务器复用你的 ChatGPT 会话。如果都无法解析，Codex 会在不带凭据的情况下连接。

超时、工具过滤与审批

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]      # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

顶层的 mcp_optional_startup_grace_ms（默认 1000）控制 Codex 在构建首个工具列表前等待可选服务器的时长；设为 0 则会等待每个服务器完整的 startup_timeout_sec。

远程 MCP 服务器的 OAuth

许多托管服务器——例如 Sentry、Notion 和 Linear——使用 OAuth 而非静态令牌让你登录。在 Codex 中的流程是：

1. 用 --url 添加服务器。
2. 运行 codex mcp login <name>（或在应用中点击 Authenticate）。浏览器窗口会打开，Codex 在本地回环回调地址上监听，例如 http://127.0.0.1/callback。
3. 批准访问。Codex 会保存凭据并重复使用。

Codex 会自动注册自身：当授权服务器声明支持时优先使用 Client ID Metadata Documents（CIMD），否则回退到 Dynamic Client Registration（DCR）。你可以在单次登录中强制使用其中一种：

codex mcp login <server-name> --oauth-client-registration dcr

如果你的身份提供方要求使用预先注册的客户端，请在添加服务器时传入。Codex 会打印出需要在提供方处注册的准确回调 URL：

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client
# confidential client: read the secret from an env var
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

密钥会保存到 config.toml 中的 mcp_servers.example.oauth.client_secret，所以不要把该文件纳入版本控制。对于远程开发机，可以用全局的 mcp_oauth_callback_port 和 mcp_oauth_callback_url 设置固定回调地址。关于这一流程的协议细节，请阅读我们的 MCP 认证与 OAuth 指南。

Codex 能作为 MCP 服务器运行吗？

现在不行了。旧教程会让你运行 codex mcp-server，以便其他 Agent 通过 MCP 驱动 Codex。该命令已于 2026 年 8 月 24 日弃用，并与独立的 codex-mcp-server 二进制文件一起，于 2026 年 9 月 5 日移除。OpenAI 的替代方案是 Codex app server，它使用自己的 JSON-RPC 协议（不是 MCP），目前仍标记为实验性功能。如果某个 Agents SDK 脚本或编排工具会启动 codex mcp-server，请在升级前锁定旧版 Codex 或完成迁移。Codex 作为 MCP 客户端——也就是本文其余所有内容——不受影响。

适合 Codex 入门的服务器

先从两三个开始。每个启用的服务器都会往上下文里添加工具定义，而功能重叠的工具会让工具选择变差——参见 MCP 客户端如何发现工具。

Codex MCP 故障排查

• 首次运行时提示“Server failed to start”或超时。 npx -y 和 uvx 会在首次启动时下载软件包，耗时可能超过默认的 10 秒。把 startup_timeout_sec 调到 30–60，或预先安装软件包。
• 服务器已启动但缺少工具。 运行 /mcp verbose。检查 enabled_tools 和 disabled_tools——拒绝列表优先。
• API 密钥没有传到服务器。 把变量名加入 env_vars，或在 [mcp_servers.<name>.env] 下设置。对于 HTTP 服务器，使用 bearer_token_env_var，并确保该变量已在启动 Codex 的 shell 中导出。
• 项目级服务器被忽略。 .codex/config.toml 只有在项目受信任时才会加载。
• 长时间运行的工具被中断。 只针对该服务器调高 tool_timeout_sec。
• OAuth 循环或 invalid redirect_uri。 注册 codex mcp add 打印出的准确回调地址，包括任何服务器专属的回调 ID。
• 在 Codex 之外调试服务器。 如果某个服务器表现异常，先用 MCP Inspector 单独排查，再考虑是不是客户端的问题。

在给第三方服务器写入权限之前，请阅读我们的 MCP 安全最佳实践，并优先使用 default_tools_approval_mode = "writes" 或 "prompt"。

Codex 与 Claude Code 的 MCP 配置速览

服务器软件包是相同的，变的只是外层配置。另一边的做法请看我们的 Claude Code MCP 指南。

下一步

从 MCP 服务器目录 中挑选一个服务器，用 codex mcp add 添加，再用 /mcp 确认。按 分类 浏览，找到适合你技术栈的服务器，或者比较其他可以共享同一批服务器的 MCP 客户端。