# MCP 常见问题

关于 Synapse MCP Server 的常见问题。

## MCP 是什么？

MCP（Model Context Protocol）是 Anthropic 推出的开放标准，用于 LLM 与工具的集成。无需把 API 文档粘到 prompt 里，而是将工具注册到 MCP Server，LLM 像调用原生函数一样调用它们。

参见 [MCP 是什么？](/docs/mcp/what-is-mcp)。

## Synapse MCP 暴露多少个工具？

跨 12 个分类共 **79 个工具**：memory、chat、scheduler、tasks、scripts、computers、push、user、utility、visualization、sharing、webhooks、browser。

完整列表请见 [MCP 是什么？](/docs/mcp/what-is-mcp)。

## 支持哪些 MCP 客户端？

- Claude Desktop（macOS、Windows）
- Claude Code（终端）
- Cursor（IDE）
- Continue.dev（VS Code、JetBrains）
- Cline（VS Code）
- 任何兼容 MCP 的客户端

配置示例请见 [Claude Desktop 配置](/docs/mcp/claude-desktop)。

## 支持哪些传输方式？

1. **stdio**（本地，桌面端推荐）
2. **HTTP/SSE**（远程，多租户）
3. **WebSocket**（移动端，高吞吐）

## 如何配置 Claude Desktop？

编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_YOUR_KEY",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}
```

参见 [Claude Desktop 配置](/docs/mcp/claude-desktop)。

## 为什么 Claude Desktop 中看不到工具？

1. **完全重启 Claude Desktop**（macOS 上 Cmd+Q）
2. **检查配置文件是否为有效 JSON**
3. **确认已安装 Node.js 18+**
4. **查看 MCP 日志**：`~/Library/Logs/Claude/mcp.log`

参见 [MCP 故障排查](/docs/mcp/troubleshooting)。

## 如何切换到另一个 Mind？

在 MCP 配置中修改 `SYNAPSE_MIND_KEY` 并重启客户端。

若要同时使用多个 Mind，可用不同的 Mind Key 运行多个 MCP Server 实例。

## 能限制暴露的工具吗？

可以，使用 **工具配置文件**：

- `minimal`：8 个组合工具（约 500 tokens）
- `standard`：25 个工具（约 2,500 tokens）
- `full`：119 个工具（约 8,250 tokens，默认）

通过 `MCP_PROFILE` 环境变量或 `Mcp-Tool-Profile` 头设置。

## 如何调试 MCP 问题？

1. **手动运行 MCP Server**：`npx -y synapse-mcp-api@latest`
2. **查看客户端日志**（因客户端而异）
3. **验证 Mind Key 是否有效**：`curl -H "Authorization: Bearer mk_..." .../memory/recall`
4. **检查 Synapse 健康**：`curl https://synapse.schaefer.zone/health`

参见 [MCP 故障排查](/docs/mcp/troubleshooting)。

## MCP Server 是免费的吗？

是的。npm 包 `synapse-mcp-api` 是开源的。托管在 `synapse-mcp.schaefer.zone` 的 MCP Server 供公众免费使用。

## 可以自托管 MCP Server 吗？

可以：

```bash
npm install -g synapse-mcp-api
SYNAPSE_URL=https://your-synapse-instance.com \
SYNAPSE_MIND_KEY=mk_... \
synapse-mcp-api
```

## MCP 与直接 API 调用有何不同？

| 方面 | 直接 API | MCP |
|--------|-----------|-----|
| LLM 需要知道 | URL、请求头、认证 | 仅工具名 |
| 认证处理 | 手动 | 自动（环境变量） |
| 工具发现 | 读 /endpoints | 通过 MCP 协议自动 |
| 错误处理 | 手动 | 标准化 |
| 适合场景 | 自定义集成 | LLM Agent |

## 可以构建自己的 MCP 客户端吗？

可以。使用官方 MCP SDK：

- TypeScript：`@modelcontextprotocol/sdk`
- Python：`mcp`

参见 [自定义 MCP 客户端](/docs/mcp/custom-client)。

## 如何报告 MCP Bug？

提交 issue：<https://gitlab.com/schaefer-services/synapse-mcp/-/issues>

请包含：

- MCP Server 版本
- 客户端名称与版本
- 操作系统
- 相关日志
- 复现步骤

## 下一步

- [MCP 是什么？](/docs/mcp/what-is-mcp)
- [Claude Desktop 配置](/docs/mcp/claude-desktop)
- [MCP 故障排查](/docs/mcp/troubleshooting)