Rozwiązywanie problemów MCP

Częste problemy i rozwiązania przy integracji Synapse MCP z klientem LLM.

Szybka lista kontrolna diagnostyki

1. ✅ Node.js 18+ zainstalowany? (node --version)
2. ✅ Mind Key zaczyna się od mk_? (nie JWT eyJ...)
3. ✅ API Synapse osiągalne? (curl https://synapse.schaefer.zone/health)
4. ✅ Mind Key działa? (curl -H "Authorization: Bearer mk_..." .../memory/recall)
5. ✅ Plik konfiguracyjny jest poprawnym JSON-em? (bez końcowych przecinków, bez komentarzy)
6. ✅ Klient zrestartowany po zmianie konfiguracji?
7. ✅ Serwer MCP uruchamia się ręcznie? (npx -y synapse-mcp-api@latest)

Problem: brak narzędzi w kliencie

Symptomy

• Claude Desktop / Cursor / Continue pokazuje 0 narzędzi
• Brak ikony 🔌 lub wpisu „synapse" w liście serwerów MCP

Rozwiązania

1. W pełni zrestartować klienta — Cmd+Q na macOS (nie tylko zamknąć okno)
2. Sprawdzić lokalizację pliku konfiguracyjnego:
   • 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. Zwalidować JSON — wkleić konfigurację do https://jsonlint.com
4. Sprawdzić logi klienta pod kątem błędów MCP:
   • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
   • Cursor: View → Output → MCP
5. Uruchomić serwer MCP ręcznie, aby zobaczyć błędy startu:

   SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest

Problem: błąd „Mind Key invalid"

Symptomy

• Narzędzia się wyświetlają, ale wywołania zawodzą z „401 Unauthorized"
• Błąd: „Mind Key fehlt oder ungültig"

Rozwiązania

1. Zweryfikować format Mind Key — zaczyna się od mk_, około 40 znaków
2. Przetestować bezpośrednio:

   curl -H "Authorization: Bearer mk_YOUR_KEY" \
        https://synapse.schaefer.zone/memory/recall

3. Sprawdzić, czy zmienna środowiskowa jest ustawiona — dla transportu stdio zmienna musi być w konfiguracji serwera MCP, a nie w powłoce
4. Uzyskać nowy Mind Key:

   # Logowanie, aby uzyskać JWT
   curl -X POST .../login -d '{"email":"...","password":"..."}'
   # Utworzenie nowego umysłu
   curl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'

Problem: npx nie znalezione

Symptomy

• Błąd: „npx: command not found"
• Serwer MCP nie może się uruchomić

Rozwiązania

1. Zainstalować Node.js 18+:
   • macOS: brew install node lub pobrać z https://nodejs.org
   • Linux: curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs
   • Windows: pobrać z https://nodejs.org
2. Zrestartować terminal po instalacji
3. Zweryfikować: node --version && npx --version

Problem: SYNAPSE_URL nieosiągalne

Symptomy

• Serwer MCP się uruchamia, ale wywołania narzędzi przekraczają czas oczekiwania
• Błąd: „fetch failed" lub „ECONNREFUSED"

Rozwiązania

1. Przetestować łączność:

   curl https://synapse.schaefer.zone/health

2. Sprawdzić firmowy firewall — może blokować wychodzący HTTPS
3. Wypróbować alternatywny URL:
   • Produkcja: https://synapse.schaefer.zone
   • Serwer MCP: https://synapse-mcp.schaefer.zone
4. Dla self-hosted: upewnić się, że instancja Synapse działa i jest dostępna

Problem: serwer MCP się zawiesza

Symptomy

• Serwer MCP wychodzi natychmiast po starcie
• Logi klienta pokazują „MCP server disconnected"

Rozwiązania

1. Uruchomić ręcznie, aby zobaczyć błąd:

   SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \
     npx -y synapse-mcp-api@latest

2. Sprawdzić konflikty portów — serwer MCP używa domyślnie portu 13100
3. Wyczyścić pamięć podręczną npx:

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

4. Zaktualizować do najnowszej wersji:

   npx -y synapse-mcp-api@latest --version

Problem: wywołania narzędzi zwracają 429

Symptomy

• Błąd: „Rate limit exceeded"

Rozwiązania

To nie powinno się zdarzyć z MCP (używa autoryzacji nagłówkiem, bez limitu). Jeśli tak:

1. Sprawdzić, czy gdzieś używane jest ?key= — przełączyć na autoryzację nagłówkiem
2. Zweryfikować SYNAPSE_URL — upewnić się, że wskazuje właściwą instancję
3. Skontaktować się ze wsparciem, jeśli problem utrzymuje się

Problem: narzędzia się wyświetlają, ale nie działają

Symptomy

• Narzędzia wymienione w kliencie
• Wywołanie narzędzia zwraca błąd lub brak wyniku

Rozwiązania

1. Sprawdzić nazwę narzędzia — musi być dokładna (np. memory_recall, nie memory.recall)
2. Zweryfikować argumenty — sprawdzić schemat wejściowy narzędzia
3. Przetestować przez bezpośrednie 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. Sprawdzić kondycję Synapse:

   curl https://synapse.schaefer.zone/health

Uzyskiwanie pomocy

Jeśli żadne z powyższych nie rozwiąże problemu:

1. Sprawdzić istniejące zgłoszenia: https://gitlab.com/schaefer-services/synapse-mcp/-/issues
2. Otworzyć nowe zgłoszenie z:
   • Wersją serwera MCP (npx -y synapse-mcp-api@latest --version)
   • Nazwą i wersją klienta
   • Systemem operacyjnym
   • Istotnymi fragmentami logów
   • Krokami reprodukcji

Następne kroki

• Konfiguracja Claude Desktop
• Konfiguracja Claude Code
• Błędy API