ValueError: Connection failed (possibly due to auth error). Please check authentication settings first

问题场景

用户使用 RAGFlow 的 MCP Servers 功能（路径为 /user-settings/mcp），新增一个指向本地 SSE 服务的外部 MCP 服务器。SSE 服务通过 supergateway 将 @modelcontextprotocol/server-filesystem 转为 SSE 输出，监听 localhost:8000/sse，且不要求授权令牌。在 RAGFlow 界面中点击“刷新”图标以获取工具列表时，抛出连接失败的错误。

报错原文

Test MCP error: Connection failed (possibly due to auth error). Please check authentication settings first

原因分析

虽然报错文案提示“可能是认证错误”，但根据 Issue 中的代码追踪，实际异常并非来自远端鉴权。错误的根源指向 rag/utils/mcp_tool_call_conn.py 中导入 mcp 客户端相关模块（如 ClientSession、sse_client、streamablehttp_client、CallToolResult 等）时找不到对应文件。这些文件由外部 Python 包 mcp 提供，而不是 RAGFlow 仓库内的代码。

用户在截图和描述中指出 mcp/client 目录下缺少这些 Python 文件，进而引发异常。可能原因是 RAGFlow 使用的 slim 镜像未完整安装 pyproject.toml 中声明的 mcp 依赖，或安装的版本过旧、部分模块缺失，导致容器内无法正常导入 MCP 客户端代码，最终以通用的连接失败异常呈现。

环境排查

• 确认当前使用的 RAGFlow 镜像是否为 slim 版本（如 v0.20.1 slim）。
• 检查 Docker 容器内是否已安装 mcp Python 包，可通过 Python 导入 mcp.client.session、mcp.client.sse 等模块来验证是否缺少文件。
• 确认 mcp 包版本是否不低于 1.9.4，因为 Issue 中明确提示该版本要求。
• 核查 pyproject.toml 中 mcp 依赖声明的位置，并与容器内实际安装结果比对。

解决步骤

1. 进入 RAGFlow 容器（例如通过 docker exec 进入运行中的容器），检查 mcp 包是否已安装。如果没有安装，使用 pip 安装 mcp，并确保版本不低于 1.9.4。
2. 安装完成后，在容器内验证导入：尝试导入 mcp.client.session、mcp.client.sse、mcp.client.streamable_http 和 mcp.types，确认不再报 ModuleNotFoundError。
3. 回到 RAGFlow 的 MCP 设置页面，再次点击“刷新”图标，观察工具列表是否能正常出现。
4. 如果还需要长期使用，建议将 mcp 依赖安装步骤固化到自定义镜像中，避免容器重建后再次丢失。

验证方法

重新触发 MCP 连接测试，确认界面不再弹出 “Connection failed (possibly due to auth error)” 错误，并且工具数量从 0 变为实际可用的 MCP 工具列表。若之前有误报，还应核对容器日志中是否仍出现 ValueError: Connection failed 及相关导入层面的 Traceback。

参考来源

infiniflow/ragflow #9523

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。