MCP 模型上下文协议

模型上下文协议 (MCP) 将模型与工具及上下文连接起来。使用它可以让 Codex 访问第三方文档，或者让其与您的浏览器或 Figma 等开发人员工具进行交互。

Codex 在 CLI 和 IDE 扩展中均支持 MCP 服务器。

支持的 MCP 功能

• STDIO 服务器：作为本地进程运行的服务器（通过命令启动）。

  • 环境变量

• 流式 HTTP 服务器：您通过某个地址访问的服务器。

  • Bearer 令牌认证
  • OAuth 认证（对于支持 OAuth 的服务器，运行 codex mcp login <server-name>）

• 服务器指令：Codex 会读取在初始化期间返回的 MCP instructions 字段，并将其与服务器的工具一起用作服务器范围的指导。

如果您为 Codex 构建或维护 MCP 服务器，请将 instructions 用于适用于整个服务器的跨工具工作流、约束和速率限制。将前 512 个字符保持自包含，以便在 Codex 决定如何使用服务器时能够获得最重要的指导。

将 Codex 连接到 MCP 服务器

Codex 将 MCP 配置存储在 config.toml 中，与其他 Codex 配置设置并列。默认情况下该文件为 ~/.codex/config.toml，但您也可以通过 .codex/config.toml 将 MCP 服务器的作用域限定在某个项目内（仅限受信任的项目）。

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 进行配置

如需对 MCP 服务器选项进行更精细的控制，请编辑 ~/.codex/config.toml（或项目级的 .codex/config.toml）。在 IDE 扩展中，从齿轮菜单中选择 MCP settings > Open config.toml。

在配置文件中使用 [mcp_servers.<server-name>] 表来配置每个 MCP 服务器。

STDIO 服务器

• command（必需）：启动服务器的命令。
• args（可选）：传递给服务器的参数。
• env（可选）：为服务器设置的环境变量。
• env_vars（可选）：允许并转发的环境变量。
• cwd（可选）：启动服务器的工作目录。
• experimental_environment（可选）：设置为 remote，以便在有远程执行器环境可用时通过该环境启动 stdio 服务器。

env_vars 可以包含纯变量名或带有来源的对象：

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

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

流式 HTTP 服务器

• url（必需）：服务器地址。
• bearer_token_env_var（可选）：在 Authorization 中发送的 Bearer 令牌的环境变量名称。
• http_headers（可选）：标头名称到静态值的映射。
• env_http_headers（可选）：标头名称到环境变量名称的映射（值从环境中提取）。

其他配置选项

• startup_timeout_sec（可选）：服务器启动的超时时间（秒）。默认值：10。
• tool_timeout_sec（可选）：服务器运行工具的超时时间（秒）。默认值：60。
• enabled（可选）：设置为 false 以禁用服务器而不删除它。
• required（可选）：设置为 true，使得当该启用的服务器无法初始化时导致启动失败。
• enabled_tools（可选）：工具允许列表。
• disabled_tools（可选）：工具拒绝列表（在 enabled_tools 之后应用）。
• default_tools_approval_mode（可选）：此服务器工具的默认审批行为。支持的值包括 auto、prompt 和 approve。
• tools.<tool>.approval_mode（可选）：针对单个工具的审批行为重写。

如果您的 OAuth 提供商需要固定的回调端口，请在 config.toml 中设置顶级 mcp_oauth_callback_port。如果未设置，Codex 将绑定到一个临时端口。

如果您的 MCP OAuth 流程必须使用特定的回调 URL（例如，远程 Devbox 入口 URL 或自定义回调路径），请设置 mcp_oauth_callback_url。Codex 将使用此值作为 OAuth redirect_uri，同时仍使用 mcp_oauth_callback_port 作为回调监听端口。本地回调 URL（例如 localhost）绑定在本地接口上；非本地回调 URL 绑定在 0.0.0.0 上，以便回调可以到达主机。

如果 MCP 服务器播发了 scopes_supported，Codex 会在 OAuth 登录期间优先使用这些服务器播发的 scope。否则，Codex 将回退到 config.toml 中配置的 scope。

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"

# 可选的 MCP OAuth 回调重写（由 `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"] # 在 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 服务器

已安装的插件可以在其插件清单中捆绑 MCP 服务器。这些服务器由插件启动，因此用户配置不需要设置它们的传输命令。用户配置仍然可以在 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 服务器示例

MCP 服务器的列表一直在增长。以下是一些常见的服务器：

• OpenAI Docs MCP：搜索并阅读 OpenAI 开发人员文档。
• Context7：连接到最新的开发人员文档。
• Figma 本地 和 远程：访问您的 Figma 设计。
• Playwright：使用 Playwright 控制和检查浏览器。
• Chrome Developer Tools：控制和检查 Chrome。
• Sentry：访问 Sentry 日志。
• GitHub：在 git 支持的范围之外管理 GitHub（例如拉取请求和 issue）。