# Rozwiązywanie problemów MCP
SUMMARY: Rozwiązania częstych problemów integracji MCP — serwer się nie uruchamia, narzędzia się nie pojawiają, błędy autoryzacji.

KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/

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? ()
2. ✅ Mind Key zaczyna się od ? (nie JWT )
3. ✅ API Synapse osiągalne? ()
4. ✅ Mind Key działa? ()
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? ()
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: 
   - Claude Desktop Windows: 
   - Cursor: 
   - Continue: 
3. Zwalidować JSON — wkleić konfigurację do <https://jsonlint.com>
4. Sprawdzić logi klienta pod kątem błędów MCP:
   - Claude Desktop:  (macOS)
   - Cursor: View → Output → MCP
5. Uruchomić serwer MCP ręcznie, aby zobaczyć błędy startu:
   [CODE BLOCK]
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 , około 40 znaków
2. Przetestować bezpośrednio:
   [CODE BLOCK]
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:
   [CODE BLOCK]
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:  lub pobrać z <https://nodejs.org>
   - Linux: 
   - Windows: pobrać z <https://nodejs.org>
2. Zrestartować terminal po instalacji
3. Zweryfikować: 
Problem: SYNAPSEURL 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ść:
   [CODE BLOCK]
2. Sprawdzić firmowy firewall — może blokować wychodzący HTTPS
3. Wypróbować alternatywny URL:
   - Produkcja: 
   - Serwer MCP: 
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:
   [CODE BLOCK]
2. Sprawdzić konflikty portów — serwer MCP używa domyślnie portu 13100
3. Wyczyścić pamięć podręczną npx:
   [CODE BLOCK]
4. Zaktualizować do najnowszej wersji:
   [CODE BLOCK]
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  — przełączyć na autoryzację nagłówkiem
2. Zweryfikować  — 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. , nie )
2. Zweryfikować argumenty — sprawdzić schemat wejściowy narzędzia
3. Przetestować przez bezpośrednie API:
   [CODE BLOCK]
4. Sprawdzić kondycję Synapse:
   [CODE BLOCK]
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 ()
   - Nazwą i wersją klienta
   - Systemem operacyjnym
   - Istotnymi fragmentami logów
   - Krokami reprodukcji
Następne kroki
- Konfiguracja Claude Desktop
- Konfiguracja Claude Code
- Błędy API