MCP Troubleshooting

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

Quick Diagnostic Checklist

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

Issue: No Tools Appear in Client

Symptoms

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

Solutions

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

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

Issue: "Mind Key invalid" Error

Symptoms

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

Solutions

1. Verify Mind Key format — starts with mk_, ~40 characters
2. Test directly:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

3. Check env var is set — for stdio transport, the env var must be in the MCP server config, not your shell
4. Get a fresh Mind Key:

   # Login to get JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Create new mind
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

Issue: npx Not Found

Symptoms

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

Solutions

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

Issue: SYNAPSE_URL Unreachable

Symptoms

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

Solutions

1. Test connectivity:

   curl https://synapse.schaefer.zone/health

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

Issue: MCP Server Crashes

Symptoms

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

Solutions

1. Run manually to see error:

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. Check for port conflicts — MCP server uses port 13100 by default
3. Clear npx cache:

   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx

4. Update to latest:

   npx -y synapse-mcp-api@latest --version

Issue: Tool Calls Return 429

Symptoms

• Error: "Rate limit exceeded"

Solutions

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

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

Issue: Tools Appear but Don't Work

Symptoms

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

Solutions

1. Check the tool name — must be exact (e.g. memory_recall, not memory.recall)
2. Verify arguments — check the tool's input schema
3. Test via direct API:

   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. Check Synapse health:

   curl https://synapse.schaefer.zone/health

Getting Help

If none of the above solves your issue:

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

Next Steps

• Claude Desktop Setup
• Claude Code Setup
• API Errors