Claude Code nie widzi narzędzi MCP - co sprawdzić

Claude Code

Claude Code nie widzi narzędzi MCP - co sprawdzić

W skrócie

To subtelniejszy problem niż serwer, który w ogóle się nie łączy. Tutaj w komendzie /mcp serwer pokazuje status "connected", ale gdy prosisz agenta o coś, co powinien zrobić przez ten serwer, on tego nie robi - pisze kod ręcznie, mówi że nie ma dostępu albo po prostu ignoruje możliwość. Claude Code, narzędzie CLI od Anthropic, ma połączenie, ale narzędzia z serwera są niewidoczne dla agenta albo nie są przez niego używane. Dotyka to głównie osób konfigurujących MCP w większych projektach, gdzie łatwo pomylić zasięgi i konteksty.

Jak to wygląda w praktyce

Prosisz o operację, która wymaga serwera MCP, a agent odpowiada, jakby narzędzia nie było:

Ty: sprawdz w bazie ile jest rekordow w tabeli users

Claude: Nie mam bezposredniego dostepu do Twojej bazy danych.
Moge napisac zapytanie SQL, ktore uruchomisz samodzielnie...

Tymczasem /mcp pokazuje serwer bazy jako połączony. Ta rozbieżność - serwer połączony, a narzędzia jakby ich nie było - to sygnał, że narzędzia nie są zarejestrowane w bieżącym kontekście albo że agent nie skojarzył zadania z dostępnym narzędziem MCP.

Dlaczego Claude Code tak działa

Jest kilka mechanizmów. Po pierwsze, zasięg: serwer dodany jako lokalny w jednym katalogu nie będzie widoczny, gdy uruchomisz Claude Code z innego katalogu - konfiguracja projektowa (.mcp.json) i lokalna są przypięte do miejsca. Po drugie, narzędzia MCP są ładowane przy starcie sesji - jeśli dodałeś serwer w trakcie działania sesji, może ona jeszcze nie mieć jego narzędzi, dopóki jej nie odświeżysz. Po trzecie, sam model musi zdecydować, że dane narzędzie jest właściwe do zadania - jeśli nazwa narzędzia jest niejasna albo polecenie sformułowane ogólnie, agent może nie skojarzyć, że powinien go użyć. Narzędzia MCP mają w Claude Code nazwy w formacie mcp__nazwaserwera__nazwanarzedzia, co pomaga je jednoznacznie wskazać.

Jak to rozwiązać krok po kroku

1. Otwórz /mcp i rozwiń serwer - sprawdź, czy faktycznie wystawia narzędzia i jak się nazywają. Jeśli lista narzędzi jest pusta mimo statusu "connected", problem jest po stronie serwera, nie agenta.
2. Zrestartuj sesję Claude Code (zamknij i uruchom ponownie). Narzędzia MCP wczytują się przy starcie, więc serwer dodany w trakcie pracy bywa widoczny dopiero po restarcie.
3. Sprawdź zasięg i katalog: uruchom claude mcp list z tego samego katalogu, w którym pracujesz. Jeśli serwera nie ma na liście, dodałeś go w innym zasięgu - dodaj ponownie z zasięgiem user (-s user), żeby był dostępny wszędzie, albo pracuj z właściwego katalogu.
4. Wskaż agentowi narzędzie wprost. Zamiast ogólnego "sprawdź w bazie" napisz "użyj narzędzia MCP do bazy i policz rekordy w tabeli users" - jasne polecenie pomaga modelowi wybrać właściwe narzędzie.
5. Sprawdź, czy narzędzia MCP nie są zablokowane przez uprawnienia. W settings.json reguła deny mogłaby odciąć narzędzie - zweryfikuj to komendą /permissions.
6. Jeśli serwer wystawia bardzo wiele narzędzi, rozważ ograniczenie ich liczby w konfiguracji serwera - nadmiar narzędzi rozmywa kontekst i utrudnia modelowi trafny wybór.

Jak sprawdzić, że zadziałało

Po restarcie sesji wpisz /mcp i potwierdź, że serwer jest połączony oraz że po rozwinięciu widać konkretne narzędzia z nazwami. Następnie zleć zadanie, wskazując narzędzie wprost - jeśli agent tym razem sięgnie po narzędzie MCP i zwróci realny wynik z podłączonego systemu (a nie propozycję kodu do samodzielnego uruchomienia), problem jest rozwiązany. Dla pewności powtórz to samo polecenie sformułowane ogólniej - gdy i wtedy agent użyje narzędzia, oznacza to, że jest ono w pełni dostępne i rozpoznawane w tej sesji.

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