English
主导航

推荐
API 仪表板

模型上下文协议

为 Codex 提供对第三方工具和上下文的访问权限

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

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

支持的 MCP 功能

  • STDIO 服务器: 作为本地进程运行的服务器（通过命令启动）。
    • 环境变量
  • 可流式传输的 HTTP 服务器: 通过地址访问的服务器。
    • Bearer 令牌身份验证
    • OAuth 身份验证（运行 codex mcp login <server-name> 适用于支持 OAuth 的服务器）
  • 服务器指令: Codex 读取 MCP instructions 在初始化期间返回的字段，并将其与该服务器的工具一起用作服务器级别的全局指引。

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

将 Codex 连接到 MCP 服务器

Codex 将 MCP 配置存储在 config.toml ，与其他 Codex 配置设置放在一起。默认为 ~/.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 in trusted projects) directly.

使用 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.

终端 UI (TUI)

In the codex TUI，使用 /mcp 查看您的活动 MCP 服务器。

使用 config.toml 进行配置

如需对 MCP 服务器选项进行更精细的控制，请编辑 ~/.codex/config.toml （或项目范围的 .codex/config.toml)。在 IDE 扩展中，选择 MCP 设置 > 打开 config.toml from the gear menu.

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

STDIO 服务器

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

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

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

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

可流式传输的 HTTP 服务器

  • url (必填)：服务器地址。
  • bearer_token_env_var (可选)：用于发送 bearer token 的环境变量名称 Authorization.
  • 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 提供商要求固定的回调端口，请设置顶层 mcp_oauth_callback_port in config.toml。如果未设置，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 登录期间会优先使用服务器公布的这些作用域。否则，Codex 将回退到在中配置的作用域： config.toml.

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 服务器

已安装的插件可以在其插件清单中捆绑 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 文档 MCP：搜索并阅读 OpenAI 开发者文档。
  • Context7：连接到最新的开发者文档。
  • Figma 本地 and 远程：访问你的 Figma 设计。
  • Playwright：使用 Playwright 控制和检查浏览器。
  • Chrome 开发者工具：控制并检查 Chrome。
  • Sentry：访问 Sentry 日志。
  • GitHub：管理超出其范围的 GitHub git 支持的功能（例如拉取请求和议题）。