Serwer MCP timeout albo się wywala - jak zdiagnozować

Claude Code

Serwer MCP timeout albo się wywala - jak zdiagnozować

W skrócie

Podpiąłeś serwer MCP, żeby Claude Code sięgał do Twojej bazy, repozytorium albo firmowego API, a zamiast nowych narzędzi widzisz komunikat o przekroczonym czasie albo cichy brak połączenia. To jeden z najczęstszych kłopotów przy MCP i prawie zawsze da się go zdiagnozować w kilka minut, jeśli wiesz, gdzie patrzeć. Pokazujemy, jak to zrobić po kolei.

Jak to wygląda w praktyce

Objaw jest zwykle jeden z dwóch. Pierwszy: uruchamiasz sesję, a serwer po prostu nie startuje - jego narzędzia się nie pojawiają albo na liście widnieje status oczekujący, który nigdy nie przechodzi w gotowy. Drugi: serwer łączy się na moment, po czym pada, a przy próbie użycia narzędzia dostajesz błąd połączenia.

Często wygląda to tak, jakby konfiguracja była poprawna - plik .mcp.json istnieje, komenda niby dobra - a mimo to Claude Code nie ma dostępu do niczego, co ten serwer miał dostarczyć. Bywa też, że wszystko działa u kolegi z zespołu, a u Ciebie nie, bo brakuje jednego narzędzia w PATH albo zmiennej środowiskowej z kluczem API.

Dlaczego Claude Code tak działa

Claude Code łączy się z serwerami MCP w ściśle określonym oknie czasowym. Pojedyncza próba połączenia z danym serwerem jest ograniczona zmienną MCP_TIMEOUT (domyślnie 30 sekund) - jeśli serwer nie zdąży odpowiedzieć, próba kończy się błędem. Osobno działa krótsze okno startowe: gdy startowe łączenie jest blokujące, Claude Code czeka na całą parę serwerów tylko przez czas z MCP_CONNECT_TIMEOUT_MS (domyślnie 5 sekund), a serwery, które się nie wyrobią, dociągają połączenie w tle.

Do tego dochodzi najczęstsza przyczyna praktyczna: komenda startowa serwera jest błędna albo powolna. Serwer napisany w Node lub Pythonie może długo instalować zależności przy pierwszym starcie, może brakować programu w PATH, może nie być ustawionej zmiennej z tokenem. Wtedy proces albo nie wstaje, albo wstaje i natychmiast kończy się błędem - a z zewnątrz wygląda to jak timeout.

Jak to rozwiązać krok po kroku

1. Uruchom Claude Code w trybie diagnostycznym: claude --debug. W logach startu zobaczysz, jak każdy serwer MCP jest inicjowany, i konkretny powód niepowodzenia (brak komendy, błąd zależności, przekroczony czas).
2. Sprawdź status wszystkich serwerów komendą claude mcp list, a szczegóły pojedynczego przez claude mcp get <nazwa>. Serwery z .mcp.json, które nie zostały jeszcze zatwierdzone, pokazują się jako oczekujące i nie są odpytywane - najpierw je zatwierdź.
3. Odpal komendę startową serwera ręcznie w tym samym terminalu, poza Claude Code (np. npx nazwa-serwera). Jeśli tu też nie wstaje, problem jest po stronie serwera lub środowiska, a nie Claude Code.
4. Sprawdź, czy narzędzie z komendy jest w PATH i czy są ustawione wszystkie wymagane zmienne środowiskowe (klucze API). W konfiguracji serwera stdio przekazujesz je przez opcję -e, na przykład claude mcp add moj-serwer -e API_KEY=xxx -- moja-komenda.
5. Jeśli serwer działa, ale wolno startuje, zwiększ limit pojedynczej próby, ustawiając zmienną MCP_TIMEOUT na większą wartość w milisekundach przed uruchomieniem Claude Code. Gdy problemem jest krótkie okno startowe, dostosuj MCP_CONNECT_TIMEOUT_MS.
6. Popraw wpis w .mcp.json (transport, url lub komendę, argumenty) albo dodaj serwer od nowa poprawną komendą claude mcp add, a stary usuń przez claude mcp remove.
7. Zrestartuj sesję Claude Code i ponownie sprawdź status, zanim uznasz problem za rozwiązany.

Jak sprawdzić, że zadziałało

Po poprawce uruchom claude mcp list - serwer powinien mieć status gotowy, a nie oczekujący czy z błędem. To odczyt wprost u źródła, a nie domysł na podstawie braku komunikatu.

Pewniejszy dowód: poproś Claude Code o wykonanie zadania, które wymaga narzędzia z tego serwera. Jeśli narzędzie realnie się wywołało i zwróciło dane, połączenie działa. Gdy chcesz zajrzeć głębiej, ponownie odpal claude --debug i sprawdź, czy w logach startu serwer melduje się bez ostrzeżeń.

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