[BUG]: HTTP MCP Server only shows in UI when “type” is incorrect.

快速结论：这个 Bug 发生在 AnythingLLM Desktop 加载 HTTP MCP Server 时，当 MCP Server 配置正确（type 与服务器实际协议匹配），服务器反而在 UI 列表中消失；当 type 配置为错误值（与实际协议不匹配）时，服务器反而显示在列表中（但带错误信息）。优先排查 MCP Server 返回的工具 Schema 中是否包含 $ref 引用，特别是 OutputSchema 字段。

问题场景

用户在 AnythingLLM Desktop v1.15.0 (macOS Tahoe 26.5.1, Apple Silicon M4 Pro) 上配置 HTTP MCP Server（本地 localhost:8080）。使用 type: "sse" 或 type: "streamable" 与服务器实际协议匹配时，服务器在 MCP Servers 列表中消失；将 type 设为错误值（如服务器实际是 Streamable 却设为 "sse"），服务器出现在列表中，但详情显示协议错误。

报错原文

Failed to start MCP server: mytest [NO_CODE] MCP server type must have sse or streamable value.
Failed to start MCP server: mytest [400] Streamable HTTP error: Error POSTing to endpoint: sessionid must be provided
Failed to start MCP server: mytest [400] SSE error: Non-200 status code (400)

此外，当服务器正确配置时，UI 仅显示 No MCP servers found，无任何报错细节。

原因分析

根据 Issue 讨论，这很可能是一个 UI 层面的过滤/崩溃问题。当 MCP Server 正确配置（type 匹配实际协议）时，AnythingLLM 客户端在解析服务器返回的工具 Schema 时遇到 $ref 引用（特别是 OutputSchema 中的 $ref），由于无法正确解析该引用，导致整个 MCP Server 在 UI 列表中被过滤掉或崩溃消失。反之，当 type 配置错误时，客户端在协议握手阶段就失败，不会进入 Schema 解析阶段，因此服务器反而出现在列表中（带错误信息）。

注意：目前这一分析是推测，Issue 中用户提供了一个最小复现仓库（go-sdk fork），其中取消注释第 91 行（添加 $ref 到 OutputSchema）即可触发此行为。

环境排查

AnythingLLM 版本：v1.15.0（Desktop，Apple Silicon）
操作系统：macOS Tahoe 26.5.1
硬件：MacBook Pro with M4 Pro
MCP Server：HTTP 协议，本地 localhost:8080
MCP Server 实现：Go SDK（带有 $ref Schema 加载功能的分支）

解决步骤

可优先尝试：检查你的 MCP Server 返回的工具定义中，OutputSchema 字段是否包含 $ref 引用（例如 "$ref": "#/definitions/..."）。如果是，尝试将引用的 Schema 内联展开，避免使用 $ref。
如果无法修改 MCP Server，尝试在 AnythingLLM 配置中将 type 设为与实际协议不匹配的值（例如服务器是 Streamable 则设为 "sse"），此时服务器会出现在 UI 列表中（但无法正常使用），至少可以看到错误信息。
检查 MCP Server 的 InputSchema 是否也包含 $ref —— 根据 Issue 评论，此问题似乎只与 OutputSchema 有关，InputSchema 中的 $ref 可能不会触发此 Bug。
等待 AnythingLLM 官方修复此 UI 过滤逻辑。Issue 已被标记为 core-team-only 和 investigating。

验证方法

修改 MCP Server 的 OutputSchema，移除所有 $ref 引用（内联展开）。重新启动 MCP Server 并在 AnythingLLM 中点击 Refresh，如果服务器正常出现在列表中且无错误提示，即表示问题由 $ref 引起并已解决。

参考来源

Mintplex-Labs/anything-llm #5917

AI 工具推荐

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

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

了解 GamsGo AI

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

[BUG]: HTTP MCP Server only shows in UI when “type” is incorrect.