你往配置里加了一个MCP服务器。JSON校验通过，客户端甚至显示“已连接”。然后呢？零工具。没有报错，没有提示。官方/doctor也查不出任何问题。

如果你也遇到过这种情况，欢迎入坑——GitHub issues里全是难兄难弟：Windows上npx连接失败（112条评论）；NVM环境不兼容（182个回应）；服务器名称带括号导致工具被静默丢弃；/doctor对配置错误视而不见。

翻遍这些讨论帖，失败原因其实集中在几个点上——而且没有一个是MCP服务器本身的问题。全是客户端配置的坑，官方工具却不帮你查。下面是完整避坑指南。

坑1：服务器名称里的括号（或方括号）

{"mcpServers": {"Home Assistant (ha-mcp)": { "command": "npx", "args": ["-y", "ha-mcp"] }

看起来人畜无害。但至少有一款主流客户端，只要mcpServers键名里带括号，就会静默丢掉所有工具。服务器显示已连接，tools/list正常响应，界面上却什么都不显示。有个老哥排查了好几个小时才缓过神来。

修复方法：重命名键名——只用字母、数字、连字符和下划线。

坑2：Windows上直接调 npx

{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] }

Windows上的GUI应用经常直接拉起npx失败。终端里用得好好的，桌面客户端就是不行——因为GUI进程拿不到你的shell环境变量。

修复方法：包一层壳解决：

{ "command": "cmd", "args": ["/c", "npx", "-y", "..."] }
坑3：NVM（或任意版本管理器）路径问题

终端里npx能跑，是因为shell加载了NVM。GUI应用不加载你的shell配置文件，所以二进制文件根本不在它们的PATH里。上面那篇182个回应的issue就是这个原因。

修复方法：用二进制文件的绝对路径，或者放一个GUI能解析的shim。

坑4：看起来没毛病的JSON

一个没转义的Windows路径（比如"cwd": "C:\tools\my-server"）就能让整个配置静默解析失败。有些客户端会报告错误，其他客户端干脆显示零服务器。

修复方法：路径里的反斜杠写成双反斜杠，或者干脆用正斜杠C:/tools/my-server。

坑5：加载顺序与重启时机

改了配置之后，不少人忘了彻底退出客户端再重启（不只是关窗口）。客户端启动时读取配置，改动后没重启就不会生效——最经典的“连上了等于没连上”。

修复方法：改完配置先完全退出，再重新启动客户端。

最后补一句：遇到“已连接但零工具”，先别怀疑服务器，按上面的清单逐一排查客户端配置，大概率能救回来。你在哪一步掉过坑？评论区聊聊。