MCP OAuth 与 issuer 校验

远程 SSE/HTTP 服务可使用 OAuth。401 触发认证发现，CLI 读取授权与 token 端点，支持时进行动态客户端注册，再打开浏览器登录和重试连接。

浏览器与回调

默认回调为 http://localhost:<random-port>/oauth/callback，端口由系统分配；oauth.redirectUri 可指定回调。运行环境必须能打开浏览器并接收回调，普通无浏览器 headless、缺少浏览器转发的 SSH 和无浏览器容器不能直接完成这个交互流程。

显式配置

{
  "mcpServers": {
    "secure-server": {
      "httpUrl": "https://mcp.example.com/mcp",
      "oauth": {
        "enabled": true,
        "issuer": "https://auth.example.com",
        "authorizationUrl": "https://auth.example.com/oauth/authorize",
        "tokenUrl": "https://auth.example.com/oauth/token",
        "clientId": "gemini-cli-client",
        "scopes": ["mcp:read"]
      }
    }
  }
}

地址、client ID 和 scope 都是占位，需按服务替换。clientSecret 对 public client 可选，动态注册时 clientId 也可能无需预填。

issuer 判断

回调包含 iss 且已知预期 issuer 时，值必须一致。发现的元数据声明 authorization_response_iss_parameter_supported true 时必须带 iss；元数据未声明或为 false，可接受不含 iss 的回调。

显式配置 issuer 且没有发现授权元数据时，默认要求 iss。确实需兼容不返回 iss 的服务，可将 oauth.authorizationResponseIssParameterSupported 设为 false；这只允许缺失，不允许已经返回的错误 issuer。

登录与重登录

/mcp auth 列出需认证服务，/mcp auth <serverName> 完成或重新进行认证。Missing issuer parameter 与 Issuer mismatch 应按服务元数据、回调和配置排查，不能只反复重登。

token 保存

官方指定缓存文件 ~/.gemini/mcp-oauth-tokens.json，连接前检查 token，有 refresh token 时自动刷新并清理失效项。本页不从“安全保存”措辞推断文件必然加密或进入系统钥匙串。

与 A2A 的区别

MCP OAuth 字段使用 clientId、authorizationUrl 等 camelCase；远程 A2A 定义使用另一套 auth schema。不要把远程代理认证直接复制到 mcpServers。