Serwer MCP nie łączy się z Claude Code - najczęstsze przyczyny

Claude Code

Serwer MCP nie łączy się z Claude Code - najczęstsze przyczyny

W skrócie

MCP (Model Context Protocol) to sposób, w jaki Claude Code, narzędzie CLI od Anthropic, podłącza się do zewnętrznych systemów - baz danych, API, narzędzi firmowych. Gdy serwer MCP działa, agent zyskuje nowe narzędzia. Gdy nie chce się połączyć, dostajesz status "failed" i żadnych dodatkowych możliwości. To częsty problem przy pierwszej konfiguracji, bo serwer MCP to osobny proces, który Claude Code uruchamia u siebie - i jeśli cokolwiek w komendzie, ścieżce czy zmiennych środowiskowych jest nie tak, połączenie się nie nawiąże. Poniżej przechodzimy przez najczęstsze przyczyny.

Jak to wygląda w praktyce

Po dodaniu serwera i uruchomieniu /mcp w sesji widzisz listę serwerów ze statusem. Zamiast "connected" pojawia się błąd:

MCP Servers

  postgres    failed    Connection closed
  github      connected

Serwer ze statusem "failed" oznacza, że proces się nie uruchomił albo padł zaraz po starcie. Częsty jest też komunikat "Connection closed" - proces wystartował, ale natychmiast się zakończył, zwykle z powodu błędnej konfiguracji lub brakującego klucza API. Narzędzia z takiego serwera nie są dostępne dla agenta.

Dlaczego Claude Code tak działa

Najpopularniejszy typ serwera MCP to serwer stdio - Claude Code sam uruchamia go jako podproces (np. przez npx albo uvx) i komunikuje się z nim przez standardowe wejście i wyjście. Jeśli komenda uruchamiająca jest błędna, pakietu nie da się pobrać, brakuje wymaganej zmiennej środowiskowej (klucz API, connection string) albo interpreter nie jest w PATH - proces pada, a Claude Code raportuje "failed". Bywa też problem z zasięgiem: serwer dodany w jednym zasięgu (np. lokalnym) nie jest widoczny w innym kontekście. Drugi typ to serwery zdalne (SSE/HTTP) - tam przyczyną bywają problemy z adresem, tokenem uwierzytelniającym albo siecią.

Jak to rozwiązać krok po kroku

1. Sprawdź dokładny status komendą /mcp w sesji - pokaże, który serwer padł i czasem powód. To pierwszy przystanek w diagnostyce.
2. Uruchom komendę serwera ręcznie w zwykłym terminalu, dokładnie tak jak w konfiguracji, np. npx -y @modelcontextprotocol/server-postgres postg://.... Jeśli padnie tutaj, zobaczysz prawdziwy błąd - to najszybsza droga do przyczyny.
3. Zweryfikuj, że interpreter jest dostępny: dla serwerów Node potrzebujesz npx (czyli Node), dla serwerów Python zwykle uvx lub uv. Sprawdź npx --version albo uvx --version.
4. Uzupełnij zmienne środowiskowe. Wiele serwerów wymaga kluczy API lub connection stringów - w konfiguracji podaje się je w sekcji env. Brak takiej zmiennej to najczęstsza przyczyna "Connection closed".
5. Obejrzyj wpis konfiguracji: claude mcp get <nazwa> pokaże, jak serwer jest zdefiniowany. Sprawdź literówki w komendzie i argumentach.
6. Jeśli wpis jest błędny, usuń serwer (claude mcp remove <nazwa>) i dodaj go od nowa poprawną komendą claude mcp add, pilnując zasięgu (flaga -s: local, project albo user).
7. Podnieś poziom logowania, uruchamiając Claude Code z flagą --mcp-debug - zobaczysz szczegółowe logi startu serwera i dokładny moment, w którym coś idzie nie tak.

Jak sprawdzić, że zadziałało

Uruchom /mcp - serwer powinien mieć status "connected". Rozwiń go, żeby zobaczyć listę udostępnianych narzędzi. Następnie poproś agenta o zadanie, które wymaga tego serwera (np. dla serwera bazy: "wypisz tabele w bazie") - jeśli agent skorzysta z narzędzia MCP i zwróci wynik, połączenie działa w pełni. Warto też zamknąć i otworzyć sesję na nowo, aby potwierdzić, że serwer łączy się stabilnie przy każdym starcie, a nie tylko raz.

Wróć do listy: 100 najczęstszych problemów z Claude Code

Szkolenie Claude Code - od zera do zespołu agentów AI -->

Szkolenie Claude Code - od zera do zespołu agentów AI

Tryb planowania, tryby uprawnień, komendy, MCP, hooki i systemy multi-agent - wszystko na żywym kodzie podczas trzydniowego szkolenia. Prowadzi Łukasz Matuszewski. Szkolenie ma terminy gwarantowane - odbędzie się niezależnie od liczby zgłoszeń.

Sprawdź szkolenie Claude Code

To szkolenie może być dofinansowane dla Ciebie z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5