{"title":"MCP FAQ","slug":"mcp-faq","category":"faq","summary":"Common questions about MCP integration — tools, transports, troubleshooting.","audience":["human","llm"],"tags":["faq","mcp","troubleshooting"],"difficulty":"beginner","updated":"2026-06-27","word_count":448,"read_minutes":2,"lang":"en","translated":true,"requested_lang":"en","content_markdown":"\n# MCP FAQ\n\nCommon questions about the Synapse MCP server.\n\n## What is MCP?\n\nMCP (Model Context Protocol) is an open standard by Anthropic for LLM-tool\nintegration. Instead of pasting API docs into prompts, you register tools\nwith an MCP server, and the LLM calls them as native functions.\n\nSee [What is MCP?](/docs/mcp/what-is-mcp).\n\n## How many tools does Synapse MCP expose?\n\n**79 tools** across 12 categories: memory, chat, scheduler, tasks, scripts,\ncomputers, push, user, utility, visualization, sharing, webhooks, browser.\n\nSee [What is MCP?](/docs/mcp/what-is-mcp) for the full list.\n\n## Which MCP clients are supported?\n\n- Claude Desktop (macOS, Windows)\n- Claude Code (terminal)\n- Cursor (IDE)\n- Continue.dev (VS Code, JetBrains)\n- Cline (VS Code)\n- Any MCP-compatible client\n\nSee [Claude Desktop Setup](/docs/mcp/claude-desktop) for config examples.\n\n## What transports are supported?\n\n1. **stdio** (local, recommended for desktop)\n2. **HTTP/SSE** (remote, multi-tenant)\n3. **WebSocket** (mobile, high-volume)\n\n## How do I configure Claude Desktop?\n\nEdit `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\nSee [Claude Desktop Setup](/docs/mcp/claude-desktop).\n\n## Why don't tools appear in Claude Desktop?\n\n1. **Restart Claude Desktop fully** (Cmd+Q on macOS)\n2. **Check config file is valid JSON**\n3. **Verify Node.js 18+** installed\n4. **Check MCP logs**: `~/Library/Logs/Claude/mcp.log`\n\nSee [MCP Troubleshooting](/docs/mcp/troubleshooting).\n\n## How do I use a different mind?\n\nChange `SYNAPSE_MIND_KEY` in your MCP config and restart the client.\n\nFor multiple minds, run multiple MCP server instances with different\nMind Keys.\n\n## Can I limit which tools are exposed?\n\nYes, use **Tool Profiles**:\n\n- `minimal`: 8 composite tools (~500 tokens)\n- `standard`: 25 tools (~2,500 tokens)\n- `full`: 119 tools (~8,250 tokens, default)\n\nSet via `MCP_PROFILE` env var or `Mcp-Tool-Profile` header.\n\n## How do I debug MCP issues?\n\n1. **Run MCP server manually**: `npx -y synapse-mcp-api@latest`\n2. **Check client logs** (varies by client)\n3. **Verify Mind Key works**: `curl -H \"Authorization: Bearer mk_...\" .../memory/recall`\n4. **Check Synapse health**: `curl https://synapse.schaefer.zone/health`\n\nSee [MCP Troubleshooting](/docs/mcp/troubleshooting).\n\n## Is the MCP server free?\n\nYes. The npm package `synapse-mcp-api` is open source. The hosted MCP server\nat `synapse-mcp.schaefer.zone` is free for public use.\n\n## Can I self-host the MCP server?\n\nYes:\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## How does MCP differ from direct API calls?\n\n| Aspect | Direct API | MCP |\n|--------|-----------|-----|\n| LLM needs to know | URLs, headers, auth | Just tool names |\n| Auth handling | Manual | Automatic (env var) |\n| Tool discovery | Read /endpoints | Automatic via MCP protocol |\n| Error handling | Manual | Standardized |\n| Best for | Custom integrations | LLM agents |\n\n## Can I build my own MCP client?\n\nYes. Use the official MCP SDK:\n\n- TypeScript: `@modelcontextprotocol/sdk`\n- Python: `mcp`\n\nSee [Custom MCP Client](/docs/mcp/custom-client).\n\n## How do I report MCP bugs?\n\nOpen an issue: \n\nInclude:\n\n- MCP server version\n- Client name and version\n- Operating system\n- Relevant logs\n- Steps to reproduce\n\n## Next Steps\n\n- [What is MCP?](/docs/mcp/what-is-mcp)\n- [Claude Desktop Setup](/docs/mcp/claude-desktop)\n- [MCP Troubleshooting](/docs/mcp/troubleshooting)\n","content_html":"

MCP FAQ

\n

Common questions about the Synapse MCP server.

\n

What is MCP?

\n

MCP (Model Context Protocol) is an open standard by Anthropic for LLM-tool\nintegration. Instead of pasting API docs into prompts, you register tools\nwith an MCP server, and the LLM calls them as native functions.

\n

See What is MCP?.

\n

How many tools does Synapse MCP expose?

\n

79 tools across 12 categories: memory, chat, scheduler, tasks, scripts,\ncomputers, push, user, utility, visualization, sharing, webhooks, browser.

\n

See What is MCP? for the full list.

\n

Which MCP clients are supported?

\n\n

See Claude Desktop Setup for config examples.

\n

What transports are supported?

\n
    \n
  1. stdio (local, recommended for desktop)
    2. \n
  2. HTTP/SSE (remote, multi-tenant)
    3. \n
  3. WebSocket (mobile, high-volume)
    4. \n
\n

How do I configure Claude Desktop?

\n

Edit 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}

See Claude Desktop Setup.

\n

Why don't tools appear in Claude Desktop?

\n
    \n
  1. Restart Claude Desktop fully (Cmd+Q on macOS)
    2. \n
  2. Check config file is valid JSON
    3. \n
  3. Verify Node.js 18+ installed
    4. \n
  4. Check MCP logs: ~/Library/Logs/Claude/mcp.log
    5. \n
\n

See MCP Troubleshooting.

\n

How do I use a different mind?

\n

Change SYNAPSE_MIND_KEY in your MCP config and restart the client.

\n

For multiple minds, run multiple MCP server instances with different\nMind Keys.

\n

Can I limit which tools are exposed?

\n

Yes, use Tool Profiles:

\n\n

Set via MCP_PROFILE env var or Mcp-Tool-Profile header.

\n

How do I debug MCP issues?

\n
    \n
  1. Run MCP server manually: npx -y synapse-mcp-api@latest
    2. \n
  2. Check client logs (varies by client)
    3. \n
  3. Verify Mind Key works: curl -H "Authorization: Bearer mk_..." .../memory/recall
    4. \n
  4. Check Synapse health: curl https://synapse.schaefer.zone/health
    5. \n
\n

See MCP Troubleshooting.

\n

Is the MCP server free?

\n

Yes. The npm package synapse-mcp-api is open source. The hosted MCP server\nat synapse-mcp.schaefer.zone is free for public use.

\n

Can I self-host the MCP server?

\n

Yes:

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

How does MCP differ from direct API calls?

\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
AspectDirect APIMCP
LLM needs to knowURLs, headers, authJust tool names
Auth handlingManualAutomatic (env var)
Tool discoveryRead /endpointsAutomatic via MCP protocol
Error handlingManualStandardized
Best forCustom integrationsLLM agents
\n

Can I build my own MCP client?

\n

Yes. Use the official MCP SDK:

\n\n

See Custom MCP Client.

\n

How do I report MCP bugs?

\n

Open an issue: https://gitlab.com/schaefer-services/synapse-mcp/-/issues

\n

Include:

\n\n

Next Steps

\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"]}