Claude Desktop 或 Claude Code 启动时显示 “MCP server connected”，过几分钟工具列表里那个 server 就变灰、显示 “disconnected”——你点 “reconnect” 又能连上，几分钟后又掉。这是 Claude MCP（Model Context Protocol）集成的典型问题，根因通常在 server 进程、OAuth token 或本地 config 路径三处之一。
MCP 不是 HTTP 长连接，它是 Claude 启动一个本地子进程（或连接远程 HTTP MCP）通过 stdin/stdout 通信。子进程崩、network 抖、auth 过期任一都会让连接断开。
常见原因
按命中率从高到低：
1. 本地 MCP server 进程崩或被系统 kill
stdio 模式的 MCP server 是 Claude 启动的 Node / Python 子进程。它可能因为内存超限被 OS kill、未捕获异常自爆、或 Node 版本不匹配启不来。
如何判断：在 Claude Desktop 用 Help → Open Logs，搜 “spawn” 或 “exit”。出现 “exited with code 1” / “killed” 就是这种情况。
2. OAuth token 过期，server 没自动刷新
远程 MCP（如 Slack、Linear 的官方 MCP）走 OAuth。token 过期时部分实现没自动 refresh，client 端表现为”连上但所有调用 401”。
如何判断：MCP 工具调用时返回 “unauthorized” / “401” 错误，重新走一次 Settings → MCP → Reconnect 后就好。
3. mcp.json / claude_desktop_config.json 路径错或权限不够
最高频的本地坑。配置文件里 args 里的脚本路径用了相对路径、或指向了一个不存在的目录、或 Claude 进程没读权限。
如何判断：日志里出现 ENOENT: no such file or directory 或 EACCES: permission denied。
4. Node / Python 版本不匹配
MCP server 要求 Node 18+ 或 Python 3.10+，但你的 PATH 第一个 node 是旧版（比如系统自带的 14）。Claude 子进程继承 PATH，启动失败。
如何判断：在终端 which node && node -v，对照 server 的 README 要求。
5. 网络环境拦截了远程 MCP 的 SSE
某些远程 MCP 用 Server-Sent Events 通信，企业代理或 firewall 可能切断长连接。表现为定时（30-60 秒）就掉一次。
如何判断：断开间隔很规律（每 30s / 60s），且只对远程 MCP 发生。
6. macOS Gatekeeper / 防火墙阻止本地 server 监听
第一次启动新 MCP server 时 macOS 弹窗”允许网络连接”，如果你不小心点了”拒绝”，之后 server 静默失败。
如何判断：系统设置 → 网络 → 防火墙 → 选项里，看 Claude 或对应 server 是否被显式 block。
最短修复路径
Step 1：先看日志
Claude Desktop：
macOS: ~/Library/Logs/Claude/mcp*.log
Windows: %APPDATA%\Claude\logs\
Help → Open Logs Folder（菜单里有）Claude Code：
claude --debug
# 或在会话里：/doctor找最近一次断开时间附近的 MCP 相关日志。
Step 2：用绝对路径修 mcp.json
打开配置（macOS Desktop 在 ~/Library/Application Support/Claude/claude_desktop_config.json），改成：
{
"mcpServers": {
"filesystem": {
"command": "/Users/you/.nvm/versions/node/v20.10.0/bin/node",
"args": [
"/Users/you/code/mcp-filesystem/dist/index.js",
"/Users/you/Documents"
]
}
}
}关键点：
command用which node拿到的绝对路径，不要写"node"args里所有路径都是绝对路径- 路径里有空格用反斜杠转义或加引号
Step 3：手动跑一次确认 server 能起来
把 config 里的 command + args 复制到终端跑：
/Users/you/.nvm/versions/node/v20.10.0/bin/node \
/Users/you/code/mcp-filesystem/dist/index.js \
/Users/you/Documents如果终端里跑都报错，那 Claude 也起不来。先把 Node 版本、依赖装好。
Step 4：远程 MCP 重新走 OAuth
Settings → MCP → 找到失效的 server → Disconnect → Connect。授权后 MCP 工具立即可用。如果不行，检查目标平台（Slack/Linear/etc）的 admin 是否撤销了 App 授权。
Step 5：版本对齐
node -v # 应该 >= 18
python3 -V # 应该 >= 3.10
which node如果系统有多个版本，可以在 mcp.json 的 command 里显式写 nvm 路径。或者用 env 把 PATH 调整好：
{
"command": "node",
"args": ["..."],
"env": {
"PATH": "/Users/you/.nvm/versions/node/v20.10.0/bin:/usr/bin:/bin"
}
}Step 6：网络 / 防火墙排查
# 看 Claude 主进程是否被 firewall 阻止
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps | grep -i claude
# 如有需要，重置
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --remove /Applications/Claude.app
# 然后重启 Claude，按提示 Allow企业网络下远程 MCP 走 SSE 被 cut，让 IT 把 anthropic.com 和具体 MCP 的域名加白名单。
预防建议
- MCP server 安装后跑一次
mcp list（Claude Code）或在 Desktop 工具列表里手动 verify；任何 path 改动加注释 - 用 absolute path，永远不要在 mcp.json 里用
~或./ - 锁定 Node 版本（nvm + .nvmrc）防止系统升级后断
- 远程 MCP 把 token 过期时间记在 Notion / wiki 里，提前刷新
- macOS 首次启动新 MCP server，仔细看防火墙弹窗别误点 Deny
- mcp.json 用 git 管，改坏了能 rollback