[Bug]: OpenAPI MCP `extra_headers` are not forwarded from client requests

快速结论：此问题发生在使用 LiteLLM 代理且配置了 OpenAPI 驱动的 MCP（Model Context Protocol）服务器时，客户端请求中携带的自定义 header（如 X-TOKEN）无法通过 extra_headers 配置转发到上游 API。优先排查是否使用了 OpenAPI MCP 工具路径，因为该路径目前不支持动态 header 转发，仅支持托管 MCP 客户端路径。

问题场景

用户在 LiteLLM 代理中配置了 OpenAPI 驱动的 MCP 服务器（通过 spec_path 定义），并在 yaml 配置中设置了 extra_headers: ["X-TOKEN"]，期望客户端请求中的自定义 header 被转发到上游 OpenAPI 端点。实际调用 MCP 工具的 tools/call 端点时，上游 API 未收到这些 header，导致鉴权失败（如 missing-header 或 unauthorized 错误）。

报错原文

HTTP 401 Unauthorized or missing-header error from upstream API
Expected headers like X-TOKEN not present in upstream request

原因分析

根本原因是 OpenAPI MCP 工具与托管 MCP 客户端使用了不同的代码路径。LiteLLM 的托管 MCP 路径（managed MCP path）在 server.py 的 _prepare_mcp_server_headers() 方法中实现了从请求头复制配置的 extra_headers，但 OpenAPI MCP 工具在启动时通过 mcp_server_manager.py 注册为本地工具处理程序，该路径在生成工具时闭包捕获了静态 headers 字典，且仅支持通过 x-mcp-auth header 传递的认证信息（格式化为 Authorization header），没有代码路径将请求中其他自定义 header（如 X-TOKEN）传递到生成的 OpenAPI 工具执行上下文中。

具体来说，在 mcp_server_manager.py 中，OpenAPI 工具注册时明确注记 extra_headers 不可用（“not available in this OpenAPI tool generation step”），生成的工具只能使用编译时的 headers 字典和硬编码的 Authorization ContextVar 覆盖。

环境排查

确认使用 LiteLLM 版本（问题在 v1.91.0 中仍被报告未修复）
确认 MCP 服务器配置中 spec_path 指向 OpenAPI JSON 端点
排查是使用托管 MCP 客户端路径还是 OpenAPI 本地工具路径（后者不支持 extra_headers 动态转发）
确认上游 API 是否只依赖 Authorization header（该 header 通过 x-mcp-auth 支持）或其他自定义 header

解决步骤

确认工具类型：检查日志或配置，确认正在调用的 MCP 工具是否是通过 OpenAPI spec 自动生成的本地工具。如果工具名称与 OpenAPI 端点关联，则走的是不支持 extra_headers 的路径。
优先尝试静态 header 替代方案：如果上游 API 需要固定的 header 值（如 X-TOKEN: abc123），可在 MCP 服务器配置中使用 static_headers 替代：
```
mcp_servers:
  data_api:
    url: ... 
    spec_path: ...
    static_headers:
      X-TOKEN: "your-static-token-value"
```
注意：此方法是静态的，所有请求共享同一 token，不适用于每个请求携带不同 token 的场景。
变通方案：使用托管 MCP 路径：如果上游 API 支持独立部署为托管 MCP 端点（managed MCP），则配置该路径可获得 extra_headers 转发支持。但此方案要求上游 API 本身实现 MCP 协议，不适用于直接暴露 OpenAPI 的服务。
等待官方修复：检查 Issue #26794 的后续更新或 PR。目前核心问题在于 OpenAPI 工具生成阶段的代码没有实现 extra_headers 的动态传递入口，可能需要社区贡献或官方 patch。

验证方法

执行上述步骤后，再次通过 curl 调用 MCP 工具的 tools/call 端点，并携带 X-TOKEN header。检查上游 API 的访问日志或返回响应，确认 header 是否被成功转发。如果使用 static_headers，则直接确认上游 API 正常响应，无需客户端传递 token。