{"title":"MCP Troubleshooting","slug":"troubleshooting","category":"mcp","summary":"Solve common MCP integration issues — server not starting, tools not appearing, auth errors.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":552,"read_minutes":3,"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":"en","translated":true,"requested_lang":"en","content_markdown":"\n# MCP Troubleshooting\n\nCommon issues and solutions when integrating Synapse MCP with your LLM client.\n\n## Quick Diagnostic Checklist\n\n1. ✅ Node.js 18+ installed? (`node --version`)\n2. ✅ Mind Key starts with `mk_`? (not JWT `eyJ...`)\n3. ✅ Synapse API reachable? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key works? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Config file is valid JSON? (no trailing commas, no comments)\n6. ✅ Client restarted after config change?\n7. ✅ MCP server starts manually? (`npx -y synapse-mcp-api@latest`)\n\n## Issue: No Tools Appear in Client\n\n### Symptoms\n\n- Claude Desktop / Cursor / Continue shows 0 tools\n- No 🔌 icon or \"synapse\" entry in MCP servers list\n\n### Solutions\n\n1. **Restart client fully** — Cmd+Q on macOS (not just close window)\n2. **Check config file location**:\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. **Validate JSON** — paste config into \n4. **Check client logs** for MCP errors:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Run MCP server manually** to see startup errors:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Issue: \"Mind Key invalid\" Error\n\n### Symptoms\n\n- Tools appear but calls fail with \"401 Unauthorized\"\n- Error: \"Mind Key fehlt oder ungültig\"\n\n### Solutions\n\n1. **Verify Mind Key format** — starts with `mk_`, ~40 characters\n2. **Test directly**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **Check env var is set** — for stdio transport, the env var must be in the\n MCP server config, not your shell\n4. **Get a fresh Mind Key**:\n ```bash\n # Login to get JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Create new mind\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Issue: npx Not Found\n\n### Symptoms\n\n- Error: \"npx: command not found\"\n- MCP server fails to start\n\n### Solutions\n\n1. **Install Node.js 18+**:\n - macOS: `brew install node` or download from \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: download from \n2. **Restart terminal** after install\n3. **Verify**: `node --version && npx --version`\n\n## Issue: SYNAPSE_URL Unreachable\n\n### Symptoms\n\n- MCP server starts but tool calls time out\n- Error: \"fetch failed\" or \"ECONNREFUSED\"\n\n### Solutions\n\n1. **Test connectivity**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Check corporate firewall** — may block outbound HTTPS\n3. **Try alternative URL**:\n - Production: `https://synapse.schaefer.zone`\n - MCP server: `https://synapse-mcp.schaefer.zone`\n4. **For self-hosted**: ensure your Synapse instance is running and accessible\n\n## Issue: MCP Server Crashes\n\n### Symptoms\n\n- MCP server exits immediately after start\n- Client logs show \"MCP server disconnected\"\n\n### Solutions\n\n1. **Run manually to see error**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Check for port conflicts** — MCP server uses port 13100 by default\n3. **Clear npx cache**:\n ```bash\n npx clear-npx-cache\n # or\n rm -rf ~/.npm/_npx\n ```\n4. **Update to latest**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Issue: Tool Calls Return 429\n\n### Symptoms\n\n- Error: \"Rate limit exceeded\"\n\n### Solutions\n\nThis shouldn't happen with MCP (uses header auth, no rate limit). If it does:\n\n1. **Check if you're using `?key=` somewhere** — switch to header auth\n2. **Verify `SYNAPSE_URL`** — make sure it points to the right instance\n3. **Contact support** if issue persists\n\n## Issue: Tools Appear but Don't Work\n\n### Symptoms\n\n- Tools listed in client\n- Calling a tool returns an error or no result\n\n### Solutions\n\n1. **Check the tool name** — must be exact (e.g. `memory_recall`, not `memory.recall`)\n2. **Verify arguments** — check the tool's input schema\n3. **Test via direct 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. **Check Synapse health**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Getting Help\n\nIf none of the above solves your issue:\n\n1. **Check existing issues**: \n2. **Open a new issue** with:\n - MCP server version (`npx -y synapse-mcp-api@latest --version`)\n - Client name and version\n - Operating system\n - Relevant log excerpts\n - Steps to reproduce\n\n## Next Steps\n\n- [Claude Desktop Setup](/docs/mcp/claude-desktop)\n- [Claude Code Setup](/docs/mcp/claude-code)\n- [API Errors](/docs/api/errors)\n","content_html":"

MCP Troubleshooting

\n

Common issues and solutions when integrating Synapse MCP with your LLM client.

\n

Quick Diagnostic Checklist

\n
    \n
  1. ✅ Node.js 18+ installed? (node --version)
    2. \n
  2. ✅ Mind Key starts with mk_? (not JWT eyJ...)
    3. \n
  3. ✅ Synapse API reachable? (curl https://synapse.schaefer.zone/health)
    4. \n
  4. ✅ Mind Key works? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
    5. \n
  5. ✅ Config file is valid JSON? (no trailing commas, no comments)
    6. \n
  6. ✅ Client restarted after config change?
    7. \n
  7. ✅ MCP server starts manually? (npx -y synapse-mcp-api@latest)
    8. \n
\n

Issue: No Tools Appear in Client

\n

Symptoms

\n
    \n
  • Claude Desktop / Cursor / Continue shows 0 tools
    • \n
  • No 🔌 icon or "synapse" entry in MCP servers list
    • \n
\n

Solutions

\n
    \n
  1. Restart client fully — Cmd+Q on macOS (not just close window)
    2. \n
  2. Check config file location:
      \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. Validate JSON — paste config into https://jsonlint.com
    4. \n
  4. Check client logs for MCP errors:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  5. Run MCP server manually to see startup errors:
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
    6. \n
\n

Issue: "Mind Key invalid" Error

\n

Symptoms

\n
    \n
  • Tools appear but calls fail with "401 Unauthorized"
    • \n
  • Error: "Mind Key fehlt oder ungültig"
    • \n
\n

Solutions

\n
    \n
  1. Verify Mind Key format — starts with mk_, ~40 characters
    2. \n
  2. Test directly:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. Check env var is set — for stdio transport, the env var must be in the\nMCP server config, not your shell
    4. \n
  4. Get a fresh Mind Key:
    # Login to get JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Create new mind\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

Issue: npx Not Found

\n

Symptoms

\n
    \n
  • Error: "npx: command not found"
    • \n
  • MCP server fails to start
    • \n
\n

Solutions

\n
    \n
  1. Install Node.js 18+:
      \n
    • macOS: brew install node or download from https://nodejs.org
      • \n
    • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
      • \n
    • Windows: download from https://nodejs.org
      • \n
    \n
    2. \n
  2. Restart terminal after install
    3. \n
  3. Verify: node --version && npx --version
    4. \n
\n

Issue: SYNAPSE_URL Unreachable

\n

Symptoms

\n
    \n
  • MCP server starts but tool calls time out
    • \n
  • Error: "fetch failed" or "ECONNREFUSED"
    • \n
\n

Solutions

\n
    \n
  1. Test connectivity:
    curl https://synapse.schaefer.zone/health
    2. \n
  2. Check corporate firewall — may block outbound HTTPS
    3. \n
  3. Try alternative URL:
      \n
    • Production: https://synapse.schaefer.zone
      • \n
    • MCP server: https://synapse-mcp.schaefer.zone
      • \n
    \n
    4. \n
  4. For self-hosted: ensure your Synapse instance is running and accessible
    5. \n
\n

Issue: MCP Server Crashes

\n

Symptoms

\n
    \n
  • MCP server exits immediately after start
    • \n
  • Client logs show "MCP server disconnected"
    • \n
\n

Solutions

\n
    \n
  1. Run manually to see error:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Check for port conflicts — MCP server uses port 13100 by default
    3. \n
  3. Clear npx cache:
    npx clear-npx-cache\n# or\nrm -rf ~/.npm/_npx
    4. \n
  4. Update to latest:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Issue: Tool Calls Return 429

\n

Symptoms

\n
    \n
  • Error: "Rate limit exceeded"
    • \n
\n

Solutions

\n

This shouldn't happen with MCP (uses header auth, no rate limit). If it does:

\n
    \n
  1. Check if you're using ?key= somewhere — switch to header auth
    2. \n
  2. Verify SYNAPSE_URL — make sure it points to the right instance
    3. \n
  3. Contact support if issue persists
    4. \n
\n

Issue: Tools Appear but Don't Work

\n

Symptoms

\n
    \n
  • Tools listed in client
    • \n
  • Calling a tool returns an error or no result
    • \n
\n

Solutions

\n
    \n
  1. Check the tool name — must be exact (e.g. memory_recall, not memory.recall)
    2. \n
  2. Verify arguments — check the tool's input schema
    3. \n
  3. Test via direct 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. Check Synapse health:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Getting Help

\n

If none of the above solves your issue:

\n
    \n
  1. Check existing issues: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
    2. \n
  2. Open a new issue with:
      \n
    • MCP server version (npx -y synapse-mcp-api@latest --version)
      • \n
    • Client name and version
      • \n
    • Operating system
      • \n
    • Relevant log excerpts
      • \n
    • Steps to reproduce
      • \n
    \n
    3. \n
\n

Next Steps

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