# MCP-felsökning

Vanliga problem och lösningar vid integration av Synapse MCP med er LLM-klient.

## Snabb checklista för diagnostik

1. ✅ Node.js 18+ installerat? (`node --version`)
2. ✅ Mind Key börjar med `mk_`? (inte JWT `eyJ...`)
3. ✅ Synapse API nåbart? (`curl https://synapse.schaefer.zone/health`)
4. ✅ Mind Key fungerar? (`curl -H "Authorization: Bearer mk_..." .../memory/recall`)
5. ✅ Konfigurationsfil är giltig JSON? (inga avslutande kommatecken, inga kommentarer)
6. ✅ Klient omstartad efter konfigurationsändring?
7. ✅ MCP-server startar manuellt? (`npx -y synapse-mcp-api@latest`)

## Problem: Inga verktyg visas i klienten

### Symptom

- Claude Desktop / Cursor / Continue visar 0 verktyg
- Ingen 🔌-ikon eller "synapse"-post i MCP-serverlista

### Lösningar

1. **Starta om klienten helt** — Cmd+Q på macOS (inte bara stäng fönstret)
2. **Kontrollera sökväg till konfigurationsfil**:
   - 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. **Validera JSON** — klistra in konfiguration i <https://jsonlint.com>
4. **Kontrollera klientloggar** för MCP-fel:
   - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)
   - Cursor: View → Output → MCP
5. **Kör MCP-server manuellt** för att se startfel:
   ```bash
   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
   ```

## Problem: "Mind Key invalid"-fel

### Symptom

- Verktyg visas men anrop misslyckas med "401 Unauthorized"
- Fel: "Mind Key fehlt oder ungültig"

### Lösningar

1. **Verifiera Mind Key-format** — börjar med `mk_`, ~40 tecken
2. **Testa direkt**:
   ```bash
   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall
   ```
3. **Kontrollera att miljövariabel är satt** — för stdio-transport måste
   miljövariabeln vara i MCP-serverkonfigurationen, inte ert shell
4. **Hämta en ny 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"}'
   ```

## Problem: npx hittades inte

### Symptom

- Fel: "npx: command not found"
- MCP-server startar inte

### Lösningar

1. **Installera Node.js 18+**:
   - macOS: `brew install node` eller ladda ner från <https://nodejs.org>
   - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`
   - Windows: ladda ner från <https://nodejs.org>
2. **Starta om terminal** efter installation
3. **Verifiera**: `node --version && npx --version`

## Problem: SYNAPSE_URL onåbar

### Symptom

- MCP-server startar men verktygsanrop time-outar
- Fel: "fetch failed" eller "ECONNREFUSED"

### Lösningar

1. **Testa anslutning**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```
2. **Kontrollera företagsbrandvägg** — kan blockera utgående HTTPS
3. **Prova alternativ URL**:
   - Produktion: `https://synapse.schaefer.zone`
   - MCP-server: `https://synapse-mcp.schaefer.zone`
4. **För egenvärd**: säkerställ att er Synapse-instans körs och är åtkomlig

## Problem: MCP-server kraschar

### Symptom

- MCP-server avslutas omedelbart efter start
- Klientloggar visar "MCP server disconnected"

### Lösningar

1. **Kör manuellt för att se fel**:
   ```bash
   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest
   ```
2. **Kontrollera portkonflikter** — MCP-server använder port 13100 som standard
3. **Rensa npx-cache**:
   ```bash
   npx clear-npx-cache
   # or
   rm -rf ~/.npm/_npx
   ```
4. **Uppdatera till senaste**:
   ```bash
   npx -y synapse-mcp-api@latest --version
   ```

## Problem: Verktygsanrop returnerar 429

### Symptom

- Fel: "Rate limit exceeded"

### Lösningar

Detta bör inte hända med MCP (använder header-auth, ingen hastighetsgräns). Om det gör det:

1. **Kontrollera om ni använder `?key=` nånstans** — byt till header-auth
2. **Verifiera `SYNAPSE_URL`** — säkerställ att den pekar på rätt instans
3. **Kontakta support** om problemet kvarstår

## Problem: Verktyg visas men fungerar inte

### Symptom

- Verktyg listade i klient
- Att anropa ett verktyg returnerar fel eller inget resultat

### Lösningar

1. **Kontrollera verktygsnamnet** — måste vara exakt (t.ex. `memory_recall`, inte `memory.recall`)
2. **Verifiera argument** — kontrollera verktygets indataschema
3. **Testa via direkt 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. **Kontrollera Synapse-hälsa**:
   ```bash
   curl https://synapse.schaefer.zone/health
   ```

## Få hjälp

Om inget av ovanstående löser ert problem:

1. **Kontrollera befintliga ärenden**: <https://gitlab.com/schaefer-services/synapse-mcp/-/issues>
2. **Öppna ett nytt ärende** med:
   - MCP-serverversion (`npx -y synapse-mcp-api@latest --version`)
   - Klientnamn och version
   - Operativsystem
   - Relevanta loggutdrag
   - Steg för att reproducera

## Nästa steg

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