# MCP Troubleshooting
SUMMARY: Solve common MCP integration issues — server not starting, tools not appearing, auth errors.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

MCP Troubleshooting
Common issues and solutions when integrating Synapse MCP with your LLM client.
Quick Diagnostic Checklist
1. ✅ Node.js 18+ installed? ()
2. ✅ Mind Key starts with ? (not JWT )
3. ✅ Synapse API reachable? ()
4. ✅ Mind Key works? ()
5. ✅ Config file is valid JSON? (no trailing commas, no comments)
6. ✅ Client restarted after config change?
7. ✅ MCP server starts manually? ()
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: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. Validate JSON — paste config into <https://jsonlint.com>
4. Check client logs for MCP errors:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. Run MCP server manually to see startup errors:
   [CODE BLOCK]
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 , 40 characters
2. Test directly:
   [CODE BLOCK]
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:
   [CODE BLOCK]
Issue: npx Not Found
Symptoms
- Error: "npx: command not found"
- MCP server fails to start
Solutions
1. Install Node.js 18+:
   - macOS:  or download from <https://nodejs.org>
   - Linux: 
   - Windows: download from <https://nodejs.org>
2. Restart terminal after install
3. Verify: 
Issue: SYNAPSEURL Unreachable
Symptoms
- MCP server starts but tool calls time out
- Error: "fetch failed" or "ECONNREFUSED"
Solutions
1. Test connectivity:
   [CODE BLOCK]
2. Check corporate firewall — may block outbound HTTPS
3. Try alternative URL:
   - Production: 
   - MCP server: 
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:
   [CODE BLOCK]
2. Check for port conflicts — MCP server uses port 13100 by default
3. Clear npx cache:
   [CODE BLOCK]
4. Update to latest:
   [CODE BLOCK]
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  somewhere — switch to header auth
2. Verify  — 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. , not )
2. Verify arguments — check the tool's input schema
3. Test via direct API:
   [CODE BLOCK]
4. Check Synapse health:
   [CODE BLOCK]
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 ()
   - Client name and version
   - Operating system
   - Relevant log excerpts
   - Steps to reproduce
Next Steps
- Claude Desktop Setup
- Claude Code Setup
- API Errors