两万多次调用归纳出 12 类 MCP 故障
作者根据 21,555 次未携带凭据的初始化和工具列表探测归纳远程 MCP 故障,并按观察频率排列检查和修复办法。文章也涵盖本地配置问题,例如 JSON 语法错误或 Windows 路径转义错误导致客户端忽略配置。
AI 深度解读
MCP 服务在 Cursor 或 Claude Code 里亮红点、没有工具,或者列出了工具却调用失败,排查入口各不相同。Serverdex 作者把常见故障整理成 12 类,并用 21,555 次托管服务探测,为其中几类远程故障补上了数字。
这份清单适合按症状读。客户端完全看不到服务,先查配置有没有被读取。远程服务能连上却没有工具,先看状态码和响应内容。工具能列出却用不了,再查调用凭据、服务日志和上下文开销。
服务没出现,先确认客户端读到了配置
第一步是校验 JSON。末尾多一个逗号、两个服务条目之间少一个逗号、从聊天窗口复制了弯引号,都可能让客户端跳过配置。Windows 路径在 JSON 里也要转义,例如 C:\Users 应写成 C:\\Users。MCP 快速入门给 Claude Desktop 用户的第一步,就是检查 claude_desktop_config.json 的语法。
语法通过后,再核对文件路径、配置结构和作用域。Claude Code 和 Cursor 各有自己的读取规则,原文没有逐一列出路径。改完也要确认客户端重新加载了配置。Claude Desktop 在启动时读取配置,需要完全退出再打开。其他客户端有的保存后重载,有的提供刷新按钮。
本地服务启动失败,直接看命令、路径和日志
日志出现 spawn、ENOENT 或 command not found 时,先在终端执行配置里的原命令。桌面应用由操作系统启动,拿到的 PATH 可能和终端不同。通过 nvm 或 pyenv 装好的运行时,在终端里能用,客户端里可能找不到 npx、uvx 或 docker。可以把 which npx 的输出填进 command,也可以全局安装所需运行时。Windows 快速入门还提到,缺少 %APPDATA%\npm 时可尝试 npm install -g npm。
文件系统类服务能启动却找不到目录,就检查 args。客户端的工作目录可能和项目目录不同,传入绝对路径更稳。工具已经列出、每次调用却都报鉴权或配置错误,则检查 env,把 <your API_KEY> 之类的占位符换成实际值。Claude Code 的 --env 和服务名之间要隔一个选项,比如 --transport stdio,否则服务名会被解析成第二组 KEY=value。Windows 上若路径里的 ${APPDATA} 触发 ENOENT,可把 APPDATA 加进 env。
如果服务短暂出现后变红,直接看 stderr。Claude Desktop 的 mcp.log 和 mcp-server-NAME.log 分别可在 macOS 的 ~/Library/Logs/Claude、Windows 的 %APPDATA%\Claude\logs、Linux 的 ~/.config/Claude/logs 下找。手动运行服务还能看到它究竟卡在运行时版本、必填参数,还是端口占用。
远程服务没有工具,先看返回了什么
截至 2026 年 11 月 20 日,Serverdex 同步的官方 MCP Registry 有 41,114 条记录。团队从 11 月 17 日起大约每天探测一次托管服务,不带凭据,发送 initialize 和 tools/list。在作者公布的 21,555 次检查中,13,717 个响应正常,5,371 个返回 401 或 403,1,470 个有响应但没有返回 MCP 协议内容,668 个完全没回应。
对于 401 或 403,先查服务要求的鉴权方式。Cursor、VS Code、Cline、Windsurf、Zed 可以通过 headers 配置密钥,Codex 可以用 bearer token 环境变量。走 OAuth 时,Claude Code 可用 /mcp 或 claude mcp login,Codex 可用 codex mcp login。Zed 会对没有 Authorization 头的 URL 提示登录,Claude Desktop 则从 Connectors 进入。按作者 2026 年 11 月 19 日查阅的客户端文档,Windsurf 的 stdio 服务不支持 OAuth。
如果期待 JSON-RPC,实际却收到 HTML,先核对 URL。文档页、旧路径和只在服务所在机器上生效的 localhost 都可能被误填进去。用服务文档给出的端点,常见路径以 /mcp 结尾。端点可达但握手卡住,再核对传输方式。Cline 只配 url 时默认走旧版 SSE,使用 Streamable HTTP 要写 "type": "streamableHttp"。VS Code 区分 "type": "http" 和 "type": "sse"。Claude Code 的 .mcp.json 可写 "type": "http",CLI 对应 --transport http。按原文,从 v2.1.265 起 Claude Code 先试 HTTP 再回退,旧版本连 SSE 要显式传 --transport sse。Continue 的 YAML 则写 type: streamable-http。
工具列出来了,模型为什么还是不用
工具定义也占上下文。作者估算,在有响应的服务中,单个服务的工具定义开销中位数约为 4.8k tokens,有些服务高得多。工具定义随请求提供给模型,所以即使还没执行工具,启用的工具也会影响上下文预算。连接正常但模型变慢、常挑错工具,或者客户端提示工具过多时,可以先关掉当前项目用不到的服务。客户端支持筛选工具的话,只保留任务所需的那几个。
我的判断
我会把这份清单当成按症状查找的索引。远程探测直接记录了状态码、响应类型和超时情况,足以说明为什么远程服务没有工具时,先查鉴权和端点比反复重启客户端更有针对性。无凭据请求收到 401 或 403 后,仍需结合服务文档区分缺少凭据和权限受限。一次超时也只能说明那次探测没有收到响应,作者因此记录连续失败次数。
开头把 12 类问题按常见程度排序,但托管端探测看不到用户本机的 JSON、PATH 或配置作用域,这几项的排序属于经验之谈。原文列出的四组远程结果合计 21,226,和总数相差 329,作者没有交代差额。4.8k tokens 也是工具定义的估算值,原文没有提供不同工具数量下的延迟或调用成功率对照,适合用来估算上下文预算。
能拿来做什么
- 在 Cursor 或 Claude Code 接入本地 Node MCP 服务时,先校验 JSON,再手动运行
command和args。终端能跑而客户端报ENOENT时,优先核对客户端的PATH和可执行文件绝对路径。 - 接入远程 MCP 时,先记录状态码和响应类型。遇到
401或403就查鉴权,收到 HTML 就核对端点,端点可达但握手失败再查传输设置。 - 给日常 AI 编程项目按需启用 MCP 服务。工具已经列出却经常选错时,先停用当前任务无关的服务,再用同一个任务复测。