“助手看不到我的数据”这句抱怨，最常见的原因并不是服务器坏了，而是配置改完之后
客户端从未重启。多数 MCP 客户端只在启动时读一次配置，此后不再读，所以您在应用
开着的时候编辑的文件，正是应用没有读过的文件。请把它彻底退出——在 macOS 上关闭
窗口只会让进程继续留着——再重新打开。在 Claude Code 里则运行 /mcp，不必重启
终端。
如果这样还不行，接下来有用的问题不是“我用的是哪个客户端”，而是“究竟发生了 什么”。服务器根本不出现、服务器连上了却没有任何工具、工具返回空结果、工具只在 试图改动什么的时候才失败——这是四种不同的故障，对应四种不同的修法，而且修法几乎 与您运行的是哪个应用无关。本文的每一处细节，都于 2026 年 8 月 14 日对照厂商 文档核对过。
在动手改任何东西之前，先看看客户端已经知道什么。每个客户端都恰好有一个地方能 回答“这台服务器连上了吗”，而不去看它、只从聊天窗口猜，正是人们把一个界面一秒 就能说清的问题拖成一小时的原因。
| 客户端 | 看哪里 | 健康的服务器长什么样 |
|---|---|---|
| Claude Code | claude mcp list 或 /mcp 面板 |
✔ Connected |
| Claude Desktop | 聊天输入框里的加号图标 → Connectors | 服务器连同它的工具一起列出 |
| Cursor | Output 面板（Cmd+Shift+U）→ MCP Logs |
有初始化记录，没有连接错误 |
| VS Code | Command Palette 里的 MCP: List Servers | 服务器能启动，Show Output 日志干净 |
| Zed | Settings → AI → MCP Servers | 绿点，提示为 Server is active |
其中信息量最大的是 Claude Code。claude mcp list 会在每台服务器旁边打印健康
状态——✔ Connected、! Needs authentication、✘ Failed to connect、
⏸ Pending approval——并把失败详情追加在同一行；claude mcp get <name> 在
Issue: 那一行给出同样的信息，包括服务器自己返回的错误文本。
如果状态界面完全看不到您的服务器，说明客户端没有读到您写的那条记录。几乎所有 情况都出自三个原因。
文件解析不成合法的 JSON。 多一个尾逗号或少一个花括号，客户端就会忽略整个 文件——不只是坏掉的那一条——而且通常不会说一声。在怀疑别的东西之前，先把文件 贴进任意一个 JSON 校验器。
您编辑的不是客户端会读的那个文件。 几乎每个客户端都同时有个人配置和项目
范围的配置，改错一个就会得到正好这个症状。Cursor 全局读 ~/.cursor/mcp.json，
在项目内读 .cursor/mcp.json；VS Code 读工作区的 .vscode/mcp.json，以及用
MCP: Open User Configuration 打开的用户配置文件 mcp.json。Claude Code 有
三个范围——local 和 user 在 ~/.claude.json 里，project 在仓库根目录的
.mcp.json 里——同一个名字若在多个范围中定义，local 胜过 project，project 胜过
user。整条记录都来自胜出的那个范围，字段不会被合并。
键名对这个客户端来说是错的。 VS Code 的顶层键是 servers，Zed 的是
context_servers，其他人都用 mcpServers。粘进 VS Code 的 mcpServers 块并
不是编辑器会报出来的错误，它只是一个不被读取的键。逐个客户端的说明见
MCP 配置文件到底在哪里。
有一种情况看着像服务器不见了，其实不是：在 Claude Code 里，项目范围的服务器会
停在 ⏸ Pending approval，直到您在那个目录里交互式运行 claude 并批准它；而
提交进仓库的批准记录，在您信任该工作区之前一律不算数。
配置里什么都没改、服务器却连不上时，配置里通常仍然写着一条指向已经不存在的
程序的绝对路径。把应用更新到了另一个文件夹、给它改了名、把它移出 Applications，
都会在 JSON 看起来仍然正确的情况下弄坏这条路径，而客户端的报错里没有任何东西
指向这次移动。先于一切，把 command 的值和现实对一下：
ls -l "/absolute/path/from/your/config"
同一类故障也会打中通过版本管理器启动的服务器。如果 command 是 node、
npx、python 或 uv，而您的运行时来自 nvm、pyenv 或 asdf，那么这条路径在
您的终端里存在，对客户端却不存在，因为客户端不会启动登录 shell。把裸名字换成
绝对路径——which node 会告诉您——或者让 command 直接指向那个可执行文件。
状态是绿的而工具列表是空的，意味着握手成功了，但 tools/list 没返回有用的
东西。造成这种情况的有两件事。
第一是服务器确实报告了一个空的工具集。这一点可以在客户端之外用 MCP Inspector 确认——那是官方的测试界面，直接连到 stdio 或 Streamable HTTP 服务器，把它公开 的东西列出来。如果 Inspector 看得到工具而您的客户端看不到，问题出在客户端的 配置上。
第二是工具上限。VS Code 把单次聊天请求限制在 128 个已启用的工具以内，总数超出 时会直接拒绝该请求，而一台装得满满的机器达到这个数比您以为的更快；把服务器 关掉几个以回到上限之下，用的是 Chat 视图里的 Configure Tools 按钮。Cursor 允许您在侧边栏的 Customize 面板里逐个禁用服务器，被禁用的服务器不会加载， 也不会出现在聊天里——这一点值得先查，因为某人上个月拨过的一个开关，看起来和 一台启动失败的服务器一模一样。
工具列出来了，助手也调用了，结果却是空的。这里传输没有问题，问题出在数据而不是 配置。请确认服务器读取的资料库就是您心里想的那一个：账号对、设备对，而且内容 确实已经同步到这台机器，而不是只存在于另一台上。然后在客户端的日志里查看工具的 调用参数：一个猜了日期范围或过滤条件的助手，完全可以从一份健康的资料库里得到 空结果。
如果搜索能成功，而每一次重命名、打标签或更新的尝试都失败，这不是传输问题。 服务器通常会分成读取数据的工具和改动数据的工具，而改动的那一半往往带着额外的 前提条件：应用要在运行、会话要已认证、某项权限客户端还没拿到。有两个客户端侧的 原因值得先排除。改动数据的工具会被声明为这一类，因此客户端在运行前会先问一句 ——而您顺手关掉的那个确认，在记录里读起来就是一次失败。另外，以只读标志启动的 服务器根本不会公开这些工具，这是一个配置选择，不是故障。
这是服务器的问题而不是您的，但值得认得出来，因为那条报错很容易让人误解。在
stdio 上，协议要求标准输出里除了 JSON-RPC 消息之外不能有别的东西，所以一台把
版本横幅、一行“正在启动”的提示或彩色日志打到 stdout 的服务器会把这条流弄脏，
客户端随即以一个解析错误失败，并把打印出来的头几个字符引在里面——
Unexpected token 'S', "Starting s"... is not valid JSON。这该由服务器的作者
来修：日志应当写到 stderr，宿主本来就会把它收下。
另一个启动期的陷阱是环境。stdio 服务器只会继承一小部分随平台而定的环境变量，
而不是您的 shell 配置，而且它的工作目录可能是未定义的，在 macOS 上实际相当于
/。请把服务器需要的东西通过其配置条目里的 env 键传进去，并且让每一条路径
都是绝对路径。
command 里的路径确实存在，而且是绝对路径。从头往下走要花一分钟。从第七步开始，才是把一个五秒钟的问题拖成一个下午的办法。
Speak-Y 把它的 MCP 服务器随 macOS 应用一起分发，所以上面几种失败对它根本不会
发生：没有要装的 npm 包，没有需要通过 nvm 解析的运行时，也没有会过期的令牌。
可能发生的只有路径过期这一种，而应用会自己把它修好。启动时它会检查 Claude
Code、Claude Desktop 和 Cursor 的配置，并在 command 的值指向应用旧位置时把它
改写——只针对确实属于它自己的条目，靠应用的可执行文件和 --mcp 参数来匹配，
所以碰巧同名的另一台服务器不会被改动。如果需要手动处理，设置 → 集成里每个
检测到的客户端旁边都有重新安装；点完之后重启客户端，或者在 Claude Code 里
运行 /mcp。
读取与改动之间的这道分界，是另一个值得认得出来的症状。搜索录音，以及读取转写、
摘要和待办事项，都直接在这台机器上的资料库里完成，不需要别的东西在运行。那些
用来整理的工具——标签、标题、发言人姓名、重新转写、发布到
团队频道——都要经过正在运行的应用，所以在 Speak-Y 已退出时它们会失败，
而搜索照常可用。这种不对称本身就是一种诊断：如果读取正常而改动不行，
请去启动应用，而不是去改任何配置。在服务器的参数里加上 --read-only，会把
改动类的工具从客户端的视野里整个拿掉——这是设计如此，不是出了毛病。一台健康的
服务器返回空结果，通常意味着那段录音还在另一台设备上：服务器读的是这块磁盘，
不会去取别处的东西。
如果您是在做初次设置而不是修问题，逐个客户端的教程比本页更有用： Claude Desktop 与 Claude Code 一步步来，而 VS Code、Zed 和 Devin Desktop 面向那几个配置形状与众不同的编辑器。
多数客户端只在启动时读取 MCP 配置，因此在客户端运行期间写入的配置还没有被加载。请完全退出应用再重新打开——在 macOS 上关闭窗口并不够——在 Claude Code 里则运行 /mcp，不必重启终端。
每个客户端都有一个地方回答这个问题。Claude Code：claude mcp list，它会在每台服务器旁边打印 ✔ Connected、! Needs authentication 或 ✘ Failed to connect。Claude Desktop：聊天输入框里的加号图标，然后是 Connectors。VS Code：从 Command Palette 运行 MCP: List Servers。Cursor：Output 面板并选中 MCP Logs。Zed：Settings → AI → MCP Servers，绿点的提示为 Server is active。
在 macOS 上是 ~/Library/Logs/Claude，在 Windows 上是 %APPDATA%\Claude\logs。可以用 tail -n 20 -F ~/Library/Logs/Claude/mcp*.log 实时跟踪。mcp.log 记录一般的连接事件，mcp-server-NAME.log 记录那台服务器写到 stderr 的内容。
客户端是自己启动这个进程的，不经过您的登录 shell。它不会继承您完整的 PATH，只有一小部分随平台而定的环境变量，而且工作目录可能是未定义的。请为 command 使用绝对路径，参数里也用绝对路径，需要的变量通过 env 键显式传入。
几乎总是 MCP 配置里的绝对路径，它仍然指向应用原来所在的位置。重装到另一个文件夹、给应用改名、把它移出 Applications，都会在配置看起来仍然正确的情况下把路径弄坏。重新运行该客户端的一键安装，让路径被改写即可。