接入 MCP 工具和上下文

Model Context Protocol（MCP，模型上下文协议）把模型连接到工具和上下文。

你可以用 MCP 让 Codex 访问第三方文档，也可以让它操作开发工具，例如浏览器或 Figma。

Codex 在 CLI 和 IDE extension 中都支持 MCP servers（MCP 服务器）。

支持的 MCP 功能

STDIO servers：作为本地进程运行的服务器，由命令启动。
- 支持环境变量。
Streamable HTTP servers：通过某个地址访问的服务器。
- 支持 bearer token authentication（Bearer Token 认证）。
- 支持 OAuth authentication（OAuth 认证）。如果服务器支持 OAuth，运行 codex mcp login <server-name> 登录。

把 Codex 连接到 MCP server

Codex 把 MCP 配置和其他 Codex 配置一起存放在 config.toml 中。默认位置是：

~/.codex/config.toml

你也可以用项目级 .codex/config.toml 把 MCP servers 限定在某个项目里。项目级配置只会在 trusted projects（受信任项目）中加载。

CLI 和 IDE extension 共享这份配置。配置好 MCP servers 之后，你可以在两个 Codex 客户端之间切换，不需要重复设置。

配置 MCP servers 有两种方式：

使用 CLI：运行 codex mcp 添加和管理 servers。
编辑 config.toml：直接更新 ~/.codex/config.toml，或在受信任项目里更新项目级 .codex/config.toml。

用 CLI 配置

添加 MCP server

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

例如，添加 Context7。Context7 是一个免费的开发者文档 MCP server：

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

其他 CLI 命令

查看所有可用 MCP 命令：

codex mcp --help

Terminal UI（TUI）

在 codex TUI 中，使用 /mcp 查看当前 active MCP servers（活跃 MCP 服务器）。

用 config.toml 配置

如果你需要更细粒度地控制 MCP server 选项，可以编辑 ~/.codex/config.toml，或项目级 .codex/config.toml。

在 IDE extension 里，可以从齿轮菜单选择：

MCP settings > Open config.toml

每个 MCP server 都使用配置文件里的 [mcp_servers.<server-name>] table 配置。

STDIO servers

command（必填）：启动 server 的命令。
args（可选）：传给 server 的参数。
env（可选）：为 server 设置的环境变量。
env_vars（可选）：允许并转发的环境变量。
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 executor environment（远程执行器环境）读取，并且需要 remote MCP stdio。

Streamable HTTP servers

url（必填）：server 地址。
bearer_token_env_var（可选）：环境变量名。Codex 会从这个变量读取 bearer token，并放进 Authorization。
http_headers（可选）：header name 到静态值的映射。
env_http_headers（可选）：header name 到环境变量名的映射。值从环境变量读取。

其他配置选项

startup_timeout_sec（可选）：server 启动超时时间，单位秒。默认 10。
tool_timeout_sec（可选）：server 运行工具的超时时间，单位秒。默认 60。
enabled（可选）：设置为 false 时禁用 server，但不删除配置。
required（可选）：设置为 true 时，如果这个已启用 server 无法初始化，Codex 启动失败。
enabled_tools（可选）：tool allow list（工具允许列表）。
disabled_tools（可选）：tool deny list（工具拒绝列表）。它会在 enabled_tools 之后应用。

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

如果你的 MCP OAuth 流程必须使用特定 callback URL，例如 remote Devbox ingress URL 或自定义 callback path，可以设置 mcp_oauth_callback_url。Codex 会把这个值作为 OAuth redirect_uri，同时仍然用 mcp_oauth_callback_port 作为 callback listener port。

local callback URLs，例如 localhost，会绑定本地接口。非本地 callback URLs 会绑定 0.0.0.0，让 callback 能到达主机。

如果 MCP server 声明了 scopes_supported，Codex 在 OAuth 登录时会优先使用 server 声明的 scopes。否则，Codex 会回退使用 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
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

有用的 MCP servers 示例

MCP servers 的列表还在持续增长。下面是一些常见选择：

OpenAI Docs MCP：搜索和阅读 OpenAI developer docs。
Context7：连接到最新开发者文档。
Figma Local 和 Remote：访问 Figma designs（Figma 设计稿）。
Playwright：用 Playwright 控制和检查浏览器。
Chrome Developer Tools：控制和检查 Chrome。
Sentry：访问 Sentry logs。
GitHub：管理 git 之外的 GitHub 能力，例如 pull requests 和 issues。

On this page