Claude Code Tool Search: trovare e configurare gli MCP

Se hai collegato diversi server MCP a Claude Code, la ricerca degli strumenti gli consente di caricare su richiesta gli strumenti necessari, senza caricare in anticipo tutte le definizioni. All’avvio, l’agente riceve i nomi degli strumenti differiti e le istruzioni dei server, quindi cerca nel catalogo ciò di cui ha bisogno. Questo lo aiuta a lavorare con un ampio insieme di strumenti: la documentazione di Anthropic afferma che la precisione della selezione diminuisce quando vengono caricati più di 30-50 strumenti alla volta. Si tratta di un’indicazione generale, non di una misurazione della tua sessione. La ricerca degli strumenti è abilitata per impostazione predefinita quando il modello la supporta, ma la piattaforma, un proxy o le impostazioni possono disabilitarla.

Documentazione Ailoot: API, chiavi e configurazione.

Cosa succede al contesto senza la ricerca degli strumenti#

Ogni server MCP collegato aggiunge i propri strumenti all’elenco di quelli che l’agente può invocare. Senza la ricerca degli strumenti, le loro definizioni — nome, descrizione e schema dei parametri — vengono caricate in anticipo nel contesto. I server si connettono in background all’avvio di una sessione. Se serve uno strumento di un server la cui connessione non è ancora stata completata, Claude Code attende tramite lo strumento interno WaitForMcpServers. Puoi valutare separatamente, per ogni connessione, quanti strumenti e token aggiunge un server specifico.

La documentazione ufficiale di Anthropic riporta due valori approssimativi (numeri generali, senza indicare un metodo di misurazione):

• 50 strumenti possono occupare 10-20 mila token di contesto;
• la precisione nella selezione dello strumento giusto diminuisce quando ne vengono caricati più di 30-50 alla volta.

Come valutare la ricerca degli strumenti dalle impostazioni#

Per capire se la ricerca degli strumenti dovrebbe funzionare nella sessione corrente, controlla queste condizioni:

• quale modello risponde — Sonnet/Haiku/Opus 4.5 o versioni successive: il meccanismo è disponibile; un modello precedente: non lo è;
• se ANTHROPIC_BASE_URL è impostato su un host non standard — in tal caso, il meccanismo è disattivato per impostazione predefinita, a meno che non venga abilitato esplicitamente tramite ENABLE_TOOL_SEARCH;
• il valore della variabile ENABLE_TOOL_SEARCH — false disabilita completamente il meccanismo; auto/auto:N lo abilita solo quando il volume delle definizioni raggiunge una soglia;
• se è impostato CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS — in assenza delle impostazioni gestite dell’organizzazione, mantiene disattivata la ricerca degli strumenti anche se l’utente ha impostato ENABLE_TOOL_SEARCH;
• se lo strumento ToolSearch è bloccato tramite permissions.deny nelle impostazioni — tale restrizione disabilita la ricerca;
• quale piattaforma viene usata — il meccanismo non è disponibile sulle distribuzioni Microsoft Foundry in Azure, mentre su Google Cloud Agent Platform il comportamento dipende dalla versione di Claude Code e dal modello.

Questa verifica consente di valutare lo stato dalla configurazione, ma non di osservarlo all’interno della sessione. La sezione MCP e quella sulla ricerca degli strumenti nella documentazione dell’Agent SDK non descrivono un indicatore diretto «ricerca degli strumenti: attiva/disattivata» nell’interfaccia. Il fatto che questi due documenti non ne parlino non dimostra che un indicatore simile non esista altrove.

Puoi impostare la variabile prima di avviare una sessione, per esempio ENABLE_TOOL_SEARCH=auto:15 claude. Per assicurarti che gli strumenti di un server specifico vengano sempre caricati, usa il campo alwaysLoad: true nella configurazione di quel server. È disponibile per tutti i tipi di server; condizioni e limitazioni sono descritte più avanti nella sezione alwaysLoad.

Come funziona la ricerca degli strumenti#

Quando la ricerca degli strumenti è abilitata, all’avvio della sessione vengono caricati nel contesto solo i nomi degli strumenti differiti e le istruzioni del server. Le istruzioni del server descrivono per quali attività quel server è utile. Quando un’attività richiede una funzionalità che non è ancora nel contesto, l’agente cerca autonomamente uno strumento adatto nel catalogo.

La documentazione dell’Agent SDK descrive più nel dettaglio il meccanismo di ricerca: per impostazione predefinita, una singola ricerca carica dal catalogo fino a cinque degli strumenti più pertinenti. Restano disponibili nei turni successivi della sessione finché l’SDK non compatta i messaggi in cui l’agente li ha individuati. Dopo la compattazione, gli strumenti individuati in precedenza possono uscire dal contesto e l’agente li cerca di nuovo la volta successiva che servono. Il catalogo supporta fino a 10 000 strumenti. La documentazione MCP di Claude Code non riporta questi valori specifici, ma descrive lo stesso principio di caricamento differito.

Secondo la documentazione dell’Agent SDK, ogni ricerca aggiunge un round-trip. La documentazione non specifica esattamente cosa includa quel round-trip. Per Claude Code, la documentazione MCP descrive anche una differenza nella segnalazione degli errori: senza la ricerca degli strumenti, Claude Code non comunica al modello le connessioni ai server non riuscite. Quando la ricerca è abilitata, il modello riceve informazioni su quale server non è riuscito a connettersi e sull’errore verificatosi.

Claude Code non impone un limite fisso al numero di strumenti provenienti da un singolo server. Il limite pratico è il budget della finestra di contesto per la sessione specifica.

La configurazione degli strumenti è una delle attività che rientrano nella gestione del contesto di un agente AI.

Quando la ricerca degli strumenti è disabilitata per impostazione predefinita#

Il meccanismo è abilitato per impostazione predefinita, ma il suo funzionamento dipende dal modello, dall’host API e dalla piattaforma.

Modello. La ricerca degli strumenti richiede un modello che supporti i blocchi tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 o versioni successive. Per i modelli precedenti, Claude Code carica in anticipo le definizioni degli strumenti.

Host API. Claude Code disabilita la ricerca degli strumenti quando la variabile ANTHROPIC_BASE_URL punta a un host di terze parti: la maggior parte dei proxy non inoltra i blocchi speciali tool_reference. Questo vale quando ti connetti a Claude tramite un gateway o server proxy tuo, invece che direttamente all’indirizzo di Anthropic. La disattivazione dipende da un valore non standard di ANTHROPIC_BASE_URL; il modo in cui viene pagato l’abbonamento non la provoca di per sé. Puoi impostare esplicitamente ENABLE_TOOL_SEARCH per sovrascrivere questo comportamento. Se il proxy non supporta i blocchi tool_reference, forzare l’attivazione del meccanismo provoca un errore della richiesta. In questo caso non si passa al caricamento anticipato delle definizioni.

Piattaforma di distribuzione. La ricerca degli strumenti non funziona sulle distribuzioni Microsoft Foundry ospitate in Azure: il server rifiuta la richiesta e ENABLE_TOOL_SEARCH non sovrascrive questa limitazione. Su Google Cloud Agent Platform, prima della versione 2.1.221 di Claude Code, il meccanismo era disattivato per tutti i modelli, a meno che non fosse impostato esplicitamente ENABLE_TOOL_SEARCH=true. A partire da quella versione, è abilitato per impostazione predefinita per Opus/Sonnet/Haiku 4.5 e versioni successive. Per i modelli precedenti sulla piattaforma, Claude Code continua a caricare in anticipo tutti gli strumenti perché l’infrastruttura del server rifiuta l’header interno richiesto.

La variabile ENABLE_TOOL_SEARCH ha cinque impostazioni possibili:

• non impostata — comportamento standard, con le eccezioni elencate sopra;
• true — il meccanismo è abilitato sui modelli che lo supportano, con due eccezioni: Azure Foundry e i modelli precedenti di Agent Platform; le richieste inviate tramite un proxy che non supporta i blocchi tool_reference falliranno;
• auto — Claude Code carica gli strumenti in anticipo finché le loro definizioni combinate occupano meno del 10% della finestra di contesto, quindi passa al caricamento differito quando viene raggiunta tale soglia;
• auto:N — stesso principio, con una soglia percentuale specificata manualmente;
• false — il meccanismo è completamente disabilitato e tutti gli strumenti vengono caricati in anticipo.

Esiste anche la variabile CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: se è impostata, la ricerca degli strumenti resta disattivata e l’impostazione di ENABLE_TOOL_SEARCH da parte dell’utente non cambia la situazione. L’eccezione si applica quando l’organizzazione mantiene abilitata la ricerca degli strumenti tramite le impostazioni gestite, disponibili a partire dalla versione 2.1.227 di Claude Code.

Cosa fa alwaysLoad e come influisce sul contesto e sull’avvio#

Il campo alwaysLoad: true nella configurazione di un server è disponibile per tutti i tipi di server. Con questo campo, tutti gli strumenti di quel server vengono caricati nel contesto all’avvio, indipendentemente dall’impostazione di ENABLE_TOOL_SEARCH. Prima di usarli, l’agente non deve cercarli.

Il caricamento sempre attivo degli strumenti ha due conseguenze. Ogni strumento caricato in anticipo occupa una parte del contesto che altrimenti sarebbe disponibile per l’attività stessa. Inoltre, l’avvio della sessione attende la connessione a questo server, entro il timeout standard di cinque secondi.

L’eccezione è un server remoto con una voce valida nella cache: fornisce gli strumenti dalla cache senza connettersi e non ritarda l’avvio. La cache di individuazione è disattivata per impostazione predefinita, a meno che non sia già stata abilitata per l’account durante il rilascio graduale della funzionalità. Puoi anche abilitarla esplicitamente tramite MCP_DISCOVERY_CACHE=1. L’eccezione per l’avvio rapido si applica quando la cache è attiva e contiene una voce valida. Gli strumenti con alwaysLoad continuano a occupare permanentemente il contesto, indipendentemente dal fatto che all’agente sarebbero serviti durante il lavoro tramite ricerca.

Per chi scrive un proprio server MCP: le istruzioni del server aiutano Claude a capire quando cercare i suoi strumenti, in modo simile a quanto fanno le Skills. Per impostazione predefinita, Claude Code tronca a 2048 caratteri la descrizione di ogni strumento e le istruzioni di ogni server, quindi inserisci i dettagli essenziali all’inizio.

La scelta di come estendere Claude Code dipende da più fattori del numero di server MCP collegati. Le guide Claude Code: quanti componenti aggiuntivi mantenere attivi contemporaneamente e Cosa scegliere in Claude Code: Skills, Subagents, MCP o Plugins esaminano Skills, Subagents, MCP e Plugins per diverse attività. Per istruzioni dettagliate sulla configurazione di server MCP specifici, consulta Server MCP per Claude Code: combinazioni pronte all’uso.

E adesso?#

Per un insieme di meno di circa 10 strumenti, le cui definizioni entrano nel contesto senza difficoltà, la documentazione dell’Agent SDK osserva che di solito è più veloce caricarli tutti in una volta. Tuttavia, nel comportamento predefinito di Claude Code, quando la variabile non è impostata e non si applica nessuna delle limitazioni indicate sopra, la ricerca degli strumenti è abilitata e il caricamento degli strumenti MCP viene differito fino alla ricerca, fatta eccezione per i server con alwaysLoad.

In questo caso, puoi impostare esplicitamente ENABLE_TOOL_SEARCH=auto: le definizioni verranno caricate in anticipo finché il loro volume combinato è inferiore al 10% della finestra di contesto e la ricerca verrà abilitata al raggiungimento della soglia. Un’altra opzione è ENABLE_TOOL_SEARCH=false se sai che l’insieme non crescerà. In tal caso, Claude Code smetterà di comunicare al modello gli errori di connessione ai server, come descritto sopra.

Negli altri casi, controlla di nuovo le condizioni operative quando cambia l’ambiente:

• passa a Sonnet/Haiku/Opus 4.5 o versioni successive se la sessione usa un modello precedente;
• se la connessione usa un valore non standard di ANTHROPIC_BASE_URL, imposta esplicitamente ENABLE_TOOL_SEARCH=true solo quando il proxy stesso inoltra i blocchi tool_reference;
• assicurati che la piattaforma di distribuzione non rientri tra le eccezioni: Azure Foundry o i modelli precedenti di Google Cloud Agent Platform.

Se le condizioni sono soddisfatte e la ricerca non è bloccata dalle impostazioni, puoi collegare i server MCP che ti servono. Usa alwaysLoad solo per i server i cui strumenti servono a ogni turno della sessione; lascia che gli altri vengano caricati tramite la ricerca.

Se hai bisogno di accedere ai modelli AI tramite Ailoot, dai un’occhiata ad Ailoot.