Skip to main content

MCP 故障排查

intermediate 🤖 LLM 友好 2 分钟 · 342 字 更新于： 2026-06-27 中文

解决常见 MCP 集成问题 — 服务器不启动、工具不出现、认证错误。

阅读本文： 📄 纯文本 ⚡ JSON 🤖 LLM 格式
语言: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

MCP 故障排查

把 Synapse MCP 集成到 LLM 客户端时的常见问题与解决方案。

快速诊断清单

  1. ✅ 是否已安装 Node.js 18+？（node --version）
  2. ✅ Mind Key 是否以 mk_ 开头？（不是 JWT 的 eyJ...）
  3. ✅ Synapse API 是否可达？（curl https://synapse.schaefer.zone/health）
  4. ✅ Mind Key 是否可用？（curl -H "Authorization: Bearer mk_..." .../memory/recall）
  5. ✅ 配置文件是否为有效 JSON？（无尾随逗号、无注释）
  6. ✅ 配置更改后是否重启客户端？
  7. ✅ MCP Server 是否能手动启动？（npx -y synapse-mcp-api@latest）

问题：客户端中没有工具出现

症状

  • Claude Desktop / Cursor / Continue 显示 0 个工具
  • 没有 🔌 图标或 MCP Server 列表中没有 “synapse” 条目

解决方案

  1. 完全重启客户端 — macOS 上 Cmd+Q（不是只关窗口）
  2. 检查配置文件位置：
    • Claude Desktop macOS：~/Library/Application Support/Claude/claude_desktop_config.json
    • Claude Desktop Windows：%APPDATA%\Claude\claude_desktop_config.json
    • Cursor：~/.cursor/config.json
    • Continue：~/.continue/config.json
  3. 校验 JSON — 把配置粘到 https://jsonlint.com
  4. 查看客户端日志中的 MCP 错误：
    • Claude Desktop：~/Library/Logs/Claude/mcp.log（macOS）
    • Cursor：View → Output → MCP
  5. 手动运行 MCP Server 以查看启动错误：
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

问题：“Mind Key invalid” 错误

症状

  • 工具出现，但调用失败返回 “401 Unauthorized”
  • 错误：“Mind Key fehlt oder ungültig”

解决方案

  1. 验证 Mind Key 格式 — 以 mk_ 开头，约 40 个字符
  2. 直接测试：
    curl -H "Authorization: Bearer mk_YOUR_KEY" \
     https://synapse.schaefer.zone/memory/recall
  3. 检查环境变量是否设置 — 对于 stdio 传输，环境变量必须在 MCP Server 配置中，而不是你的 shell
  4. 获取新的 Mind Key：
    # 登录获取 JWT
curl -X POST .../login -d '{"email":"...","password":"..."}'
# 创建新 Mind
curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

问题：npx 未找到

症状

  • 错误：“npx: command not found”
  • MCP Server 启动失败

解决方案

  1. 安装 Node.js 18+：
    • macOS：brew install node 或从 https://nodejs.org 下载
    • Linux：curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
    • Windows：从 https://nodejs.org 下载
  2. 安装后重启终端
  3. 验证：node --version && npx --version

问题：SYNAPSE_URL 不可达

症状

  • MCP Server 启动但工具调用超时
  • 错误：“fetch failed” 或 “ECONNREFUSED”

解决方案

  1. 测试连通性：
    curl https://synapse.schaefer.zone/health
  2. 检查公司防火墙 — 可能阻挡出站 HTTPS
  3. 尝试备用 URL：
    • 生产环境：https://synapse.schaefer.zone
    • MCP Server：https://synapse-mcp.schaefer.zone
  4. 自托管：确保 Synapse 实例正在运行且可访问

问题：MCP Server 崩溃

症状

  • MCP Server 启动后立即退出
  • 客户端日志显示 “MCP server disconnected”

解决方案

  1. 手动运行查看错误：
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
  npx -y synapse-mcp-api@latest
  2. 检查端口冲突 — MCP Server 默认使用端口 13100
  3. 清除 npx 缓存：
    npx clear-npx-cache
# 或
rm -rf ~/.npm/_npx
  4. 更新到最新版：
    npx -y synapse-mcp-api@latest --version

问题：工具调用返回 429

症状

  • 错误：“Rate limit exceeded”

解决方案

MCP 不应出现此问题（用头部认证，无限制）。如果出现：

  1. 检查是否在某处用了 ?key= — 改用头部认证
  2. 验证 SYNAPSE_URL — 确保指向正确实例
  3. 若问题持续，联系支持

问题：工具出现但不工作

症状

  • 客户端列出了工具
  • 调用工具返回错误或无结果

解决方案

  1. 检查工具名 — 必须精确（如 memory_recall，不是 memory.recall）
  2. 验证参数 — 检查工具的输入 schema
  3. 通过直接 API 测试：
    curl -X POST https://synapse.schaefer.zone/memory \
  -H "Authorization: Bearer mk_..." \
  -H "Content-Type: application/json" \
  -d '{"category":"fact","key":"test","content":"hello"}'
  4. 检查 Synapse 健康：
    curl https://synapse.schaefer.zone/health

获取帮助

如果以上方案都无法解决：

  1. 查看已有 issue：https://gitlab.com/schaefer-services/synapse-mcp/-/issues
  2. 提交新 issue，附上：
    • MCP Server 版本（npx -y synapse-mcp-api@latest --version）
    • 客户端名称与版本
    • 操作系统
    • 相关日志片段
    • 复现步骤

下一步

← 返回 MCP 集成