# 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:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   # 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**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Update to latest**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Claude Code Setup](/docs/mcp/claude-code)
- [API Errors](/docs/api/errors)