# MCP 故障排查
SUMMARY: 解决常见 MCP 集成问题 — 服务器不启动、工具不出现、认证错误。

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

MCP 故障排查
把 Synapse MCP 集成到 LLM 客户端时的常见问题与解决方案。
快速诊断清单
1. ✅ 是否已安装 Node.js 18+？（）
2. ✅ Mind Key 是否以  开头？（不是 JWT 的 ）
3. ✅ Synapse API 是否可达？（）
4. ✅ Mind Key 是否可用？（）
5. ✅ 配置文件是否为有效 JSON？（无尾随逗号、无注释）
6. ✅ 配置更改后是否重启客户端？
7. ✅ MCP Server 是否能手动启动？（）
问题：客户端中没有工具出现
症状
- Claude Desktop / Cursor / Continue 显示 0 个工具
- 没有 🔌 图标或 MCP Server 列表中没有 “synapse” 条目
解决方案
1. 完全重启客户端 — macOS 上 Cmd+Q（不是只关窗口）
2. 检查配置文件位置：
   - Claude Desktop macOS：
   - Claude Desktop Windows：
   - Cursor：
   - Continue：
3. 校验 JSON — 把配置粘到 <https://jsonlint.com>
4. 查看客户端日志中的 MCP 错误：
   - Claude Desktop：（macOS）
   - Cursor：View → Output → MCP
5. 手动运行 MCP Server 以查看启动错误：
   [CODE BLOCK]
问题：“Mind Key invalid” 错误
症状
- 工具出现，但调用失败返回 “401 Unauthorized”
- 错误：“Mind Key fehlt oder ungültig”
解决方案
1. 验证 Mind Key 格式 — 以  开头，约 40 个字符
2. 直接测试：
   [CODE BLOCK]
3. 检查环境变量是否设置 — 对于 stdio 传输，环境变量必须在 MCP Server 配置中，而不是你的 shell
4. 获取新的 Mind Key：
   [CODE BLOCK]
问题：npx 未找到
症状
- 错误：“npx: command not found”
- MCP Server 启动失败
解决方案
1. 安装 Node.js 18+：
   - macOS： 或从 <https://nodejs.org> 下载
   - Linux：
   - Windows：从 <https://nodejs.org> 下载
2. 安装后重启终端
3. 验证：
问题：SYNAPSEURL 不可达
症状
- MCP Server 启动但工具调用超时
- 错误：“fetch failed” 或 “ECONNREFUSED”
解决方案
1. 测试连通性：
   [CODE BLOCK]
2. 检查公司防火墙 — 可能阻挡出站 HTTPS
3. 尝试备用 URL：
   - 生产环境：
   - MCP Server：
4. 自托管：确保 Synapse 实例正在运行且可访问
问题：MCP Server 崩溃
症状
- MCP Server 启动后立即退出
- 客户端日志显示 “MCP server disconnected”
解决方案
1. 手动运行查看错误：
   [CODE BLOCK]
2. 检查端口冲突 — MCP Server 默认使用端口 13100
3. 清除 npx 缓存：
   [CODE BLOCK]
4. 更新到最新版：
   [CODE BLOCK]
问题：工具调用返回 429
症状
- 错误：“Rate limit exceeded”
解决方案
MCP 不应出现此问题（用头部认证，无限制）。如果出现：
1. 检查是否在某处用了  — 改用头部认证
2. 验证  — 确保指向正确实例
3. 若问题持续，联系支持
问题：工具出现但不工作
症状
- 客户端列出了工具
- 调用工具返回错误或无结果
解决方案
1. 检查工具名 — 必须精确（如 ，不是 ）
2. 验证参数 — 检查工具的输入 schema
3. 通过直接 API 测试：
   [CODE BLOCK]
4. 检查 Synapse 健康：
   [CODE BLOCK]
获取帮助
如果以上方案都无法解决：
1. 查看已有 issue：<https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. 提交新 issue，附上：
   - MCP Server 版本（）
   - 客户端名称与版本
   - 操作系统
   - 相关日志片段
   - 复现步骤
下一步
- Claude Desktop 配置
- Claude Code 配置
- API 错误