Problemy z połączeniem serwera MCP

Masz problemy z połączeniami serwerów MCP? Ten kompleksowy przewodnik obejmuje typowe problemy, rozwiązania specyficzne dla platform i najlepsze praktyki ustanawiania niezawodnych połączeń MCP.

Zrozumienie architektury połączeń MCP

Przed przejściem do rozwiązywania problemów istotne jest zrozumienie jak działają połączenia MCP:

Przepływ połączenia

Wykrywanie klienta: Cursor/Claude Code odkrywa serwery MCP z konfiguracji
Uruchomienie procesu: Klient uruchamia proces serwera używając określonego polecenia
Negocjacja transportu: Klient i serwer ustanawiają kanał komunikacji
Rejestracja narzędzi: Serwer reklamuje dostępne narzędzia klientowi
Keep-Alive: Połączenie utrzymywane przez okresowe kontrole zdrowia

Typowe problemy z połączeniem

1. “Nie znaleziono narzędzi” lub serwer niewidoczny

To najczęstszy problem przy konfiguracji serwerów MCP.

Cursor
Claude Code

Objawy:

Czerwony wskaźnik obok serwera MCP
Komunikat “Nie znaleziono narzędzi”
Serwer nie pojawia się na liście narzędzi

Rozwiązania:

# 1. Sprawdź czy serwer MCP jest włączony
cursor --version  # Upewnij się że v0.45+ dla obsługi MCP

# 2. Sprawdź składnię konfiguracji
cat ~/.cursor/mcp.json  # lub specyficzny dla projektu .cursor/mcp.json

# 3. Całkowicie zrestartuj Cursor
# Zamknij wszystkie okna włącznie z procesami w tle

Sprawdzenie konfiguracji:

{
  "mcpServers": {
    "your-server": {
      "command": "npx",
      "args": ["-y", "@your-scope/server-name"]
    }
  }
}

Objawy:

Serwer nie pojawia się na liście narzędzi
Brak narzędzi MCP dostępnych w czacie
Komunikaty timeout połączenia

Rozwiązania:

# 1. Wylistuj skonfigurowane serwery
claude mcp list

# 2. Przetestuj serwer ręcznie
claude mcp test your-server-name

# 3. Włącz tryb debug
claude --mcp-debug

Przykład konfiguracji:

# Dodaj serwer z transportem SSE (np. Figma)
claude mcp add --transport sse figma-dev-mode http://127.0.0.1:3845/sse

2. Błędy “Client Closed” lub “spawn ENOENT”

Te błędy wskazują na nieudane uruchomienie procesu serwera.

Wyczyść cache NPX

npx clear-npx-cache
npm cache clean --force

Zweryfikuj zależności

# Sprawdź wersję Node.js (wymaga 18+)
node --version

# Upewnij się że npx jest dostępny
npx --version

Testuj ręczne wykonanie

# Spróbuj uruchomić polecenie serwera bezpośrednio
npx -y @modelcontextprotocol/server-example

Sprawdź konfigurację PATH

Windows
macOS/Linux

# Dodaj Node.js do PATH
$env:Path += ";C:\Program Files\nodejs"

# Dla trwałej poprawki, dodaj przez Właściwości systemu

# Dodaj do profilu shell
export PATH="/usr/local/bin:$PATH"

3. Problemy z uwierzytelnianiem i uprawnieniami

Typowe problemy auth

Nieskonfigurowane klucze API
Błędy przepływu OAuth
Uprawnienia systemu plików
Firewall blokujący localhost

Rozwiązania według typu:

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["-y", "@example/server"],
      "env": {
        "API_KEY": "your-key-here",
        "API_SECRET": "your-secret"
      }
    }
  }
}

Dla serwerów opartych na OAuth (np. zdalne MCP):

# Przepływ OAuth Claude Code
claude mcp add --transport sse remote-server https://api.example.com/mcp

# Podążaj za promptami OAuth w przeglądarce
# Sprawdź blokery popup'ów

Rozwiązywanie problemów:

Upewnij się że redirect URL są na białej liście
Sprawdź konsolę przeglądarki pod kątem błędów
Zweryfikuj konfigurację aplikacji OAuth

# Napraw problemy z uprawnieniami w systemach Unix
chmod +x ~/.npm/_npx/*/node_modules/*/dist/index.js

# Dla globalnych instalacji
sudo npm install -g @modelcontextprotocol/server-name

Problemy specyficzne dla platform

Problemy specyficzne dla Windows

Problemy z wykonaniem PowerShell

Użytkownicy Windows często napotykają problemy specyficzne dla PowerShell z serwerami MCP.

Problem: Puste okna PowerShell lub błędy execution policy

Rozwiązania:

# 1. Ustaw execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 2. Użyj pełnych ścieżek zamiast npx
{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\AppData\\Roaming\\npm\\node_modules\\@scope\\server\\dist\\index.js"]
    }
  }
}

# 3. Wyłącz okno PowerShell (specyficzne dla Cursor)
# Dodaj do konfiguracji serwera:
"windowsHide": true

Problemy specyficzne dla macOS

Blokady Gatekeeper

# Jeśli macOS blokuje wykonanie
xattr -d com.apple.quarantine /path/to/mcp/server

Dostęp do portu

# Sprawdź czy port jest używany
lsof -i :3845  # Dla przykładu Figma MCP

Problemy z Homebrew Node

# Upewnij się o prawidłową wersję Node
brew update
brew upgrade node

Błędy uprawnień Linux

# Typowe poprawki dla Linux
# 1. Unikaj globalnych instalacji npm z sudo
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 2. Napraw uprawnienia npm
sudo chown -R $(whoami) ~/.npm

# 3. Użyj menedżera wersji node
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Problemy sieciowe i firewall

Problemy z połączeniem serwera lokalnego

# Testuj łączność localhost
curl http://127.0.0.1:3845/sse  # Przykład dla Figma

# Alternatywa: użyj 0.0.0.0
{
  "url": "http://0.0.0.0:3845/sse"
}

# Windows Defender
netsh advfirewall firewall add rule name="MCP Server" dir=in action=allow protocol=TCP localport=3845

# macOS
sudo pfctl -f /etc/pf.conf

# Linux (ufw)
sudo ufw allow 3845/tcp

Dla sieci korporacyjnych z proxy:

{
  "mcpServers": {
    "server": {
      "command": "npx",
      "args": ["-y", "@scope/server"],
      "env": {
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080",
        "NO_PROXY": "localhost,127.0.0.1"
      }
    }
  }
}

Problemy kompatybilności HTTP/2

Poprawka dla Cursor:

Otwórz ustawienia (Cmd/Ctrl + ,)
Wyszukaj “HTTP/2”
Włącz “Disable HTTP/2”
Zrestartuj Cursor

Problemy z wydajnością i timeout

Obsługa dużych operacji

{
  "mcpServers": {
    "heavy-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "MCP_TIMEOUT": "30000",  // 30 sekund
        "NODE_OPTIONS": "--max-old-space-size=4096"
      }
    }
  }
}

Zarządzanie pulą połączeń

Dla wielu serwerów MCP:

// Przykład konfiguracji dla scenariuszy wysokiego obciążenia
{
  "mcpServers": {
    "db-server": {
      "command": "npx",
      "args": ["@db/mcp-server"],
      "maxRestarts": 3,
      "restartDelay": 1000,
      "connectionPool": {
        "max": 10,
        "idleTimeout": 60000
      }
    }
  }
}

Zaawansowane rozwiązywanie problemów

# Włącz logi debug MCP
1. Ctrl+Shift+U (Cmd+Shift+U na Mac)
2. Wybierz "MCP Logs" z dropdown
3. Szukaj:
   - Próby połączeń
   - Błędy uwierzytelniania
   - Błędy rejestracji narzędzi

# Uruchom z flagą debug
claude --mcp-debug

# Sprawdź konkretny serwer
claude mcp get server-name -v

# Monitoruj logi w czasie rzeczywistym
claude --debug 2>&1 | grep MCP

Zarządzanie procesami

# Znajdź zablokowane procesy MCP
# Windows
tasklist | findstr "node"
taskkill /F /PID <pid>

# macOS/Linux
ps aux | grep mcp
kill -9 <pid>

# Wyczyść osierocone procesy
pkill -f "mcp-server"

Odzyskiwanie stanu połączenia

// Przykład konfiguracji odzyskiwania
{
  "mcpServers": {
    "resilient-server": {
      "command": "npx",
      "args": ["@scope/server"],
      "reconnect": {
        "enabled": true,
        "maxAttempts": 5,
        "backoffMultiplier": 2,
        "initialDelay": 1000,
        "maxDelay": 30000
      },
      "healthCheck": {
        "enabled": true,
        "interval": 60000,
        "timeout": 5000
      }
    }
  }
}

Najlepsze praktyki dla stabilnych połączeń

Zarządzanie konfiguracją

Używaj kontroli wersji dla konfiguracji MCP
Oddzielne konfiguracje dev/prod
Dokumentuj wymagane zmienne środowiskowe
Testuj konfiguracje przed wdrożeniem

Względy bezpieczeństwa

Nigdy nie wpisuj wrażliwych danych na stałe
Używaj użytkowników bazy danych tylko do odczytu
Implementuj ograniczenia częstości
Waliduj parametry wejściowe

Konfiguracja monitorowania

Włącz logi debug w developmencie
Skonfiguruj kontrole zdrowia
Monitoruj użycie zasobów
Śledź metryki połączeń

Obsługa błędów

Implementuj graceful degradation
Dodaj logikę retry z backoff
Loguj błędy kompleksowo
Dostarczaj przyjazne użytkownikowi komunikaty

Lista kontrolna szybkiego odniesienia

Podczas rozwiązywania problemów z połączeniami MCP, przejdź przez tę listę kontrolną:

Sprawdzenie wersji
- Cursor v0.45+ lub najnowszy Claude Code
- Node.js 18+ zainstalowany
- NPM/NPX działają poprawnie
Walidacja konfiguracji
- Poprawna składnia JSON
- Prawidłowe polecenie i argumenty
- Ustawione wymagane zmienne środowiskowe
Weryfikacja sieci
- Serwer osiągalny na określonym porcie
- Brak blokowania przez firewall
- Ustawienia proxy jeśli mają zastosowanie
Stan procesu
- Brak osieroconych procesów
- Wystarczające zasoby systemowe
- Prawidłowe uprawnienia plików
Informacje debug
- Włącz logi debug
- Sprawdź komunikaty błędów
- Przetestuj ręczne wykonanie

Uzyskiwanie pomocy

Jeśli nadal doświadczasz problemów:

Zbierz informacje debug

# Informacje systemowe
node --version
npm --version
cursor --version  # lub claude --version

# Konfiguracja MCP
cat ~/.cursor/mcp.json  # lub równoważne

# Logi błędów
# Skopiuj z output MCP Logs

Sprawdź zasoby społeczności
Zgłoś problemy
- Dołącz pełne komunikaty błędów
- Określ platformę i wersje
- Podaj minimalne kroki reprodukcji
- Wspomni co już próbowałeś

Pamiętaj, że MCP szybko się rozwija, więc utrzymuj swoje narzędzia w aktualnej wersji i sprawdzaj notatki wydania pod kątem zmian łamiących kompatybilność!