# 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** 以查看启动错误：
   ```bash
   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. **直接测试**：
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **检查环境变量是否设置** — 对于 stdio 传输，环境变量必须在 MCP Server 配置中，而不是你的 shell
4. **获取新的 Mind Key**：
   ```bash
   # 登录获取 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. **测试连通性**：
   ```bash
   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. **手动运行查看错误**：
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **检查端口冲突** — MCP Server 默认使用端口 13100
3. **清除 npx 缓存**：
   ```bash
   npx clear-npx-cache
   # 或
   rm -rf ~/.npm/_npx
   ```
4. **更新到最新版**：
   ```bash
   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 测试**：
   ```bash
   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 健康**：
   ```bash
   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`）
   - 客户端名称与版本
   - 操作系统
   - 相关日志片段
   - 复现步骤

## 下一步

- [Claude Desktop 配置](/docs/mcp/claude-desktop)
- [Claude Code 配置](/docs/mcp/claude-code)
- [API 错误](/docs/api/errors)