Wyszukiwanie narzędzi w Claude Code: jak agent znajduje potrzebne mu narzędzie MCP

Jeśli masz podłączonych kilka serwerów MCP do Claude Code, wyszukiwanie narzędzi pozwala ładować na żądanie te narzędzia, które są potrzebne, bez wcześniejszego ładowania wszystkich definicji. Podczas uruchamiania agent otrzymuje nazwy odroczonych narzędzi i instrukcje serwerów, a następnie wyszukuje w katalogu potrzebne narzędzia. Ułatwia mu to pracę z dużym zestawem narzędzi: dokumentacja Anthropic podaje, że trafność wyboru spada, gdy jednocześnie załadowanych jest więcej niż 30-50 narzędzi. To ogólna wskazówka, a nie pomiar z Twojej sesji. Wyszukiwanie narzędzi jest domyślnie włączone, gdy obsługuje je model, ale platforma, serwer proxy lub ustawienia mogą je wyłączyć.

Dokumentacja Ailoot: API, klucze i konfiguracja.

Co dzieje się z kontekstem bez wyszukiwania narzędzi#

Każdy podłączony serwer MCP dodaje swoje narzędzia do listy elementów, które agent może wywołać. Bez wyszukiwania narzędzi ich definicje — nazwa, opis i schemat parametrów — są wcześniej ładowane do kontekstu. Serwery łączą się w tle po rozpoczęciu sesji. Jeśli potrzebne jest narzędzie z serwera, który nie zakończył jeszcze łączenia, Claude Code czeka za pomocą wewnętrznego narzędzia WaitForMcpServers. Możesz osobno ocenić, ile narzędzi i tokenów dodaje konkretny serwer dla każdego połączenia.

Oficjalna dokumentacja Anthropic podaje dwie przybliżone wartości (ogólne liczby, bez określonej metody pomiaru):

• 50 narzędzi może zajmować 10-20 tysięcy tokenów kontekstu;
• trafność wyboru odpowiedniego narzędzia spada, gdy jednocześnie załadowanych jest więcej niż 30-50 narzędzi.

Jak ocenić działanie wyszukiwania narzędzi na podstawie ustawień#

Aby sprawdzić, czy wyszukiwanie narzędzi powinno działać w bieżącej sesji, sprawdź następujące warunki:

• który model odpowiada — Sonnet/Haiku/Opus 4.5 lub nowszy: mechanizm jest dostępny; starszy model: nie jest dostępny;
• czy ANTHROPIC_BASE_URL wskazuje niestandardowy host — w takim przypadku mechanizm jest domyślnie wyłączony, chyba że zostanie jawnie włączony przez ENABLE_TOOL_SEARCH;
• wartość zmiennej ENABLE_TOOL_SEARCH — false całkowicie wyłącza mechanizm; auto/auto:N włącza go dopiero po osiągnięciu progu przez łączny rozmiar definicji;
• czy ustawiono CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS — bez zarządzanych ustawień organizacji utrzymuje ono wyłączone wyszukiwanie narzędzi nawet wtedy, gdy użytkownik ustawił ENABLE_TOOL_SEARCH;
• czy narzędzie ToolSearch jest blokowane przez permissions.deny w ustawieniach — takie ograniczenie wyłącza wyszukiwanie;
• używana platforma — mechanizm jest niedostępny we wdrożeniach Microsoft Foundry na Azure, a na Google Cloud Agent Platform jego działanie zależy od wersji Claude Code i modelu.

Ta kontrola pozwala ocenić stan na podstawie konfiguracji, ale nie obserwować go wewnątrz sesji. Sekcja MCP i sekcja wyszukiwania narzędzi w dokumentacji Agent SDK nie opisują bezpośredniego wskaźnika „wyszukiwanie narzędzi: włączone/wyłączone” w interfejsie. Brak wzmianki w tych dwóch dokumentach nie dowodzi, że taki wskaźnik nie istnieje nigdzie indziej.

Możesz ustawić zmienną przed rozpoczęciem sesji, na przykład ENABLE_TOOL_SEARCH=auto:15 claude. Aby mieć pewność, że narzędzia konkretnego serwera będą zawsze ładowane, użyj pola alwaysLoad: true w konfiguracji tego serwera. Jest ono dostępne dla wszystkich typów serwerów; warunki i ograniczenia opisano w sekcji alwaysLoad poniżej.

Jak działa wyszukiwanie narzędzi#

Gdy wyszukiwanie narzędzi jest włączone, podczas uruchamiania sesji do kontekstu ładowane są tylko nazwy odroczonych narzędzi i instrukcje serwera. Instrukcje serwera opisują, do jakich zadań przydaje się dany serwer. Gdy zadanie wymaga funkcji, której nie ma jeszcze w kontekście, agent sam wyszukuje odpowiednie narzędzie w katalogu.

Dokumentacja Agent SDK dokładniej opisuje mechanizm wyszukiwania: domyślnie pojedyncze wyszukiwanie ładuje z katalogu maksymalnie pięć najbardziej trafnych narzędzi. Pozostają one dostępne w kolejnych turach sesji, dopóki SDK nie skompaktuje wiadomości, w których agent je znalazł. Po kompakcji wcześniej odkryte narzędzia mogą zniknąć z kontekstu, a agent wyszuka je ponownie, gdy będą potrzebne. Katalog obsługuje maksymalnie 10 000 narzędzi. Dokumentacja MCP samego Claude Code nie podaje tych konkretnych wartości, ale opisuje tę samą zasadę odroczonego ładowania.

Według dokumentacji Agent SDK każde wyszukiwanie dodaje jedną dodatkową rundę komunikacji. Dokumentacja nie precyzuje, co dokładnie obejmuje ta runda. W przypadku Claude Code dokumentacja MCP opisuje również różnicę w raportowaniu błędów: bez wyszukiwania narzędzi Claude Code nie informuje modelu o nieudanych połączeniach z serwerami. Gdy wyszukiwanie jest włączone, model otrzymuje informację, z którym serwerem nie udało się połączyć i jaki wystąpił błąd.

Claude Code nie narzuca stałego limitu liczby narzędzi z jednego serwera. Praktyczny limit wyznacza budżet okna kontekstu dla konkretnej sesji.

Konfigurowanie narzędzi jest jednym z zadań związanych z zarządzaniem kontekstem agenta AI.

Kiedy wyszukiwanie narzędzi jest domyślnie wyłączone#

Mechanizm jest domyślnie włączony, ale jego działanie zależy od modelu, hosta API i platformy.

Model. Wyszukiwanie narzędzi wymaga modelu obsługującego bloki tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 lub nowszego. W przypadku starszych modeli Claude Code ładuje definicje narzędzi z wyprzedzeniem.

Host API. Claude Code wyłącza wyszukiwanie narzędzi, gdy zmienna ANTHROPIC_BASE_URL wskazuje hosta zewnętrznego: większość serwerów proxy nie przekazuje specjalnych bloków tool_reference. Dotyczy to połączenia z Claude przez własną bramę lub serwer proxy zamiast bezpośrednio pod adresem Anthropic. Przyczyną wyłączenia jest niestandardowa wartość ANTHROPIC_BASE_URL; sam sposób opłacania subskrypcji nie ma na to wpływu. Możesz jawnie ustawić ENABLE_TOOL_SEARCH, aby zmienić to zachowanie. Jeśli sam serwer proxy nie obsługuje bloków tool_reference, wymuszenie włączenia mechanizmu spowoduje błąd żądania. W takim przypadku nie nastąpi powrót do wcześniejszego ładowania definicji.

Platforma wdrożeniowa. Wyszukiwanie narzędzi nie działa we wdrożeniach Microsoft Foundry hostowanych na Azure: serwer odrzuca żądanie, a ENABLE_TOOL_SEARCH nie zmienia tego zachowania. Na Google Cloud Agent Platform przed wersją Claude Code 2.1.221 mechanizm był wyłączony dla wszystkich modeli, chyba że jawnie ustawiono ENABLE_TOOL_SEARCH=true. Od tej wersji jest domyślnie włączony dla Opus/Sonnet/Haiku 4.5 i nowszych. W przypadku starszych modeli na tej platformie Claude Code nadal ładuje wszystkie narzędzia z wyprzedzeniem, ponieważ infrastruktura serwera odrzuca wymagany nagłówek wewnętrzny.

Zmienna ENABLE_TOOL_SEARCH ma pięć możliwych ustawień:

• nieustawiona — standardowe działanie, z wyjątkami wymienionymi powyżej;
• true — mechanizm jest włączony w obsługujących go modelach, z wyjątkiem dwóch przypadków: Azure Foundry i starszych modeli Agent Platform; żądania wysyłane przez serwer proxy bez obsługi bloków tool_reference zakończą się niepowodzeniem;
• auto — Claude Code ładuje narzędzia z wyprzedzeniem, dopóki łączne definicje zajmują mniej niż 10% okna kontekstu, a po osiągnięciu tego progu przełącza się na ładowanie odroczone;
• auto:N — ta sama zasada, z ręcznie określonym progiem procentowym;
• false — mechanizm jest całkowicie wyłączony, a wszystkie narzędzia są ładowane z wyprzedzeniem.

Istnieje też zmienna CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: jeśli jest ustawiona, wyszukiwanie narzędzi pozostaje wyłączone, a ustawienie przez użytkownika ENABLE_TOOL_SEARCH tego nie zmienia. Wyjątkiem jest sytuacja, gdy organizacja utrzymuje włączone wyszukiwanie narzędzi za pomocą zarządzanych ustawień, dostępnych od wersji Claude Code 2.1.227.

Jak działa alwaysLoad i jaki ma wpływ na kontekst oraz uruchamianie#

Pole alwaysLoad: true w konfiguracji serwera jest dostępne dla wszystkich typów serwerów. Dzięki niemu wszystkie narzędzia tego serwera są ładowane do kontekstu podczas uruchamiania, niezależnie od ustawienia ENABLE_TOOL_SEARCH. Agent nie musi ich wyszukiwać przed użyciem.

Stałe ładowanie narzędzi ma dwa skutki. Każde narzędzie załadowane z wyprzedzeniem zajmuje część kontekstu, którą można by przeznaczyć na samo zadanie. Ponadto podczas uruchamiania sesji następuje oczekiwanie na połączenie z tym serwerem, w ramach standardowego limitu czasu wynoszącego pięć sekund.

Wyjątkiem jest serwer zdalny z prawidłowym wpisem w pamięci podręcznej: udostępnia narzędzia z pamięci podręcznej bez nawiązywania połączenia i nie opóźnia uruchamiania. Pamięć podręczna wykrywania jest domyślnie wyłączona, chyba że została już włączona dla konta podczas stopniowego wdrażania tej funkcji. Możesz też włączyć ją jawnie przez MCP_DISCOVERY_CACHE=1. Wyjątek umożliwiający szybkie uruchomienie obowiązuje, gdy pamięć podręczna jest aktywna i zawiera prawidłowy wpis. Narzędzia z alwaysLoad stale zajmują miejsce w kontekście, niezależnie od tego, czy agent potrzebowałby ich podczas pracy z wyszukiwaniem.

Jeśli piszesz własny serwer MCP: instrukcje serwera pomagają Claude zrozumieć, kiedy wyszukiwać jego narzędzia, podobnie jak Skills. Claude Code domyślnie skraca opisy poszczególnych narzędzi i instrukcje poszczególnych serwerów do 2048 znaków, dlatego umieść najważniejsze szczegóły na początku.

Wybór sposobu rozszerzenia Claude Code zależy nie tylko od liczby podłączonych serwerów MCP. Przewodniki Claude Code: ile rozszerzeń zachować jednocześnie oraz Co wybrać w Claude Code: Skills, Subagents, MCP czy Plugins omawiają Skills, Subagents, MCP i Plugins w kontekście różnych zadań. Instrukcje konfiguracji konkretnych serwerów MCP krok po kroku znajdziesz w przewodniku Serwery MCP dla Claude Code: gotowe zestawy.

Co dalej#

W przypadku zestawu obejmującego mniej więcej mniej niż 10 narzędzi, których definicje bez problemu mieszczą się w kontekście, dokumentacja Agent SDK wskazuje, że zwykle szybciej jest załadować je wszystkie naraz. Jednak w domyślnym działaniu Claude Code, gdy zmienna nie jest ustawiona i nie obowiązuje żadne z powyższych ograniczeń, wyszukiwanie narzędzi jest włączone, a ładowanie narzędzi MCP jest odroczone do czasu wyszukiwania, z wyjątkiem serwerów z alwaysLoad.

W tym przypadku możesz jawnie ustawić ENABLE_TOOL_SEARCH=auto: definicje będą ładowane z wyprzedzeniem, dopóki ich łączny rozmiar nie przekroczy 10% okna kontekstu; po osiągnięciu progu włączy się wyszukiwanie. Jeśli wiesz, że zestaw nie będzie się powiększać, możesz też ustawić ENABLE_TOOL_SEARCH=false. W takim przypadku Claude Code przestanie informować model o nieudanych połączeniach z serwerami, jak opisano powyżej.

W pozostałych przypadkach ponownie sprawdź warunki działania, gdy zmieni się środowisko:

• jeśli w sesji używany jest starszy model, przełącz się na Sonnet/Haiku/Opus 4.5 lub nowszy;
• jeśli połączenie korzysta z niestandardowej wartości ANTHROPIC_BASE_URL, jawnie ustaw ENABLE_TOOL_SEARCH=true tylko wtedy, gdy sam serwer proxy przekazuje bloki tool_reference;
• upewnij się, że platforma wdrożeniowa nie należy do wyjątków: Azure Foundry lub starsze modele Google Cloud Agent Platform.

Jeśli warunki są spełnione, a wyszukiwanie nie jest blokowane przez ustawienia, możesz podłączyć potrzebne serwery MCP. Używaj alwaysLoad tylko dla serwerów, których narzędzia są potrzebne w każdej turze sesji; pozostałym pozwól ładować się przez wyszukiwanie.

Jeśli potrzebujesz dostępu do modeli AI za pośrednictwem Ailoot, zajrzyj na stronę Ailoot.