# MCP OAuth 与 Callback

> 选择预注册 client、CIMD 或 DCR，并正确区分 callback URL 和本地监听端口。

- 网址：https://funcoding.ai/agents/codex/build/mcp-oauth/
- 核实日期：2026-10-07（命令、配置和价格以官方文档为准）
- 官方来源：[Codex 官方文档：Model Context Protocol](https://learn.chatgpt.com/docs/extend/mcp)

---
OAuth 登录失败时，先区分服务器注册方式、回调地址、监听端口和 issuer 验证。它与 Codex 自身的 ChatGPT 登录是不同流程。

## 预注册客户端

```bash
codex mcp add example --url https://mcp.example.com --oauth-client-id my-client
```

示例需替换为实际 URL 和 client ID。将 codex mcp add 显示的完整 callback 注册到提供方，不能仅复制文档里的通用地址。

服务器声明 authorization_response_iss_parameter_supported=true 且提供 metadata issuer 时，新预注册 client 可用稳定 callback。未声明 issuer 支持时需要服务器特定 callback ID，该 ID 由 MCP URL（含 path/query）派生。

已有 client_id 却没有保存 callback 的配置，继续使用带 callback ID 的地址。不匹配的显式 callback 可能回退到全局/default 加服务器 ID，且不会改写保存的值。

## URL 与监听端口

顶层 mcp_oauth_callback_url 设置 callback 路径或远程 ingress；mcp_oauth_callback_port 设置本地全局监听端口，单服务器 oauth.callback_port 可以覆盖。

URL 中写端口不会自动设置 listener。直接 loopback 回调可用不带端口的 http://127.0.0.1，让登录时插入实际端口；显式固定端口时需同时配置 URL 与 listener。localhost、IPv6、HTTPS 和已有端口 URL 不使用该自动替换。经代理的外部端口可以与本地 listener 不同。

## 注册方式

服务器支持 CIMD、token endpoint 允许 none、callback 使用受支持 loopback 时，Codex 可自动选 CIMD；否则在可用时使用 DCR。已有 client ID 优先，跳过自动注册。

单次登录可指定：

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

默认 auto，选择只作用于当前登录，不保存到 config.toml。自定义 callback 主机、路径或 query 需要 DCR 或预注册 client。

## 验证失败

返回的 iss 不匹配总会拒绝；服务器声明 issuer 支持却缺少 iss 也会拒绝。这些情况不会交换 code 或尝试另一个 callback。畸形 URL、声明支持但 metadata 无 issuer 同样硬失败。

服务器声明 scopes_supported 时优先使用其 scopes，否则回退 config.toml 配置。插件 OAuth 使用 camelCase 字段，但遵循相同 callback 选择规则。