# 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:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   # 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ść**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   npx clear-npx-cache
   # lub
   rm -rf ~/.npm/_npx
   ```
4. **Zaktualizować do najnowszej wersji**:
   ```bash
   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**:
   ```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. **Sprawdzić kondycję Synapse**:
   ```bash
   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](/docs/mcp/claude-desktop)
- [Konfiguracja Claude Code](/docs/mcp/claude-code)
- [Błędy API](/docs/api/errors)