{"title":"Rozwiązywanie problemów MCP","slug":"troubleshooting","category":"mcp","summary":"Rozwiązania częstych problemów integracji MCP — serwer się nie uruchamia, narzędzia się nie pojawiają, błędy autoryzacji.","audience":["human","llm"],"tags":["mcp","troubleshooting","errors","debugging"],"difficulty":"intermediate","updated":"2026-06-27","word_count":557,"read_minutes":3,"llm_context":"Common issues:\n1. Node.js < 18 → upgrade to 18+\n2. Mind Key invalid → check format (mk_...), get fresh via POST /minds\n3. npx not found → install Node.js\n4. Tools not appearing → restart client, check config JSON validity\n5. SYNAPSE_URL unreachable → curl /health to verify\n6. MCP server crashes → check logs, run npx manually to see error\nDebug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr\nLogs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/\n","lang":"pl","translated":true,"requested_lang":"pl","content_markdown":"\n# Rozwiązywanie problemów MCP\n\nCzęste problemy i rozwiązania przy integracji Synapse MCP z klientem LLM.\n\n## Szybka lista kontrolna diagnostyki\n\n1. ✅ Node.js 18+ zainstalowany? (`node --version`)\n2. ✅ Mind Key zaczyna się od `mk_`? (nie JWT `eyJ...`)\n3. ✅ API Synapse osiągalne? (`curl https://synapse.schaefer.zone/health`)\n4. ✅ Mind Key działa? (`curl -H \"Authorization: Bearer mk_...\" .../memory/recall`)\n5. ✅ Plik konfiguracyjny jest poprawnym JSON-em? (bez końcowych przecinków, bez komentarzy)\n6. ✅ Klient zrestartowany po zmianie konfiguracji?\n7. ✅ Serwer MCP uruchamia się ręcznie? (`npx -y synapse-mcp-api@latest`)\n\n## Problem: brak narzędzi w kliencie\n\n### Symptomy\n\n- Claude Desktop / Cursor / Continue pokazuje 0 narzędzi\n- Brak ikony 🔌 lub wpisu „synapse\" w liście serwerów MCP\n\n### Rozwiązania\n\n1. **W pełni zrestartować klienta** — Cmd+Q na macOS (nie tylko zamknąć okno)\n2. **Sprawdzić lokalizację pliku konfiguracyjnego**:\n - Claude Desktop macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - Claude Desktop Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - Cursor: `~/.cursor/config.json`\n - Continue: `~/.continue/config.json`\n3. **Zwalidować JSON** — wkleić konfigurację do \n4. **Sprawdzić logi klienta** pod kątem błędów MCP:\n - Claude Desktop: `~/Library/Logs/Claude/mcp.log` (macOS)\n - Cursor: View → Output → MCP\n5. **Uruchomić serwer MCP ręcznie**, aby zobaczyć błędy startu:\n ```bash\n SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest\n ```\n\n## Problem: błąd „Mind Key invalid\"\n\n### Symptomy\n\n- Narzędzia się wyświetlają, ale wywołania zawodzą z „401 Unauthorized\"\n- Błąd: „Mind Key fehlt oder ungültig\"\n\n### Rozwiązania\n\n1. **Zweryfikować format Mind Key** — zaczyna się od `mk_`, około 40 znaków\n2. **Przetestować bezpośrednio**:\n ```bash\n curl -H \"Authorization: Bearer mk_YOUR_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n ```\n3. **Sprawdzić, czy zmienna środowiskowa jest ustawiona** — dla transportu stdio\n zmienna musi być w konfiguracji serwera MCP, a nie w powłoce\n4. **Uzyskać nowy Mind Key**:\n ```bash\n # Logowanie, aby uzyskać JWT\n curl -X POST .../login -d '{\"email\":\"...\",\"password\":\"...\"}'\n # Utworzenie nowego umysłu\n curl -X POST .../minds -H \"Authorization: Bearer YOUR_JWT\" -d '{\"name\":\"new mind\"}'\n ```\n\n## Problem: npx nie znalezione\n\n### Symptomy\n\n- Błąd: „npx: command not found\"\n- Serwer MCP nie może się uruchomić\n\n### Rozwiązania\n\n1. **Zainstalować Node.js 18+**:\n - macOS: `brew install node` lub pobrać z \n - Linux: `curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs`\n - Windows: pobrać z \n2. **Zrestartować terminal** po instalacji\n3. **Zweryfikować**: `node --version && npx --version`\n\n## Problem: SYNAPSE_URL nieosiągalne\n\n### Symptomy\n\n- Serwer MCP się uruchamia, ale wywołania narzędzi przekraczają czas oczekiwania\n- Błąd: „fetch failed\" lub „ECONNREFUSED\"\n\n### Rozwiązania\n\n1. **Przetestować łączność**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n2. **Sprawdzić firmowy firewall** — może blokować wychodzący HTTPS\n3. **Wypróbować alternatywny URL**:\n - Produkcja: `https://synapse.schaefer.zone`\n - Serwer MCP: `https://synapse-mcp.schaefer.zone`\n4. **Dla self-hosted**: upewnić się, że instancja Synapse działa i jest dostępna\n\n## Problem: serwer MCP się zawiesza\n\n### Symptomy\n\n- Serwer MCP wychodzi natychmiast po starcie\n- Logi klienta pokazują „MCP server disconnected\"\n\n### Rozwiązania\n\n1. **Uruchomić ręcznie, aby zobaczyć błąd**:\n ```bash\n SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n npx -y synapse-mcp-api@latest\n ```\n2. **Sprawdzić konflikty portów** — serwer MCP używa domyślnie portu 13100\n3. **Wyczyścić pamięć podręczną npx**:\n ```bash\n npx clear-npx-cache\n # lub\n rm -rf ~/.npm/_npx\n ```\n4. **Zaktualizować do najnowszej wersji**:\n ```bash\n npx -y synapse-mcp-api@latest --version\n ```\n\n## Problem: wywołania narzędzi zwracają 429\n\n### Symptomy\n\n- Błąd: „Rate limit exceeded\"\n\n### Rozwiązania\n\nTo nie powinno się zdarzyć z MCP (używa autoryzacji nagłówkiem, bez limitu). Jeśli\ntak:\n\n1. **Sprawdzić, czy gdzieś używane jest `?key=`** — przełączyć na autoryzację nagłówkiem\n2. **Zweryfikować `SYNAPSE_URL`** — upewnić się, że wskazuje właściwą instancję\n3. **Skontaktować się ze wsparciem**, jeśli problem utrzymuje się\n\n## Problem: narzędzia się wyświetlają, ale nie działają\n\n### Symptomy\n\n- Narzędzia wymienione w kliencie\n- Wywołanie narzędzia zwraca błąd lub brak wyniku\n\n### Rozwiązania\n\n1. **Sprawdzić nazwę narzędzia** — musi być dokładna (np. `memory_recall`, nie `memory.recall`)\n2. **Zweryfikować argumenty** — sprawdzić schemat wejściowy narzędzia\n3. **Przetestować przez bezpośrednie API**:\n ```bash\n curl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer mk_...\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"category\":\"fact\",\"key\":\"test\",\"content\":\"hello\"}'\n ```\n4. **Sprawdzić kondycję Synapse**:\n ```bash\n curl https://synapse.schaefer.zone/health\n ```\n\n## Uzyskiwanie pomocy\n\nJeśli żadne z powyższych nie rozwiąże problemu:\n\n1. **Sprawdzić istniejące zgłoszenia**: \n2. **Otworzyć nowe zgłoszenie** z:\n - Wersją serwera MCP (`npx -y synapse-mcp-api@latest --version`)\n - Nazwą i wersją klienta\n - Systemem operacyjnym\n - Istotnymi fragmentami logów\n - Krokami reprodukcji\n\n## Następne kroki\n\n- [Konfiguracja Claude Desktop](/docs/mcp/claude-desktop)\n- [Konfiguracja Claude Code](/docs/mcp/claude-code)\n- [Błędy API](/docs/api/errors)\n","content_html":"

Rozwiązywanie problemów MCP

\n

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

\n

Szybka lista kontrolna diagnostyki

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

Problem: brak narzędzi w kliencie

\n

Symptomy

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

Rozwiązania

\n
    \n
  1. W pełni zrestartować klienta — Cmd+Q na macOS (nie tylko zamknąć okno)
    2. \n
  2. Sprawdzić lokalizację pliku konfiguracyjnego:
      \n
    • Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
      • \n
    • Claude Desktop Windows: %APPDATA%\\Claude\\claude_desktop_config.json
      • \n
    • Cursor: ~/.cursor/config.json
      • \n
    • Continue: ~/.continue/config.json
      • \n
    \n
    3. \n
  3. Zwalidować JSON — wkleić konfigurację do https://jsonlint.com
    4. \n
  4. Sprawdzić logi klienta pod kątem błędów MCP:
      \n
    • Claude Desktop: ~/Library/Logs/Claude/mcp.log (macOS)
      • \n
    • Cursor: View → Output → MCP
      • \n
    \n
    5. \n
  5. Uruchomić serwer MCP ręcznie, aby zobaczyć błędy startu:
    SYNAPSE_MIND_KEY=mk_... npx -y synapse-mcp-api@latest
    6. \n
\n

Problem: błąd „Mind Key invalid"

\n

Symptomy

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

Rozwiązania

\n
    \n
  1. Zweryfikować format Mind Key — zaczyna się od mk_, około 40 znaków
    2. \n
  2. Przetestować bezpośrednio:
    curl -H "Authorization: Bearer mk_YOUR_KEY" \\\n     https://synapse.schaefer.zone/memory/recall
    3. \n
  3. Sprawdzić, czy zmienna środowiskowa jest ustawiona — dla transportu stdio\nzmienna musi być w konfiguracji serwera MCP, a nie w powłoce
    4. \n
  4. Uzyskać nowy Mind Key:
    # Logowanie, aby uzyskać JWT\ncurl -X POST .../login -d '{"email":"...","password":"..."}'\n# Utworzenie nowego umysłu\ncurl -X POST .../minds -H "Authorization: Bearer YOUR_JWT" -d '{"name":"new mind"}'
    5. \n
\n

Problem: npx nie znalezione

\n

Symptomy

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

Rozwiązania

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

Problem: SYNAPSE_URL nieosiągalne

\n

Symptomy

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

Rozwiązania

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

Problem: serwer MCP się zawiesza

\n

Symptomy

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

Rozwiązania

\n
    \n
  1. Uruchomić ręcznie, aby zobaczyć błąd:
    SYNAPSE_MIND_KEY=mk_... SYNAPSE_URL=https://synapse.schaefer.zone \\\n  npx -y synapse-mcp-api@latest
    2. \n
  2. Sprawdzić konflikty portów — serwer MCP używa domyślnie portu 13100
    3. \n
  3. Wyczyścić pamięć podręczną npx:
    npx clear-npx-cache\n# lub\nrm -rf ~/.npm/_npx
    4. \n
  4. Zaktualizować do najnowszej wersji:
    npx -y synapse-mcp-api@latest --version
    5. \n
\n

Problem: wywołania narzędzi zwracają 429

\n

Symptomy

\n
    \n
  • Błąd: „Rate limit exceeded"
    • \n
\n

Rozwiązania

\n

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

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

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

\n

Symptomy

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

Rozwiązania

\n
    \n
  1. Sprawdzić nazwę narzędzia — musi być dokładna (np. memory_recall, nie memory.recall)
    2. \n
  2. Zweryfikować argumenty — sprawdzić schemat wejściowy narzędzia
    3. \n
  3. Przetestować przez bezpośrednie API:
    curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer mk_..." \\\n  -H "Content-Type: application/json" \\\n  -d '{"category":"fact","key":"test","content":"hello"}'
    4. \n
  4. Sprawdzić kondycję Synapse:
    curl https://synapse.schaefer.zone/health
    5. \n
\n

Uzyskiwanie pomocy

\n

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

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

Następne kroki

\n\n","urls":{"html":"/docs/mcp/troubleshooting","text":"/docs/mcp/troubleshooting?format=text","json":"/docs/mcp/troubleshooting?format=json","llm":"/docs/mcp/troubleshooting?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}