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:

   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:

   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:

   # 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:

   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:

   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:

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

4. Uppdatera till senaste:

   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:

   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:

   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
• Claude Code-konfiguration
• API-fel