模型上下文协议（MCP）

模型上下文协议（MCP）

为 ChatGPT 和 Codex 配置 MCP server，覆盖桌面应用、config.toml、STDIO、Streamable HTTP、OAuth、ChatGPT 会话认证、环境变量、工具白名单、审批模式、超时、plugin 内置 MCP 与常见集成。

模型上下文协议（MCP）#

Codex 中文站说明： 本页围绕“模型上下文协议（MCP）”重新补充了中文使用场景和验证重点。界面名称可能随 Codex 版本更新，请以当前客户端为准。

让 Codex 访问第三方工具和上下文

Model Context Protocol（MCP）把模型连接到工具和上下文。你可以用它让 ChatGPT 或 Codex 访问第三方文档，也可以让它们与浏览器、Figma 等开发工具交互。

ChatGPT Web 可以使用 plugins 提供的远程 MCP 工具。本地 Codex 客户端还可以直接连接 MCP server，并共享配置。

ChatGPT 桌面应用、Codex CLI 和 IDE 扩展均支持 MCP server，并为同一台 Codex 主机共享 MCP 配置。

下面列出的 server 功能适用于配置在 Codex 主机上的 MCP server。托管 plugin 工具可能支持不同能力。

支持的 MCP 能力#

  • STDIO server：以本地进程运行，由命令启动。
  • 环境变量
  • Streamable HTTP server：通过地址访问。
  • Bearer token 认证
  • OAuth 认证
  • 可信第一方 server 的 ChatGPT 会话认证
  • Server instructions：Codex 会读取 MCP server 初始化时返回的 instructions 字段，并将其与 server 工具一起作为 server 级指导。

如果你为 Codex 构建或维护 MCP server，请使用 instructions 描述适用于整个 server 的跨工具工作流、约束和速率限制。前 512 个字符应能独立表达最重要的指导，以便 Codex 决定如何使用该 server 时直接获得关键信息。

将 Codex 连接到 MCP server#

Codex 会把 MCP 配置与其他设置一起保存在 config.toml 中。默认文件是 ~/.codex/config.toml；在可信项目中，也可以通过 .codex/config.toml 把 MCP server 限定到项目范围。

ChatGPT 桌面应用、Codex CLI 和 IDE 扩展共享该配置。完成设置后，可以在这些客户端之间切换，无需重新配置。

在 ChatGPT 桌面应用中配置#

  1. 打开 Settings（设置），选择 MCP servers。
  2. 选择 Add server。
  3. 输入名称，选择 STDIO 或 Streamable HTTP，再填写 server 的命令或 URL。
  4. 保存 server，然后选择 Restart。

Server 列表会显示哪些 server 已启用，哪些需要 OAuth。OAuth server 需要登录时，选择 Authenticate。在 composer（输入框）中输入 /mcp 可以查看已连接的 server。

使用 config.toml 配置#

需要更细粒度的控制时，编辑 ~/.codex/config.toml 或项目级 .codex/config.toml。每个 MCP 选项都可以在配置参考中搜索。

在配置文件中，使用 [mcp_servers.] 表配置每个 MCP server。

STDIO server#

  • command（必填）：启动 server 的命令。
  • args（可选）：传给 server 的参数。
  • env（可选）：为 server 设置的环境变量。
  • env_vars（可选）：允许并转发的环境变量。
  • cwd（可选）：启动 server 时使用的工作目录。
  • experimental_environment（可选）：设为 remote 后，在可用时通过远程执行器环境启动 STDIO server。

env_vars 可以包含普通变量名，也可以包含带来源的对象：

toml
env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

字符串条目和 source = "local" 从 Codex 本地环境读取；source = "remote" 从远程执行器环境读取，并要求支持 remote MCP STDIO。

Streamable HTTP server#

  • url（必填）：server 地址。
  • auth（可选）：在已配置的 bearer token 和 authorization headers 之后尝试的认证方式。使用 oauth（默认）读取已保存的 MCP OAuth 凭据；使用 chatgpt 可让可信的第一方 ChatGPT origin 使用当前 ChatGPT 会话，并把已保存 OAuth 作为回退。
  • bearer_token_env_var（可选）：用于读取 bearer token 并放入 Authorization 的环境变量名。
  • http_headers（可选）：静态 header 名和值的映射。
  • env_http_headers（可选）：header 名与环境变量名的映射，值从环境读取。

如果没有可用凭据来源，Codex 仍可以尝试在无认证状态下连接。请单独运行 codex mcp login 来启动 MCP OAuth 登录。

其他配置项#

  • startup_timeout_sec（可选）：server 启动超时，单位为秒，默认 10。
  • tool_timeout_sec（可选）：server 运行工具的超时，单位为秒，默认 60。
  • enabled（可选）：设为 false 可以禁用 server 而不删除配置。
  • required（可选）：设为 true 后，如果已启用 server 无法初始化，Codex 启动也会失败。
  • enabled_tools（可选）：工具允许列表。
  • disabled_tools（可选）：工具拒绝列表，在 enabled_tools 之后应用。
  • default_tools_approval_mode（可选）：此 server 工具的默认审批行为。支持 auto、prompt、writes 和 approve。writes 会对未标记为只读的工具请求审批。
  • tools..approval_mode（可选）：按工具覆盖审批行为。

如果 OAuth 提供商要求固定 callback 端口，请在 config.toml 顶层设置 mcp_oauth_callback_port；未设置时，Codex 会绑定临时端口。

如果 MCP OAuth 流程必须使用特定 callback URL，例如远程 Devbox ingress URL 或自定义 callback 路径，请设置 mcp_oauth_callback_url。Codex 会把它作为基础 callback URL，再附加 server 专属 callback ID，生成登录时使用的 OAuth redirect_uri。向 OAuth 提供商注册时，应使用包含附加 callback ID、已配置路径、查询参数和端口的完整 redirect_uri，而不是没有后缀的基础 host 或路径。本地 callback URL（例如 localhost）绑定本地接口；非本地 URL 绑定 0.0.0.0，使 callback 能到达主机。

如果 MCP server 声明了 scopes_supported，Codex 会在 OAuth 登录时优先使用 server 声明的 scopes；否则回退到 config.toml 中配置的 scopes。

config.toml 示例#

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
toml
# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"
toml
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
toml
[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"

Plugin 提供的 MCP server#

已安装 plugin 可以在 plugin manifest 中打包 MCP server。这类 server 由 plugin 启动，因此用户配置不需要设置 transport 命令；用户仍可通过 plugins..mcp_servers. 控制启用状态和工具策略。

toml
[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

常用 MCP server 示例#

MCP server 列表仍在持续增长，常见选项包括：

本站实践建议#

使用“模型上下文协议（MCP）”扩展 Codex 时，只启用当前任务需要的能力，并检查其可访问的数据与可执行操作。团队共享前应先完成权限和失败场景测试。

Codex API 与国内使用#

在实践“模型上下文协议（MCP）”相关功能时，如需为 Codex 配置 OpenAI-compatible API，可以前往 APIBest 获取 API Key。第三方服务的模型映射、价格、额度和数据处理方式以 APIBest 当前说明为准。