[Bug]: Breaking change in LiteLLM 1.96+: managed MCP OAuth2 flow opens LiteLLM UI instead of the vendor authorization page

快速结论：LiteLLM 1.96+ 引入的 is_gateway_managed_oauth2 属性将命名 MCP 服务器错误归类为聚合网关 DCR 流，导致 OAuth 授权重定向到 LiteLLM 登录 UI 而非厂商授权页。优先检查 discoverable_endpoints.py 中的响应构建逻辑及 delegate_auth_to_upstream 配置状态。

适用环境：LiteLLM 代理 1.96+（Issue 从 1.95.1 升级至 1.99.0 后触发），配置了受管 OAuth2 MCP 服务器（客户端携带 x-litellm-api-key 请求头）。

最快修复方案：暂无确认的一步修复方案。可以优先尝试为命名 MCP 服务器显式设置 delegate_auth_to_upstream: true，或回退到 LiteLLM 1.95.1 及更早版本，但两者均未被 Issue 维护者明确验证为等同修复。

注意事项：LiteLLM 维护者在回复中强调键控流和 keyless 流机制不同；当前讨论仍在澄清是聚合 DCR 行为误触发还是键控流程回归，尚不能作为最终修复方案采纳。

问题场景

用户将 LiteLLM 从 1.95.1 升级至 1.99.0（1.96+ 起），运行带 MCP 客户端的 Claude Code 配置，访问名为 figma 的 MCP 服务器。配置采用受管 OAuth2（授权码流），预期客户端先走 LiteLLM 每服务器中继端点（/figma/register、/figma/authorize），再由 LiteLLM 将浏览器重定向到厂商授权页（如 https://www.figma.com/oauth/mcp）。实际在授权码请求时被 303 重定向到 LiteLLM 自身的 /sso/key/generate 登录页面，无法进入厂商授权页并完成整个 OAuth 中继流程。

报错原文

[Bug]: Breaking change in LiteLLM 1.96+: managed MCP OAuth2 flow opens LiteLLM UI instead of the vendor authorization page


GET http://localhost:4000/.well-known/oauth-protected-resource/mcp/figma
{
  "authorization_servers": ["http://localhost:4000/mcp"],
  "resource": "http://localhost:4000/mcp/figma"
}


303 See Other
Location: http://localhost:4000/sso/key/generate?return_to=...

原因分析

可能原因：LiteLLM 1.96+ 引入了一个新的属性 is_gateway_managed_oauth2（位于 litellm/types/mcp_server/mcp_server_manager.py），它将“LiteLLM 中继厂商 OAuth 流程”和“使用聚合 /mcp 网关 DCR 流程”两个概念混在一起。在 discoverable_endpoints.py 的 _build_oauth_protected_resource_response 中，当命名 MCP 服务器的 is_gateway_managed_oauth2 返回 True 时，LiteLLM 会把请求指向聚合的 /mcp 网关 DCR 端点，随后客户端注册得到的 client_id 形如 llm_dcrc_<opaque-value>（DCR 注册模式），导致最终授权请求被引导到 LiteLLM UI 登录页。

值得注意的是，Issue 报告者明确提到并未启用 dcr_bridge，排除该配置项为触发条件，问题仅由 auth_type: oauth2 + oauth2_flow: authorization_code 触发。

环境排查

确认 LiteLLM 版本已升级至 1.96+（具体验证范围为 1.99.0，但 1.96+ 均可能触发）。
检查 MCP 服务器 YAML 是否显式设置了 delegate_auth_to_upstream: true（如果设置了则不会触发，因为 is_gateway_managed_oauth2 会返回 False）。
排查 mcpservers 的命名服务器是否存在且与配置名称严格一致（explicitly_named 变量需要 True 才能进入问题分支）。
确认 MCP 客户端是否该请求携带 LiteLLM API Key：通过 x-litellm-api-key 请求头传递（keyless 流程被维护者视为另一种受支持但不同流）。
检查该 OAuth2 中继是否原本依赖 1.95.1 前每服务器中继端点（/figma/register、/figma/authorize、/figma/token）行为；这些端点在 1.96+ 中对命名服务器有所变更。

解决步骤

在服务端配置中显式关闭聚合管理标记：若希望保留厂商授权码中继，可在 MCP 服务器配置中加上 delegate_auth_to_upstream: true 后重启 LiteLLM 代理，观察是否绕过问题分支（注意该操作不一定保留后续 LiteLLM 存储/刷新 token 行为，此方案为“可优先尝试”，尚未被维护者确认替换等价）。
验证并收集触发位置日志：确认实际触发分支位于 litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py 中 _build_oauth_protected_resource_response 的 if explicitly_named and mcp_server is not None and mcp_server.is_gateway_managed_oauth2 条件，及 mcp_server_manager.py 中的 is_gateway_managed_oauth2 属性计算逻辑。
判断归属流：与维护者澄清时说明你的客户端发送了 LiteLLM API Key —— 即属于“LiteLLM-keyed OAuth”流程，而不是 keyless 的“LiteLLM 登录 → 厂商 OAuth → LiteLLM session”流程；这有助于维护者区分是否 keyless 流程中的设计预期。
回滚版本：如果生产等不及补丁，先暂时回退到 1.95.1（Issue 报告阶段尚未有最终修复在哪个版本合入的官方确认）。
跟进 Issue 动态：关注该 Issue 及 #34856 上的 Flow 区分逻辑；维护者已承认两种流程混合，修复尚未落地，等待代码库中新增 opt-in/opt-out（如 gateway_dcr: false 配置项）方案落地前不要对现有行为重启依赖。

验证方法

调整任一步骤后重启 LiteLLM 代理，再模拟原始 MCP 授权请求链路：先请求 GET http://localhost:4000/.well-known/oauth-protected-resource/mcp/figma，确认响应为每服务器授权端点（authorization_servers 中不应再包含聚合的 http://localhost:4000/mcp），随后带 LiteLLM Key 请求 GET /authorize?...，确认得到 303 并重定向到厂商页面（如 https://www.figma.com/oauth/mcp）而非 /sso/key/generate，然后完整走完厂商授权页 → LiteLLM 回调 → vendor token 的流程。