{"title":"MCP 故障排查","slug":"troubleshooting","category":"mcp","summary":"解决常见 MCP 集成问题 — 服务器不启动、工具不出现、认证错误。","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":342,"read_minutes":2,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# MCP 故障排查\n\n把 Synapse MCP 集成到 LLM 客户端时的常见问题与解决方案。\n\n## 快速诊断清单\n\n1. ✅ 是否已安装 Node.js 18+？（`node --version`）\n2. ✅ Mind Key 是否以 `mk_` 开头？（不是 JWT 的 `eyJ...`）\n3. ✅ Synapse API 是否可达？（`curl https://synapse.schaefer.zone/health`）\n4. ✅ Mind Key 是否可用？（`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`）\n5. ✅ 配置文件是否为有效 JSON？（无尾随逗号、无注释）\n6. ✅ 配置更改后是否重启客户端？\n7. ✅ MCP Server 是否能手动启动？（`npx -y synapse-mcp-api@latest`）\n\n## 问题：客户端中没有工具出现\n\n### 症状\n\n- Claude Desktop / Cursor / Continue 显示 0 个工具\n- 没有 🔌 图标或 MCP Server 列表中没有 “synapse” 条目\n\n### 解决方案\n\n1. **完全重启客户端** — macOS 上 Cmd+Q（不是只关窗口）\n2. **检查配置文件位置**：\n - Claude Desktop macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows：`%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor：`~/.cursor/config.json`\n - Continue：`~/.continue/config.json`\n3. **校验 JSON** — 把配置粘到 \n4. **查看客户端日志**中的 MCP 错误：\n - Claude Desktop：`~/Library/Logs/Claude/mcp.log`（macOS）\n - Cursor：View → Output → MCP\n5. **手动运行 MCP Server** 以查看启动错误：\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## 问题：“Mind Key invalid” 错误\n\n### 症状\n\n- 工具出现，但调用失败返回 “401 Unauthorized”\n- 错误：“Mind Key fehlt oder ungültig”\n\n### 解决方案\n\n1. **验证 Mind Key 格式** — 以 `mk_` 开头，约 40 个字符\n2. **直接测试**：\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **检查环境变量是否设置** — 对于 stdio 传输，环境变量必须在 MCP Server 配置中，而不是你的 shell\n4. **获取新的 Mind Key**：\n ```bash\n # 登录获取 JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # 创建新 Mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## 问题：npx 未找到\n\n### 症状\n\n- 错误：“npx: command not found”\n- MCP Server 启动失败\n\n### 解决方案\n\n1. **安装 Node.js 18+**：\n - macOS：`brew install node` 或从 下载\n - Linux：`curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows：从 下载\n2. 安装后**重启终端**\n3. **验证**：`node --version && npx --version`\n\n## 问题：SYNAPSE_URL 不可达\n\n### 症状\n\n- MCP Server 启动但工具调用超时\n- 错误：“fetch failed” 或 “ECONNREFUSED”\n\n### 解决方案\n\n1. **测试连通性**：\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **检查公司防火墙** — 可能阻挡出站 HTTPS\n3. **尝试备用 URL**：\n - 生产环境：`https://synapse.schaefer.zone`\n - MCP Server：`https://synapse-mcp.schaefer.zone`\n4. **自托管**：确保 Synapse 实例正在运行且可访问\n\n## 问题：MCP Server 崩溃\n\n### 症状\n\n- MCP Server 启动后立即退出\n- 客户端日志显示 “MCP server disconnected”\n\n### 解决方案\n\n1. **手动运行查看错误**：\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **检查端口冲突** — MCP Server 默认使用端口 13100\n3. **清除 npx 缓存**：\n ```bash\n npx clear-npx-cache\n # 或\n rm -rf ~/.npm/_npx\n ```\n4. **更新到最新版**：\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## 问题：工具调用返回 429\n\n### 症状\n\n- 错误：“Rate limit exceeded”\n\n### 解决方案\n\nMCP 不应出现此问题（用头部认证，无限制）。如果出现：\n\n1. **检查是否在某处用了 `?key=`** — 改用头部认证\n2. **验证 `SYNAPSE_URL`** — 确保指向正确实例\n3. 若问题持续，**联系支持**\n\n## 问题：工具出现但不工作\n\n### 症状\n\n- 客户端列出了工具\n- 调用工具返回错误或无结果\n\n### 解决方案\n\n1. **检查工具名** — 必须精确（如 `memory_recall`，不是 `memory.recall`）\n2. **验证参数** — 检查工具的输入 schema\n3. **通过直接 API 测试**：\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **检查 Synapse 健康**：\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## 获取帮助\n\n如果以上方案都无法解决：\n\n1. **查看已有 issue**：\n2. **提交新 issue**，附上：\n - MCP Server 版本（`npx -y synapse-mcp-api@latest --version`）\n - 客户端名称与版本\n - 操作系统\n - 相关日志片段\n - 复现步骤\n\n## 下一步\n\n- [Claude Desktop 配置](/docs/mcp/claude-desktop)\n- [Claude Code 配置](/docs/mcp/claude-code)\n- [API 错误](/docs/api/errors)\n","content_html":"

MCP 故障排查

\n

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

\n

快速诊断清单

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

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

\n

症状

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

解决方案

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

问题：“Mind Key invalid” 错误

\n

症状

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

解决方案

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

问题：npx 未找到

\n

症状

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

解决方案

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

问题：SYNAPSE_URL 不可达

\n

症状

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

解决方案

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

问题：MCP Server 崩溃

\n

症状

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

解决方案

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

问题：工具调用返回 429

\n

症状

\n
    \n
  • 错误：“Rate limit exceeded”
    • \n
\n

解决方案

\n

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

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

问题：工具出现但不工作

\n

症状

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

解决方案

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

获取帮助

\n

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

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

下一步

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}