Problemy z połączeniem serwera MCP

Napotykasz problemy z połączeniem z serwerami MCP? Ten kompleksowy przewodnik obejmuje powszechne problemy, rozwiązania specyficzne dla platformy i najlepsze praktyki ustanawiania niezawodnych połączeń MCP.

Zrozumienie architektury połączeń MCP

Zanim zagłębisz się w rozwiązywanie problemów, konieczne jest zrozumienie, jak działają połączenia MCP:

Flow połączenia

Client Discovery: Cursor/Claude Code odkrywa serwery MCP z konfiguracji
Process Launch: Klient uruchamia proces serwera używając określonej komendy
Transport Negotiation: Klient i serwer ustanawiają kanał komunikacji
Tool Registration: Serwer reklamuje dostępne narzędzia klientowi
Keep-Alive: Połączenie utrzymywane przez okresowe sprawdzenia zdrowia

Powszechne problemy z połączeniem

1. “No Tools Found” lub serwer nie jest widoczny

To najczęstszy problem podczas setupu serwerów MCP.

Cursor
Claude Code

Symptomy:

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

Rozwiązania:

# 1. Zweryfikuj, że serwer MCP jest włączony
cursor --version  # Upewnij się, że v0.45+ dla wsparcia MCP

# 2. Sprawdź składnię konfiguracji
cat ~/.cursor/mcp.json  # lub project-specific .cursor/mcp.json

# 3. Zrestartuj Cursor całkowicie
# Zamknij wszystkie okna łącznie z procesami w tle

Configuration Check:

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

Symptomy:

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

Rozwiązania:

# 1. Wylistuj skonfigurowane serwery
claude mcp list

# 2. Sprawdź szczegóły konkretnego serwera
claude mcp get your-server-name

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

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ą, że proces serwera nie uruchomił się.

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

Przetestuj manualne wykonanie

# Spróbuj uruchomić komendę serwera bezpośrednio
npx -y @modelcontextprotocol/server-github

Sprawdź konfigurację PATH

Windows
macOS/Linux

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

# Dla stałej zmiany, dodaj przez System Properties

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

3. Problemy z uwierzytelnianiem i uprawnieniami

Powszechne problemy z uwierzytelnianiem

Klucze API nie skonfigurowane
Niepowodzenia flow 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):

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

# Śledź prompty OAuth w przeglądarce
# Sprawdź blokery popup

Rozwiązywanie problemów:

Upewnij się, że redirect URLs 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-github

Problemy specyficzne dla platformy

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 polityki wykonywania

Rozwiązania:

# 1. Ustaw politykę wykonywania
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 2. Używaj 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 Node z Homebrew

# Upewnij się o poprawną wersję Node
brew update
brew upgrade node

Błędy uprawnień Linux

# Powszechne 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 node version manager
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Problemy sieciowe i z firewallem

Problemy z połączeniem lokalnego serwera

# Przetestuj łą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 z kompatybilnością HTTP/2

Poprawka dla Cursor:

Otwórz Settings (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ładowa konfiguracja dla scenariuszy wysokiego obciążenia
{
  "mcpServers": {
    "db-server": {
      "command": "npx",
      "args": ["-y", "mongodb-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 dropdownu
3. Szukaj:
   - Próby połączenia
   - Niepowodzenia uwierzytelniania
   - Błędy rejestracji narzędzi

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

# Sprawdź konkretny serwer
claude mcp get server-name

# Monitoruj logi w czasie rzeczywistym
claude --debug "mcp" 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ładowa konfiguracja 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
Oddziel konfiguracje dev/prod
Dokumentuj wymagane zmienne środowiskowe
Testuj konfiguracje przed wdrożeniem

Zagadnienia bezpieczeństwa

Nigdy nie hardcoduj wrażliwych poświadczeń
Używaj użytkowników bazy danych tylko do odczytu
Implementuj rate limiting
Waliduj parametry wejściowe

Setup monitorowania

Włącz logi debug w rozwoju
Skonfiguruj sprawdzenia 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
Zapewnij przyjazne komunikaty dla użytkownika

Szybka lista kontrolna referencyjna

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ące poprawnie
Walidacja konfiguracji
- Poprawna składnia JSON
- Poprawne command i args
- Ustawione wymagane zmienne środowiskowe
Weryfikacja sieci
- Serwer osiągalny na określonym porcie
- Brak blokowania przez firewall
- Ustawienia proxy jeśli dotyczy
Zdrowie procesu
- Brak osieroconych procesów
- Wystarczające zasoby systemowe
- Poprawne uprawnienia do plików
Informacje debug
- Włącz logi debug
- Sprawdź komunikaty błędów
- Przetestuj manualne 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 wyjścia 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
- Wspomnij, co już próbowałeś

Pamiętaj, że MCP szybko ewoluuje, więc utrzymuj narzędzia zaktualizowane i sprawdzaj release notes pod kątem breaking changes!