
Misc. bug: WebUI CORS proxy requests don’t include API key for MCP connections
快速结论:当同时启用 --api-key-file 和 --webui-mcp-proxy 时,WebUI 发送给 /cors-proxy 的请求不会自动携带 API key,导致 MCP 连接因 401 认证失败。该问题已在 PR #21193 中修复,但此前的手动添加 Header 解决方案(在 MCP 服务器条目中添加 Authorization: Bearer <key>)在 commit abf9a6216(#21072)合并后被破坏,所有自定义 Header 被封装为 X-Proxy-Header-*,导致 Header 不再被鉴权中间件识别。
问题场景
用户启动 llama-server 并同时使用 --api-key-file(API key 认证文件)和 --webui-mcp-proxy(WebUI CORS 代理)参数。在 WebUI 中通过 API key 认证后,添加 MCP 服务器(如 http://127.0.0.1:8581/mcp)并启用“Use Proxy”选项时,连接失败。
报错原文
Connection failed: NetworkError when attempting to fetch resource.
Streamable HTTP error: Error POSTing to endpoint: {"error":{"message":"Invalid API Key","type":"authentication_error","code":401}}
原因分析
根本原因是 /cors-proxy 端点受全局 API key 验证中间件保护,但 WebUI 在发起 CORS 代理请求时未自动包含 API key。用户的 MCP 连接请求经过 CORS 代理时,因为缺少认证信息,服务器返回 401。
此前,用户可以通过手动在 MCP 服务器条目中添加 Authorization: Bearer <api-key> 作为自定义 Header 来绕过该问题。然而,commit abf9a6216(#21072)将所有自定义 Header 包裹为 X-Proxy-Header-* 格式,导致 Authorization 头不再被 llama-server 的鉴权中间件识别,因此该手动方案也失效。
环境排查
- llama-server 版本:version 8577 (2405d59cb) 及之后(包括受影响版本)
- 操作系统:Linux(但 Windows 用户也报告遇到相同问题,如版本 b9119)
- 命令行参数:确认同时使用了
--api-key-file和--webui-mcp-proxy - 受影响模块:llama-server、WebUI CORS proxy、MCP 连接
解决步骤
- 检查是否已包含修复:确认 llama-server 版本是否包含 PR #21193 的修复。该 PR 确保 WebUI 在发送
/cors-proxy请求时自动携带 API key。 - 如果版本较旧:升级到包含 PR #21193 修复的版本。
- 对于无法升级的情况:
- 注意:旧的“手动添加
Authorization: Bearer <key>头”方案在 commit abf9a6216(#21072)后已失效。 - 可能原因:如果没有其他可用的配置选项,目前无已知变通方案。等待官方修复版本的发布。
- 注意:旧的“手动添加
- 可优先尝试(推测):尝试在不启用
--webui-mcp-proxy的模式下测试 MCP 连接,确认问题是 CORS 代理特有。但 Issue 中未提供此变通方案。
验证方法
重新启动 llama-server 并使用同样的配置(--api-key-file + --webui-mcp-proxy),在 WebUI 中通过 API key 认证后,添加 MCP 服务器并启用“Use Proxy”。如果连接成功,不再报 401 Invalid API Key 错误,说明问题已解决。



