# MCP-probleemoplossing

Veelvoorkomende problemen en oplossingen bij het integreren van Synapse MCP met uw LLM-client.

## Snelle diagnosecontrole

1. ✅ Node.js 18+ geïnstalleerd? (`node --version`)
2. ✅ Mind Key begint met `mk_`? (niet JWT `eyJ...`)
3. ✅ Synapse-API bereikbaar? (`curl https://synapse.schaefer.zone/health`)
4. ✅ Mind Key werkt? (`curl -H "Authorization: Bearer mk_..." .../memory/recall`)
5. ✅ Config-bestand is geldige JSON? (geen komma's aan het einde, geen opmerkingen)
6. ✅ Client herstart na config-wijziging?
7. ✅ MCP-server start handmatig? (`npx -y synapse-mcp-api@latest`)

## Probleem: er verschijnen geen tools in de client

### Symptomen

- Claude Desktop / Cursor / Continue toont 0 tools
- Geen 🔌-icoon of "synapse"-vermelding in de lijst met MCP-servers

### Oplossingen

1. **Start de client volledig opnieuw** — Cmd+Q op macOS (niet alleen het venster sluiten)
2. **Controleer de locatie van het config-bestand**:
   - 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. **Valideer de JSON** — plak de configuratie in <https://jsonlint.com>
4. **Controleer de client-logs** op MCP-fouten:
   - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)
   - Cursor: View → Output → MCP
5. **Start de MCP-server handmatig** om opstartfouten te zien:
   ```bash
   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
   ```

## Probleem: foutmelding "Mind Key invalid"

### Symptomen

- Tools verschijnen, maar aanroepen mislukken met "401 Unauthorized"
- Foutmelding: "Mind Key fehlt oder ungültig"

### Oplossingen

1. **Verifieer het formaat van de Mind Key** — begint met `mk_`, ongeveer 40 tekens
2. **Test direct**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **Controleer of de omgevingsvariabele is ingesteld** — voor stdio-transport moet de omgevingsvariabele in de MCP-serverconfiguratie staan, niet in uw shell
4. **Vraag een nieuwe Mind Key aan**:
   ```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"}'
   ```

## Probleem: npx niet gevonden

### Symptomen

- Foutmelding: "npx: command not found"
- MCP-server start niet

### Oplossingen

1. **Installeer Node.js 18+**:
   - macOS: `brew install node` of download via <https://nodejs.org>
   - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
   - Windows: download via <https://nodejs.org>
2. **Herstart de terminal** na installatie
3. **Verifieer**: `node --version && npx --version`

## Probleem: SYNAPSE_URL onbereikbaar

### Symptomen

- MCP-server start, maar tool-aanroepen time-out
- Foutmelding: "fetch failed" of "ECONNREFUSED"

### Oplossingen

1. **Test de verbinding**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```
2. **Controleer de bedrijfsfirewall** — blokkeert mogelijk uitgaand HTTPS-verkeer
3. **Probeer een alternatieve URL**:
   - Productie: `https://synapse.schaefer.zone`
   - MCP-server: `https://synapse-mcp.schaefer.zone`
4. **Voor self-hosted**: zorg dat uw Synapse-instantie draait en bereikbaar is

## Probleem: MCP-server crasht

### Symptomen

- MCP-server sluit direct na het opstarten af
- Client-logs tonen "MCP server disconnected"

### Oplossingen

1. **Voer handmatig uit om de fout te zien**:
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **Controleer op poortconflicten** — de MCP-server gebruikt standaard poort 13100
3. **Wis de npx-cache**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Werk bij naar de laatste versie**:
   ```bash
   npx -y synapse-mcp-api@latest --version
   ```

## Probleem: tool-aanroepen retourneren 429

### Symptomen

- Foutmelding: "Rate limit exceeded"

### Oplossingen

Dit zou niet moeten voorkomen met MCP (gebruikt header-auth, geen rate limit). Mocht het toch voorkomen:

1. **Controleer of u ergens `?key=` gebruikt** — schakel over op header-auth
2. **Verifieer `SYNAPSE_URL`** — zorg dat deze naar de juiste instantie wijst
3. **Neem contact op met support** als het probleem aanhoudt

## Probleem: tools verschijnen, maar werken niet

### Symptomen

- Tools worden in de client getoond
- Een tool aanroepen levert een foutmelding of geen resultaat op

### Oplossingen

1. **Controleer de toolnaam** — moet exact kloppen (bijv. `memory_recall`, niet `memory.recall`)
2. **Verifieer de argumenten** — controleer het inputschema van de tool
3. **Test via de directe 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. **Controleer de gezondheid van Synapse**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```

## Hulp krijgen

Als geen van de bovenstaande oplossingen uw probleem verhelpt:

1. **Controleer bestaande issues**: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. **Open een nieuw issue** met:
   - MCP-serverversie (`npx -y synapse-mcp-api@latest --version`)
   - Naam en versie van de client
   - Besturingssysteem
   - Relevante logfragmenten
   - Stappen om te reproduceren

## Volgende stappen

- [Claude Desktop-instellatie](/docs/mcp/claude-desktop)
- [Claude Code-instellatie](/docs/mcp/claude-code)
- [API-fouten](/docs/api/errors)