OpenAI Codex 中文文档（4.14更新）
联系我 ↗
官方文档 ↗

模型上下文协议（MCP）

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

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

Codex CLI 和 IDE 扩展都支持 MCP 服务端。

支持的 MCP 能力

  • STDIO 服务端： 以本地进程方式运行、通过命令启动的服务端。
    • 支持环境变量
  • 流式 HTTP 服务端： 通过固定地址访问的服务端。
    • 支持 Bearer token 认证
    • 支持 OAuth 认证；对于支持 OAuth 的服务端，可以运行 codex mcp login <server-name>

将 Codex 连接到 MCP 服务端

Codex 会把 MCP 配置和其他设置一起保存在 config.toml 中。默认位置是 ~/.codex/config.toml；你也可以把 MCP 服务端配置在项目级 .codex/config.toml 中，但只有在该项目被标记为可信时才会生效。

CLI 和 IDE 扩展共享这一份配置。也就是说，MCP 服务端只需配置一次，就可以在两个 Codex 客户端之间切换使用，而无需重复设置。

配置 MCP 服务端有两种方式：

  1. 使用 CLI： 运行 codex mcp 来添加和管理服务端。
  2. 直接编辑 config.toml： 直接修改 ~/.codex/config.toml，或可信项目中的 .codex/config.toml。

使用 CLI 配置

添加 MCP 服务端

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

例如，如果要添加 Context7 这个面向开发文档的免费 MCP 服务端，可以运行：

codex mcp add context7 -- npx -y @upstash/context7-mcp

其他 CLI 命令

如果你想查看所有 MCP 子命令，可以运行 codex mcp --help。

终端界面（TUI）

在 codex TUI 中，可以使用 /mcp 查看当前激活的 MCP 服务端。

使用 config.toml 配置

如果你需要更细粒度的控制，可以直接编辑 ~/.codex/config.toml，或项目级 .codex/config.toml。在 IDE 扩展中，可以从齿轮菜单进入 MCP settings，然后选择 Open config.toml。

每个 MCP 服务端都通过一个 [mcp_servers.<server-name>] 表来定义。

STDIO 服务端

  • command（必填）：启动该服务端的命令。
  • args（可选）：传给服务端的参数。
  • env（可选）：为服务端设置的环境变量。
  • env_vars（可选）：允许转发给服务端的环境变量名。
  • cwd（可选）：启动服务端时使用的工作目录。

流式 HTTP 服务端

  • url（必填）：服务端地址。
  • bearer_token_env_var（可选）：要放进 Authorization 头里的 bearer token 所对应的环境变量名。
  • http_headers（可选）：静态 HTTP headers 映射。
  • env_http_headers（可选）：从环境变量取值的 HTTP headers 映射。

其他配置项

  • startup_timeout_sec（可选）：服务端启动超时，单位为秒；默认是 10。
  • tool_timeout_sec（可选）：单次工具调用超时，单位为秒；默认是 60。
  • enabled（可选）：设为 false 可在保留配置的同时停用该服务端。
  • required（可选）：设为 true 时，如果这个已启用的服务端无法初始化，Codex 启动会直接失败。
  • enabled_tools（可选）：工具允许列表。
  • disabled_tools（可选）：工具 denylist；会在 enabled_tools 之后应用。

如果你的 OAuth 提供方要求固定回调端口，可以在 config.toml 顶层设置 mcp_oauth_callback_port。如果不设置，Codex 会绑定一个临时端口。

如果你的 MCP OAuth 流程必须使用固定回调地址，例如远程 devbox 的 ingress URL 或自定义回调路径，可以设置 mcp_oauth_callback_url。Codex 会把它用作 OAuth 的 redirect_uri，同时仍使用 mcp_oauth_callback_port 控制本地监听端口。本地回调地址，例如 localhost，会绑定到 loopback；非本地回调地址则会绑定到 0.0.0.0，以便回调可以从外部访问到宿主机。

如果 MCP 服务端声明了“支持的权限范围”（scopes_supported），Codex 在 OAuth 授权登录时会优先使用服务端声明的“权限范围”（scopes）；只有在服务端没有声明时，才会回退到 config.toml 中配置的权限范围。

config.toml 示例

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"
# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

常见的 MCP 服务端示例

MCP 服务端的生态还在持续扩展。下面是一些常见示例：

  • OpenAI Docs MCP：搜索和读取 OpenAI 开发者文档。
  • Context7：连接到保持最新的开发者文档。
  • Figma Local 和 Remote：访问你的 Figma 设计稿。
  • Playwright：通过 Playwright 控制并检查浏览器。
  • Chrome Developer Tools：控制并检查 Chrome。
  • Sentry：访问 Sentry 日志。
  • GitHub：完成 git 之外的 GitHub 操作，例如 pull request 和 issue 管理。

来源：https://developers.openai.com/codex/mcp