模型上下文协议（MCP）
Model Context Protocol
让 Codex 访问第三方工具和上下文
Model Context Protocol (MCP) 将模型连接到工具和上下文。使用它可以 让 ChatGPT 或 Codex 访问第三方文档，或使其能够 与浏览器或 Figma 等开发者工具交互。
ChatGPT 网页端可以使用插件提供、由远程 MCP 支持的工具。安装插件后， Chat 和 Work 可以使用其中捆绑的连接器和远程 MCP 工具。 打开 Plugins 标签页即可浏览和管理可用工具。本地 Codex 客户端也可以直接连接 MCP server 并共享其配置。
ChatGPT 桌面应用、Codex CLI 和 IDE 扩展支持 MCP server， 并为同一 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 server，请使用 instructions 来说明适用于整个服务器的跨工具工作流、约束和速率限制。请让前 512 个字符自成一体，以便 Codex 在决定如何使用服务器时能够获得最重要的指导。
将 Codex 连接到 MCP server
Codex 将 MCP 配置与其他 Codex 配置设置一起存储在 config.toml 中。默认位置为 ~/.codex/config.toml，但你也可以使用 .codex/config.toml 将 MCP server 限定到项目范围（仅限可信项目）。
ChatGPT 桌面应用、Codex CLI 和 IDE 扩展共享此配置。 配置 MCP server 后，你可以在这些客户端之间切换， 无需重新设置。
在 ChatGPT 桌面应用中配置
- 打开 Settings，然后选择 MCP servers。
- 选择 Add server。
- 输入名称，选择 STDIO 或 Streamable HTTP，然后提供 服务器命令或 URL。
- 保存服务器，然后选择 Restart。
服务器列表会显示哪些服务器已启用，以及哪些服务器需要 OAuth。OAuth 服务器需要登录时，选择
Authenticate。在输入框中键入 /mcp
即可查看已连接的服务器。
在 ChatGPT 网页版中使用由 MCP 支持的工具
在托管的 ChatGPT Work 对话中，安装插件即可使用其 捆绑的连接器和远程 MCP 工具。安装后，Chat 和 Work 均可 使用这些工具。工作区管理员可以控制可用的插件和工具。
ChatGPT 网页版不会读取本地 Codex 配置文件，也不会提供本地 Codex 命令菜单。打开 Plugins 标签页即可浏览和管理可用 工具。
使用 CLI 配置
添加 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 命令
运行 codex mcp list 可查看已配置的服务器。要查看所有可用的 MCP
命令，请运行 codex mcp --help。对于支持 OAuth 的服务器，请运行
codex mcp login <server-name>。
终端界面 (TUI)
在 codex TUI 中，使用 /mcp 可查看当前启用的 MCP server 。
在 IDE 扩展中配置
- 打开齿轮菜单，然后选择 MCP servers。
- 选择 Add server。
- 输入名称，选择 STDIO 或 Streamable HTTP，并提供服务器的 命令或 URL。
- 保存服务器，然后选择 Restart extension。
MCP server 列表会显示哪些服务器已启用，以及哪些服务器需要 OAuth。 当 OAuth 服务器要求登录时，请选择 Authenticate。
使用 config.toml 配置
如需更精细的控制，请编辑 ~/.codex/config.toml 或项目范围的
.codex/config.toml。请参阅配置参考，
其中提供了所有受支持 MCP 选项的可搜索列表。
在配置文件中，使用 [mcp_servers.<server-name>] 表配置每个 MCP server 。
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（可选）：用于存放 bearer token 的环境变量名称，该令牌将通过Authorization发送。http_headers（可选）：标头名称到静态值的映射。env_http_headers（可选）：标头名称到环境变量名称的映射（值从环境中获取）。http_headers_helper（可选）：输出由标头名称和字符串值组成的 JSON 对象的本地命令， 例如{"X-Auth": "temporary-token"}。 支持从本地环境建立的 HTTP MCP 连接；不支持 stdio 服务器或通过远程执行环境建立的连接。
Codex 会为该连接缓存辅助程序生成的标头。同源 POST
返回 401 或 403 后，Codex 会刷新一次标头，并且仅当
辅助程序返回的值发生变化时才重试。显式 bearer token 和 OAuth 凭据
优先于辅助程序提供的 Authorization 标头。
如果 OAuth 403 响应报告权限范围不足，则不会触发
辅助程序刷新。
如果无法解析任何凭据来源，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（可选）：针对单个工具覆盖审批行为。tools.<tool>.output_token_limit（可选）：单次工具输出的正数 token 预算， 不包括标准的 20% 序列化余量。它会覆盖模型为该工具设置的 默认输出截断预算。
顶层 mcp_optional_startup_grace_ms 设置用于控制 Codex
在构建初始工具目录时等待可选 MCP server 的时长。
默认值为 1000 毫秒。将其设为 0，即可改为等待每台服务器各自的
startup_timeout_sec。必需服务器仍使用各自的启动
超时时间。
OAuth 客户端注册和回调
当授权服务器要求使用预注册的 OAuth 客户端时，请在添加 MCP server 时提供 其客户端 ID：
codex mcp add example --url https://mcp.example.com --oauth-client-id my-clientCodex 会显示需要向提供方注册的完整回调 URL：
OAuth callback URL: http://127.0.0.1/callbackCodex 会将回调与客户端 ID 一并保存在 config.toml 中，供后续
登录使用：
[mcp_servers.example]
url = "https://mcp.example.com"
[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"仅当授权服务器公布
authorization_response_iss_parameter_supported: true 并在元数据中提供
issuer 时，新添加的预注册客户端才会使用稳定的回调。如果未公布颁发者支持，Codex 会附加服务器专用的
回调 ID，例如 http://127.0.0.1/callback/XuuuHAzzHOni。未保存回调的现有客户端
将继续使用其包含特定回调 ID 的重定向。
登录期间，回调选择取决于 OAuth 配置和 授权服务器元数据：
| OAuth 配置 | 颁发者支持 | 使用的回调 |
|---|---|---|
有 callback_url，无 client_id |
支持 | 使用配置的回调进行客户端注册。 |
有 callback_url，无 client_id |
不支持 | 使用配置的回调进行客户端注册，并在末尾附加服务器专用的回调 ID。 |
client_id 和 callback_url |
支持 | 复用配置的回调；授权响应必须包含匹配的 iss。 |
client_id 和以正确回调 ID 结尾的 callback_url |
不支持 | 原样复用配置的回调。 |
client_id 和缺少正确回调 ID 的 callback_url |
不支持 | 忽略配置的回调。Codex 使用 mcp_oauth_callback_url；若未设置，则使用 http://127.0.0.1/callback，并在末尾附加回调 ID。 |
有 client_id，但未配置 callback_url |
支持或不支持 | Codex 使用全局或默认回调，并在末尾附加服务器专用的回调 ID。 |
回退不会修改已存储的回调 URL。Codex 根据 MCP server URL（包括其路径和查询字符串） 派生回调 ID。自动登录和显式登录 采用相同的选择规则。
需要自定义回调路径或远程
Devbox 入口 URL 时，请设置 mcp_oauth_callback_url。当提供方支持颁发者标识时，新添加的预注册客户端会原样使用该 URL。
否则，它们会使用配置的 URL，并在末尾附加服务器专用的回调 ID。请始终注册
codex mcp add 显示的确切回调。
对于不含端口的 http://127.0.0.1 回调，Codex 会从其显示和存储的
URL 中省略监听端口，然后在授权期间插入当前使用的监听端口。
此替换不适用于 localhost、IPv6 主机、
HTTPS URL 或已包含端口的回调。根据
RFC 8252 第 7.3 节，授权服务器必须接受可变的环回端口。
设置 mcp_oauth_callback_port 可选择固定的全局监听端口，也可以设置
mcp_servers.<server-name>.oauth.callback_port 为单个服务器覆盖该端口。
回调 URL 中的显式端口不会配置监听器。对于
直接环回回调，请使用不含端口的 http://127.0.0.1，或者为回调 URL 和监听器配置相同的
显式端口。代理回调可以有意使用与本地监听器
端口不同的外部 URL 端口。本地回调 URL 绑定到本地接口；非本地回调 URL
绑定到 0.0.0.0。
Codex 会在交换授权码之前验证返回的所有 iss。如果
iss 不匹配，始终会拒绝该响应。公布颁发者支持后，
缺少 iss 也会导致响应被拒绝。上述两种失败均不会交换授权码，也不会
回退到其他回调。回调 URL 格式错误，或者公布颁发者支持却未在元数据中提供颁发者，
也仍属于不可恢复的失败。请参阅
对用户进行身份验证。
如果 MCP server 公布 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.jsonCodex 会根据 MCP server 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"
output_token_limit = 30000插件提供的 MCP server
已安装的插件可以在其插件清单中捆绑 MCP server 。这些
服务器从插件启动，因此用户配置无需设置其
传输命令。用户配置仍可在 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"插件提供的 HTTP MCP server 也可以在 .mcp.json 中声明 OAuth 设置。
插件清单使用驼峰式字段名 clientId、callbackUrl 和
callbackPort：
{
"mcpServers": {
"sample": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"oauth": {
"clientId": "my-pre-registered-client",
"callbackUrl": "http://127.0.0.1/callback/registered"
}
}
}
}插件提供的 MCP server 与其他
MCP server 采用相同的回调选择规则。如果插件提供了 clientId，其提供方不支持
与颁发者绑定的回调，并且 callbackUrl 缺少服务器专用的回调
ID，Codex 会在登录时忽略该 URL，改用 mcp_oauth_callback_url；若未设置，
则使用 http://127.0.0.1/callback，并在末尾附加回调 ID。
配置的 callbackUrl 保持不变。
插件的 oauth.callbackPort 会覆盖全局
mcp_oauth_callback_port；如果两者均未设置，Codex 会选择临时端口。
嵌入 callbackUrl 的端口不会选择监听端口。对于使用固定端口的
直接环回回调，请将这两个值配置为一致：
{
"callbackUrl": "http://127.0.0.1:4321/callback/registered",
"callbackPort": 4321
}对于远程入口或其他代理，如果代理将请求转发到配置的 监听器，回调 URL 端口可以有意与本地监听器端口不同。
实用 MCP server 示例
MCP server 列表仍在不断增长。以下是一些常见示例：
- OpenAI Docs MCP：搜索和阅读 OpenAI 开发者文档。
- Context7：连接最新的开发者文档。
- Figma Local 和 Remote：访问你的 Figma 设计。
- Playwright：使用 Playwright 控制和检查浏览器。
- Chrome Developer Tools：控制和检查 Chrome。
- Sentry：访问 Sentry 日志。
- GitHub：管理
git所支持范围之外的 GitHub 功能（例如 PR 和问题单）。