# Claude Code tool search : trouver et charger les outils MCP > Comment fonctionne la recherche d’outils dans Claude Code : ce qui est chargé immédiatement dans le contexte, quand le mécanisme se désactive et comment configurer ENABLE_TOOL_SEARCH et alwaysLoad. Source: https://ailoot.ai/blog/fr/claude-code-tool-search-mcp-limit/ Canonical: https://ailoot.ai/blog/fr/claude-code-tool-search-mcp-limit/ Language: fr Publisher: Ailoot (https://ailoot.ai/) Translation: guide-055 Revision: sha256-a27f67394b2663be4e54712911d168cad04af176df998ef1b688e0d85e6dbce4 Si vous avez connecté plusieurs serveurs MCP à Claude Code, la recherche d’outils lui permet de charger les outils dont il a besoin à la demande, sans charger toutes les définitions à l’avance. Au démarrage, l’agent reçoit les noms des outils différés et les instructions des serveurs, puis recherche ce dont il a besoin dans le catalogue. Cela lui permet de travailler avec un grand nombre d’outils : la documentation d’Anthropic indique que la précision de sélection diminue lorsque plus de 30-50 outils sont chargés simultanément. Il s’agit d’une indication générale, et non d’une mesure de votre session. La recherche d’outils est activée par défaut lorsque le modèle la prend en charge, mais la plateforme, un proxy ou les paramètres peuvent la désactiver. [Documentation d’Ailoot : API, clés et configuration](https://ailoot.ai/docs/). ## Ce qui se passe dans le contexte sans recherche d’outils Chaque serveur MCP connecté ajoute ses outils à la liste des actions que l’agent peut appeler. Sans recherche d’outils, leurs définitions — nom, description et schéma des paramètres — sont chargées à l’avance dans le contexte. Les serveurs se connectent en arrière-plan au démarrage d’une session. Si l’agent a besoin d’un outil d’un serveur dont la connexion n’est pas encore établie, Claude Code attend à l’aide de l’outil interne `WaitForMcpServers`. Vous pouvez évaluer séparément, pour chaque connexion, le nombre d’outils et de jetons ajoutés par un serveur donné. La documentation officielle d’Anthropic fournit deux chiffres approximatifs (des valeurs générales, sans méthode de mesure indiquée) : - 50 outils peuvent occuper 10-20 mille jetons de contexte ; - la précision de sélection de l’outil adapté diminue lorsque plus de 30-50 outils sont chargés simultanément. ## Comment évaluer la recherche d’outils à partir des paramètres Pour savoir si la recherche d’outils devrait fonctionner dans la session actuelle, vérifiez les conditions suivantes : - quel modèle répond — Sonnet/Haiku/Opus 4.5 ou une version ultérieure : le mécanisme est disponible ; un modèle plus ancien : il ne l’est pas ; - si `ANTHROPIC_BASE_URL` est défini sur un hôte non standard — dans ce cas, le mécanisme est désactivé par défaut, sauf s’il est activé explicitement avec `ENABLE_TOOL_SEARCH` ; - la valeur de la variable `ENABLE_TOOL_SEARCH` — `false` désactive complètement le mécanisme ; `auto`/`auto:N` ne l’active que lorsque le volume des définitions atteint un seuil ; - si `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` est défini — sans paramètres gérés par l’organisation, cette variable maintient la recherche d’outils désactivée, même si l’utilisateur a défini `ENABLE_TOOL_SEARCH` ; - si l’outil `ToolSearch` est bloqué par `permissions.deny` dans les paramètres — une telle restriction désactive la recherche ; - quelle plateforme est utilisée — le mécanisme n’est pas disponible sur les déploiements Microsoft Foundry dans Azure, tandis que son comportement sur Google Cloud Agent Platform dépend de la version de Claude Code et du modèle. Cette vérification vous permet d’évaluer l’état à partir de la configuration, mais pas de l’observer au sein de la session. La section MCP et la section consacrée à la recherche d’outils dans la documentation de l’Agent SDK ne décrivent aucun indicateur direct « tool search: on/off » dans l’interface. Le fait que ces deux documents ne mentionnent pas un tel indicateur ne prouve pas qu’il n’en existe nulle part. Vous pouvez définir la variable avant de démarrer une session, par exemple `ENABLE_TOOL_SEARCH=auto:15 claude`. Pour que les outils d’un serveur spécifique soient toujours chargés, utilisez le champ `alwaysLoad: true` dans la configuration de ce serveur. Il est disponible pour tous les types de serveurs ; les conditions et les limites sont décrites dans la section alwaysLoad ci-dessous. ## Comment Claude Code trouve-t-il un outil MCP sans tout charger ? Lorsque la recherche d’outils est activée, seuls les noms des outils différés et les instructions du serveur sont chargés dans le contexte au démarrage de la session. Les instructions du serveur décrivent les tâches pour lesquelles il est utile. Lorsqu’une tâche nécessite une capacité qui ne figure pas encore dans le contexte, l’agent recherche lui-même un outil adapté dans le catalogue. La documentation de l’Agent SDK décrit le mécanisme de recherche plus en détail : par défaut, une recherche unique charge jusqu’à cinq des outils les plus pertinents du catalogue. Ils restent disponibles lors des tours suivants de la session jusqu’à ce que le SDK compacte les messages dans lesquels l’agent les a trouvés. Après la compaction, les outils découverts précédemment peuvent sortir du contexte, et l’agent les recherche à nouveau lorsqu’il en a besoin. Le catalogue prend en charge jusqu’à 10 000 outils. La documentation MCP de Claude Code ne donne pas ces chiffres précis, mais décrit le même principe de chargement différé. D’après la documentation de l’Agent SDK, chaque recherche ajoute un aller-retour supplémentaire. La documentation ne précise pas exactement ce que comprend cet aller-retour. Pour Claude Code, la documentation MCP décrit également une différence dans le signalement des erreurs : sans recherche d’outils, Claude Code ne signale pas au modèle les échecs de connexion aux serveurs. Lorsque la recherche est activée, le modèle reçoit des informations sur le serveur qui n’a pas réussi à se connecter et sur l’erreur rencontrée. Claude Code n’impose pas de limite fixe au nombre d’outils provenant d’un seul serveur. La limite pratique est le budget de la fenêtre de contexte de la session concernée. La configuration des outils fait partie des tâches de gestion du contexte d’un agent d’IA. ## Quand la recherche d’outils est désactivée par défaut Le mécanisme est activé par défaut, mais son fonctionnement dépend du modèle, de l’hôte API et de la plateforme. **Modèle.** La recherche d’outils nécessite un modèle prenant en charge les blocs tool_reference : Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 ou une version ultérieure. Avec des modèles plus anciens, Claude Code charge les définitions des outils à l’avance. **Hôte API.** Claude Code désactive la recherche d’outils lorsque la variable `ANTHROPIC_BASE_URL` pointe vers un hôte tiers : la plupart des proxys ne transmettent pas les blocs tool_reference spéciaux. Cela concerne les connexions à Claude via votre propre passerelle ou serveur proxy, plutôt que directement à l’adresse d’Anthropic. La désactivation est due à une valeur non standard de `ANTHROPIC_BASE_URL` ; le mode de paiement de l’abonnement n’en est pas la cause. Vous pouvez définir explicitement `ENABLE_TOOL_SEARCH` pour remplacer ce comportement. Si le proxy lui-même ne prend pas en charge les blocs tool_reference, forcer l’activation du mécanisme entraîne une erreur de requête. Dans ce cas, le chargement préalable des définitions ne sera pas utilisé comme solution de repli. **Plateforme de déploiement.** La recherche d’outils ne fonctionne pas sur les déploiements Microsoft Foundry hébergés sur Azure : le serveur rejette la requête et `ENABLE_TOOL_SEARCH` ne permet pas de contourner cette restriction. Sur Google Cloud Agent Platform, avant la version 2.1.221 de Claude Code, le mécanisme était désactivé pour tous les modèles, sauf si `ENABLE_TOOL_SEARCH=true` était défini explicitement. À partir de cette version, il est activé par défaut pour Opus/Sonnet/Haiku 4.5 et les versions ultérieures. Pour les modèles plus anciens sur cette plateforme, Claude Code charge toujours tous les outils à l’avance, car l’infrastructure de leurs serveurs rejette l’en-tête interne requis. La variable `ENABLE_TOOL_SEARCH` peut prendre cinq valeurs : - non définie — comportement standard, avec les exceptions indiquées ci-dessus ; - `true` — le mécanisme est activé pour les modèles qui le prennent en charge, à deux exceptions près : Azure Foundry et les anciens modèles d’Agent Platform ; les requêtes envoyées par un proxy ne prenant pas en charge les blocs tool_reference échoueront ; - `auto` — Claude Code charge les outils à l’avance tant que leurs définitions combinées occupent moins de 10% de la fenêtre de contexte, puis passe au chargement différé une fois ce seuil atteint ; - `auto:N` — même principe, avec un seuil en pourcentage défini manuellement ; - `false` — le mécanisme est complètement désactivé et tous les outils sont chargés à l’avance. Il existe également la variable `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` : si elle est définie, la recherche d’outils reste désactivée, et le fait qu’un utilisateur définisse `ENABLE_TOOL_SEARCH` n’y change rien. L’exception est le cas où l’organisation maintient la recherche d’outils activée par le biais de paramètres gérés, disponibles à partir de la version 2.1.227 de Claude Code. ## Effet de alwaysLoad sur le contexte et le démarrage Le champ `alwaysLoad: true` dans la configuration d’un serveur est disponible pour tous les types de serveurs. Il entraîne le chargement dans le contexte, au démarrage, de tous les outils de ce serveur, quelle que soit la valeur de `ENABLE_TOOL_SEARCH`. L’agent n’a pas besoin de les rechercher avant de les utiliser. Le chargement systématique des outils a deux conséquences. Chaque outil chargé à l’avance occupe une partie du contexte qui serait autrement disponible pour la tâche elle-même. En outre, le démarrage de la session attend la connexion de ce serveur, dans la limite du délai d’attente standard de cinq secondes. Il existe une exception pour un serveur distant disposant d’une entrée de cache valide : il fournit les outils depuis le cache sans se connecter et ne retarde pas le démarrage. Le cache de découverte est désactivé par défaut, sauf s’il a déjà été activé pour le compte pendant le déploiement progressif de la fonctionnalité. Vous pouvez aussi l’activer explicitement avec `MCP_DISCOVERY_CACHE=1`. L’exception de démarrage rapide s’applique lorsque le cache est actif et contient une entrée valide. Les outils dotés de `alwaysLoad` occupent malgré tout le contexte en permanence, que l’agent en ait eu besoin ou non lorsqu’il utilisait la recherche. Pour toute personne qui écrit son propre serveur MCP : les instructions du serveur aident Claude à comprendre quand rechercher ses outils, à la manière des Skills. Par défaut, Claude Code tronque à 2048 caractères la description de chaque outil et les instructions de chaque serveur. Placez donc les informations essentielles au début. Le choix de la manière d’étendre Claude Code dépend d’autre chose que du nombre de serveurs MCP connectés. Les guides [Claude Code : combien d’extensions garder actives à la fois](https://ailoot.ai/blog/fr/claude-code-skills-subagents-mcp-plugins/) et [Que choisir dans Claude Code : Skills, Subagents, MCP ou Plugins](https://ailoot.ai/blog/fr/skills-subagents-mcp-plugins-claude-code/) examinent les Skills, Subagents, MCP et Plugins selon les tâches. Pour configurer pas à pas des serveurs MCP spécifiques, consultez [Serveurs MCP pour Claude Code : combinaisons prêtes à l’emploi](https://ailoot.ai/blog/fr/mcp-servers-claude-code/). ## Et ensuite Pour un ensemble de moins d’environ 10 outils dont les définitions tiennent facilement dans le contexte, la documentation de l’Agent SDK indique qu’il est généralement plus rapide de tous les charger en une fois. Cependant, dans le comportement par défaut de Claude Code, lorsque la variable n’est pas définie et qu’aucune des restrictions ci-dessus ne s’applique, la recherche d’outils est activée et le chargement des outils MCP est différé jusqu’à leur recherche, à l’exception des serveurs dotés de `alwaysLoad`. Dans ce cas, vous pouvez définir explicitement `ENABLE_TOOL_SEARCH=auto` : les définitions seront chargées à l’avance tant que leur volume combiné est inférieur à 10% de la fenêtre de contexte, puis la recherche sera activée dès que le seuil sera atteint. Vous pouvez aussi définir `ENABLE_TOOL_SEARCH=false` si vous savez que l’ensemble ne va pas s’agrandir. Dans ce cas, Claude Code cessera d’informer le modèle des échecs de connexion aux serveurs, comme indiqué plus haut. Dans les autres cas, vérifiez à nouveau les conditions de fonctionnement lorsque l’environnement change : - passez à Sonnet/Haiku/Opus 4.5 ou à une version ultérieure si la session utilise un modèle plus ancien ; - si la connexion utilise une valeur non standard de `ANTHROPIC_BASE_URL`, définissez explicitement `ENABLE_TOOL_SEARCH=true` uniquement si le proxy lui-même transmet les blocs tool_reference ; - assurez-vous que la plateforme de déploiement ne figure pas parmi les exceptions : Azure Foundry ou les anciens modèles de Google Cloud Agent Platform. Si les conditions sont réunies et que les paramètres ne bloquent pas la recherche, vous pouvez connecter les serveurs MCP dont vous avez besoin. N’utilisez `alwaysLoad` que pour les serveurs dont les outils sont nécessaires à chaque tour de la session ; laissez les autres se charger via la recherche.
### Sources - [MCP dans Claude Code, section « Passer à l’échelle avec la recherche d’outils MCP » — documentation officielle d’Anthropic](https://code.claude.com/docs/en/mcp.md) - [Recherche d’outils dans l’Agent SDK — documentation officielle d’Anthropic](https://code.claude.com/docs/en/agent-sdk/tool-search.md)
Si vous avez besoin d’accéder à des modèles d’IA par l’intermédiaire d’Ailoot, consultez [Ailoot](https://ailoot.ai/). ## Questions fréquentes : Claude Code tool search : trouver et charger les outils MCP ### Pourquoi tool search échoue-t-il derrière un proxy malgré son activation ? L’hôte API tiers doit prendre en charge les blocs tool_reference. Forcer ENABLE_TOOL_SEARCH ne lui ajoute pas ce support ; un proxy incompatible peut refuser la requête au lieu de charger les outils d’avance. ### Quand activer alwaysLoad pour un serveur MCP ? Lorsque ses outils sont nécessaires à chaque tour. Toutes leurs définitions occupent alors le contexte initial, et le démarrage peut attendre la connexion, sauf si une entrée valide du cache de découverte s’applique. ## Ailoot · L’entreprise et son portefeuille de projets Ailoot s’appuie sur une expérience opérationnelle éprouvée, une large clientèle, un service stable et un suivi continu des KPI. L’entreprise et son portefeuille de projets : des millions de clients ; des ventes qui se chiffrent en milliards chaque mois. Ailoot met cette expérience opérationnelle au service de l’accès API aux fonctions d’IA dans les produits des clients, leurs agents, applications et automatisations.