古法编程

OpenAI Codex 通过 MCP（Model Context Protocol）连接第三方文档和工具，适合接入浏览器、Figma、Sentry、GitHub 等服务。先用 codex mcp add 或编辑 config.toml 完成配置，再按需设置 OAuth、enabled_tools、disabled_tools 和超时参数，CLI 与 IDE 扩展会共享同一份配置。

OpenAI Codex MCP 配置与接入教程

Model Context Protocol（MCP）把模型和工具、上下文连接起来。OpenAI Codex 支持在 CLI 和 IDE extension 中使用 MCP server，用来访问第三方文档，或让 Codex 与 browser、Figma 等开发工具交互。

CLI 和 IDE extension 共享同一份 MCP 配置。配置完成后，可以在两个客户端之间切换，不需要重复设置。

支持的 MCP 功能

  • STDIO servers：以本地进程运行，由命令启动。
    • Environment variables
  • Streamable HTTP servers：通过地址访问的服务器。
    • Bearer token authentication
    • OAuth authentication（对支持 OAuth 的服务器运行 codex mcp login <server-name>）

怎么把 Codex 接入 MCP server

Codex 会把 MCP 配置存放在 config.toml 里，和其他 Codex 配置共用一处。默认路径是 ~/.codex/config.toml；如果是受信任项目，也可以使用项目级的 .codex/config.toml。

可选范围如下：

  • 全局：~/.codex/config.toml
  • 项目级：.codex/config.toml（仅受信任项目）

配置方式有两种：

  1. 使用 CLI：运行 codex mcp 添加和管理服务器。
  2. 直接编辑 config.toml：手动修改 ~/.codex/config.toml，或在受信任项目里修改 .codex/config.toml。

怎么用 CLI 配置 MCP

添加 MCP server 

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

例如，添加 Context7 这个免费的开发者文档 MCP server，可以这样运行：

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

其他 CLI 命令

查看所有可用的 MCP 命令：

codex mcp --help

Terminal UI（TUI）里怎么看当前 MCP server

在 codex TUI 中，输入 /mcp 可以查看当前启用的 MCP servers。

怎么用 config.toml 配置 MCP

如果你需要更细的控制，可以直接编辑 ~/.codex/config.toml，或者在受信任项目里编辑 .codex/config.toml。

在 IDE extension 中，也可以从齿轮菜单进入 MCP settings > Open config.toml。

每个 MCP server 都用配置文件里的 [mcp_servers.<server-name>] 表来定义。

STDIO servers

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

env_vars 可以是普通变量名，也可以是带 source 的对象：

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

字符串项和 source = "local" 会从 Codex 的本地环境读取。 source = "remote" 会从远程执行环境读取，并且需要 remote MCP stdio。

Streamable HTTP servers

  • url（必填）：server 地址。
  • bearer_token_env_var（可选）：Bearer token 所在的环境变量名，Codex 会把它放进 Authorization。
  • http_headers（可选）：静态请求头映射。
  • env_http_headers（可选）：从环境变量读取请求头值的映射。

其他配置项

  • startup_timeout_sec（可选）：server 启动超时，单位秒。默认 10。
  • tool_timeout_sec（可选）：工具运行超时，单位秒。默认 60。
  • enabled（可选）：设为 false 可以禁用 server，但不删除配置。
  • required（可选）：设为 true 时，如果这个已启用的 server 无法初始化，启动会失败。
  • enabled_tools（可选）：工具白名单。
  • disabled_tools（可选）：工具黑名单，会在 enabled_tools 之后再应用。
  • default_tools_approval_mode（可选）：这个 server 的工具默认审批方式。支持 auto、prompt、approve。
  • tools.<tool>.approval_mode（可选）：覆盖某个具体工具的审批方式。

如果 OAuth provider 需要固定回调端口，可以在 config.toml 顶层设置 mcp_oauth_callback_port。如果不设置，Codex 会绑定一个临时端口。

如果 MCP OAuth 流程必须使用指定回调 URL，例如 remote Devbox ingress URL 或自定义 callback path，可以设置 mcp_oauth_callback_url。Codex 会把它作为 OAuth 的 redirect_uri，同时仍然使用 mcp_oauth_callback_port 作为回调监听端口。局部回调 URL（例如 localhost）会绑定到本地接口；非局部回调 URL 会绑定到 0.0.0.0，这样回调才能到达主机。

如果 MCP server 声明了 scopes_supported, Codex 会在 OAuth login 时优先使用 server 广播的 scopes；否则会回退到 config.toml 里配置的 scopes。

config.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"
# 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
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

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

插件提供的 MCP servers

已安装的插件可以在插件清单里打包 MCP servers。这样的 server 会由插件启动，所以用户配置里不需要再写 transport command。用户配置仍然可以通过 plugins.<plugin>.mcp_servers.<server> 控制启用状态和工具策略。

[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 servers

MCP server 的列表还在增长，下面是一些常见选项：

常见问题

OpenAI Codex 怎么添加 MCP server

可以用 codex mcp add <server-name> -- <stdio server-command> 快速添加，也可以直接编辑 ~/.codex/config.toml 或受信任项目里的 .codex/config.toml。CLI 和 IDE extension 会共享同一份配置。

enabled_tools 和 disabled_tools 有什么区别

enabled_tools 是白名单，先列出允许的工具；disabled_tools 是黑名单，会在白名单之后再次排除工具。这样可以只开放一部分 MCP 工具给 Codex 用。

Codex MCP 的 OAuth 登录怎么做

对支持 OAuth 的 server 运行 codex mcp login <server-name>。如果 provider 需要固定回调端口或自定义回调 URL，可以在 config.toml 顶层设置 mcp_oauth_callback_port 和 mcp_oauth_callback_url。