{"title":"MCP 常见问题","slug":"mcp-faq","category":"faq","summary":"关于 MCP 集成的常见问题 — 工具、传输、故障排查。","audience":["human","llm"],"tags":["faq","mcp","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":273,"read_minutes":1,"lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# MCP 常见问题\n\n关于 Synapse MCP Server 的常见问题。\n\n## MCP 是什么？\n\nMCP（Model Context Protocol）是 Anthropic 推出的开放标准，用于 LLM 与工具的集成。无需把 API 文档粘到 prompt 里，而是将工具注册到 MCP Server，LLM 像调用原生函数一样调用它们。\n\n参见 [MCP 是什么？](/docs/mcp/what-is-mcp)。\n\n## Synapse MCP 暴露多少个工具？\n\n跨 12 个分类共 **79 个工具**：memory、chat、scheduler、tasks、scripts、computers、push、user、utility、visualization、sharing、webhooks、browser。\n\n完整列表请见 [MCP 是什么？](/docs/mcp/what-is-mcp)。\n\n## 支持哪些 MCP 客户端？\n\n- Claude Desktop（macOS、Windows）\n- Claude Code（终端）\n- Cursor（IDE）\n- Continue.dev（VS Code、JetBrains）\n- Cline（VS Code）\n- 任何兼容 MCP 的客户端\n\n配置示例请见 [Claude Desktop 配置](/docs/mcp/claude-desktop)。\n\n## 支持哪些传输方式？\n\n1. **stdio**（本地，桌面端推荐）\n2. **HTTP/SSE**（远程，多租户）\n3. **WebSocket**（移动端，高吞吐）\n\n## 如何配置 Claude Desktop？\n\n编辑 `claude_desktop_config.json`：\n\n```json\n{\n \"mcpServers\": {\n \"synapse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"synapse-mcp-api@latest\"],\n \"env\": {\n \"SYNAPSE_MIND_KEY\": \"mk_YOUR_KEY\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\"\n }\n }\n }\n}\n```\n\n参见 [Claude Desktop 配置](/docs/mcp/claude-desktop)。\n\n## 为什么 Claude Desktop 中看不到工具？\n\n1. **完全重启 Claude Desktop**（macOS 上 Cmd+Q）\n2. **检查配置文件是否为有效 JSON**\n3. **确认已安装 Node.js 18+**\n4. **查看 MCP 日志**：`~/Library/Logs/Claude/mcp.log`\n\n参见 [MCP 故障排查](/docs/mcp/troubleshooting)。\n\n## 如何切换到另一个 Mind？\n\n在 MCP 配置中修改 `SYNAPSE_MIND_KEY` 并重启客户端。\n\n若要同时使用多个 Mind，可用不同的 Mind Key 运行多个 MCP Server 实例。\n\n## 能限制暴露的工具吗？\n\n可以，使用 **工具配置文件**：\n\n- `minimal`：8 个组合工具（约 500 tokens）\n- `standard`：25 个工具（约 2,500 tokens）\n- `full`：119 个工具（约 8,250 tokens，默认）\n\n通过 `MCP_PROFILE` 环境变量或 `Mcp-Tool-Profile` 头设置。\n\n## 如何调试 MCP 问题？\n\n1. **手动运行 MCP Server**：`npx -y synapse-mcp-api@latest`\n2. **查看客户端日志**（因客户端而异）\n3. **验证 Mind Key 是否有效**：`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`\n4. **检查 Synapse 健康**：`curl https://synapse.schaefer.zone/health`\n\n参见 [MCP 故障排查](/docs/mcp/troubleshooting)。\n\n## MCP Server 是免费的吗？\n\n是的。npm 包 `synapse-mcp-api` 是开源的。托管在 `synapse-mcp.schaefer.zone` 的 MCP Server 供公众免费使用。\n\n## 可以自托管 MCP Server 吗？\n\n可以：\n\n```bash\nnpm install -g synapse-mcp-api\nSYNAPSE_URL=https://your-synapse-instance.com \\\nSYNAPSE_MIND_KEY=mk_... \\\nsynapse-mcp-api\n```\n\n## MCP 与直接 API 调用有何不同？\n\n| 方面 | 直接 API | MCP |\n|--------|-----------|-----|\n| LLM 需要知道 | URL、请求头、认证 | 仅工具名 |\n| 认证处理 | 手动 | 自动（环境变量） |\n| 工具发现 | 读 /endpoints | 通过 MCP 协议自动 |\n| 错误处理 | 手动 | 标准化 |\n| 适合场景 | 自定义集成 | LLM Agent |\n\n## 可以构建自己的 MCP 客户端吗？\n\n可以。使用官方 MCP SDK：\n\n- TypeScript：`@modelcontextprotocol/sdk`\n- Python：`mcp`\n\n参见 [自定义 MCP 客户端](/docs/mcp/custom-client)。\n\n## 如何报告 MCP Bug？\n\n提交 issue：\n\n请包含：\n\n- MCP Server 版本\n- 客户端名称与版本\n- 操作系统\n- 相关日志\n- 复现步骤\n\n## 下一步\n\n- [MCP 是什么？](/docs/mcp/what-is-mcp)\n- [Claude Desktop 配置](/docs/mcp/claude-desktop)\n- [MCP 故障排查](/docs/mcp/troubleshooting)\n","content_html":"

MCP 常见问题

\n

关于 Synapse MCP Server 的常见问题。

\n

MCP 是什么？

\n

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

\n

参见 MCP 是什么？。

\n

Synapse MCP 暴露多少个工具？

\n

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

\n

完整列表请见 MCP 是什么？。

\n

支持哪些 MCP 客户端？

\n\n

配置示例请见 Claude Desktop 配置。

\n

支持哪些传输方式？

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

如何配置 Claude Desktop？

\n

编辑 claude_desktop_config.json：

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

参见 Claude Desktop 配置。

\n

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

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

参见 MCP 故障排查。

\n

如何切换到另一个 Mind？

\n

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

\n

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

\n

能限制暴露的工具吗？

\n

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

\n\n

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

\n

如何调试 MCP 问题？

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

参见 MCP 故障排查。

\n

MCP Server 是免费的吗？

\n

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

\n

可以自托管 MCP Server 吗？

\n

可以：

\n
npm install -g synapse-mcp-api\nSYNAPSE_URL=https://your-synapse-instance.com \\\nSYNAPSE_MIND_KEY=mk_... \\\nsynapse-mcp-api

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

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

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

\n

可以。使用官方 MCP SDK：

\n\n

参见 自定义 MCP 客户端。

\n

如何报告 MCP Bug？

\n

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

\n

请包含：

\n\n

下一步

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