ChatGPT 中文教程
中文
联系我 goolvyouyou@gmail.com

模型上下文协议（MCP）

Model Context Protocol

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

Model Context Protocol (MCP) 将模型连接到工具和上下文。使用它可以 让 ChatGPT 或 Codex 访问第三方文档，或使其能够 与浏览器或 Figma 等开发者工具交互。

ChatGPT 网页端可以使用插件提供、由远程 MCP 支持的工具。安装插件后， Chat 和 Work 可以使用其中捆绑的连接器和远程 MCP 工具。 打开 Plugins 标签页即可浏览和管理可用工具。本地 Codex 客户端也可以直接连接 MCP 服务器并共享其配置。

ChatGPT 桌面应用、Codex CLI 和 IDE 扩展支持 MCP 服务器， 并为同一 Codex 主机共享 MCP 配置。

以下支持的服务器功能适用于在 Codex 主机上配置的 MCP 服务器。托管的插件工具可能具有不同的功能。

支持的 MCP 功能

  • STDIO 服务器：作为本地进程运行的服务器（由命令启动）。
    • 环境变量
  • 可流式传输的 HTTP 服务器：通过地址访问的服务器。
    • Bearer token 身份验证
    • OAuth 身份验证，包括 Client ID Metadata Documents (CIMD) 和 Dynamic Client Registration (DCR)
    • 适用于可信第一方服务器的 ChatGPT 会话身份验证
  • 服务器指令：Codex 会读取初始化期间返回的 MCP instructions 字段，并将其作为服务器级指南，与服务器工具配合使用。

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

将 Codex 连接到 MCP 服务器

Codex 将 MCP 配置与其他 Codex 配置设置一起存储在 config.toml 中。默认位置为 ~/.codex/config.toml，但你也可以使用 .codex/config.toml 将 MCP 服务器限定到项目范围（仅限可信项目）。

ChatGPT 桌面应用、Codex CLI 和 IDE 扩展共享此配置。 配置 MCP 服务器后，你可以在这些客户端之间切换， 无需重新设置。

在 ChatGPT 桌面应用中配置

  1. 打开 Settings，然后选择 MCP servers。
  2. 选择 Add server。
  3. 输入名称，选择 STDIO 或 Streamable HTTP，然后提供 服务器命令或 URL。
  4. 保存服务器，然后选择 Restart。

服务器列表会显示哪些服务器已启用，以及哪些服务器需要 OAuth。OAuth 服务器需要登录时，选择 Authenticate。在输入框中键入 /mcp 即可查看已连接的服务器。

使用 config.toml 配置

如需更精细的控制，请编辑 ~/.codex/config.toml 或项目范围的 .codex/config.toml。请参阅配置参考， 其中提供了所有受支持 MCP 选项的可搜索列表。

在配置文件中，使用 [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。

Streamable HTTP 服务器

  • url（必填）：服务器地址。
  • auth（可选）：在配置的 bearer token 和 授权标头之后尝试的身份验证。使用 oauth（默认值）可采用已存储的 MCP OAuth 凭据。使用 chatgpt 可针对可信的 第一方 ChatGPT 来源使用当前 ChatGPT 会话，并将已存储的 OAuth 作为后备方案。
  • bearer_token_env_var（可选）：要在 Authorization 中发送的 bearer token 所对应的环境变量名。
  • http_headers（可选）：标头名称到静态值的映射。
  • env_http_headers（可选）：标头名称到环境变量名的映射（从环境中获取值）。

如果无法解析任何凭据来源，Codex 可以在不进行 身份验证的情况下连接服务器。单独运行 codex mcp login <server-name> 以启动 MCP OAuth 登录。

其他配置选项

  • startup_timeout_sec（可选）：服务器启动超时时间（秒）。默认值：10。
  • tool_timeout_sec（可选）：服务器运行工具的超时时间（秒）。默认值：60。
  • enabled（可选）：设为 false 可禁用服务器而不将其删除。
  • required（可选）：设为 true，可在此已启用服务器无法初始化时使启动失败。
  • enabled_tools（可选）：工具允许列表。
  • disabled_tools（可选）：工具拒绝列表（在 enabled_tools 之后应用）。
  • default_tools_approval_mode（可选）：此服务器中 工具的默认批准行为。支持的值为 auto、prompt、writes 和 approve。writes 模式会对未标记为只读的工具显示提示。
  • tools.<tool>.approval_mode（可选）：针对各工具覆盖批准行为。

如果 OAuth 提供方要求固定回调端口，请在 config.toml 中设置顶层 mcp_oauth_callback_port。如果未设置，Codex 会绑定临时端口。

如果 MCP OAuth 流必须使用特定回调 URL（例如远程 Devbox 入口 URL 或自定义回调路径），请设置 mcp_oauth_callback_url。Codex 使用此值作为基础回调 URL，然后附加服务器特定的回调 ID，以生成登录期间发送的 OAuth redirect_uri。请向 OAuth 提供方注册完整派生的 redirect_uri，其中应包含附加的回调 ID 以及任何已配置的路径、查询或端口，而不是只注册不带该后缀的基础主机或路径。本地回调 URL（例如 localhost）绑定到本地接口；非本地回调 URL 绑定到 0.0.0.0，以便回调能够到达主机。

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

OAuth 客户端注册

Codex 支持 OAuth Client ID Metadata Documents (CIMD) 和 Dynamic Client Registration (DCR)。默认情况下，当授权服务器通告 client_id_metadata_document_supported: true、在 token_endpoint_auth_methods_supported 中包含 none，且回调使用受支持的 环回 URL 时，Codex 会自动选择 CIMD。否则，Codex 会在 DCR 可用时使用 DCR。已配置的 OAuth 客户端 ID 始终具有优先权，并会跳过客户端注册。

对于 CIMD，Codex 会使用专用于该 MCP 服务器、由 ChatGPT 托管的元数据文档：

https://chatgpt.com/oauth/codex/<callback_id>/client.json

Codex 会根据 MCP 服务器 URL 派生 <callback_id>，并将其包含在 环回重定向 URI 中，例如 http://127.0.0.1:<port>/callback/<callback_id>。元数据文档会注册 不含端口的匹配环回 URI。按照 RFC 8252 的要求，授权服务器必须接受登录时选择的 端口，同时精确匹配主机和路径。自定义 回调主机、路径或查询参数需要使用 DCR 或已配置的 OAuth 客户端 ID。

对稳定共享 CIMD 文档的支持正在开发中，即将推出：

https://chatgpt.com/oauth/codex/client.json

当授权服务器通告 authorization_response_iss_parameter_supported: true、在其元数据中提供有效的 issuer，并且授权响应中包含匹配的 iss 时，Codex 将使用带有共享 /callback 路径的稳定文档。 未提供与颁发者绑定的响应的服务器将继续使用 回调专用文档。

要为单次 CLI 登录选择注册方式，请使用 --oauth-client-registration：

codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr

默认值为 auto。注册方式选择仅适用于当前登录， 不会存储在 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 Docs MCP：搜索和阅读 OpenAI 开发者文档。
  • Context7：连接最新的开发者文档。
  • Figma Local 和 Remote：访问你的 Figma 设计。
  • Playwright：使用 Playwright 控制和检查浏览器。
  • Chrome Developer Tools：控制和检查 Chrome。
  • Sentry：访问 Sentry 日志。
  • GitHub：管理 git 所支持范围之外的 GitHub 功能（例如拉取请求和议题）。