Búsqueda de herramientas MCP en Claude Code: cómo configurarla

Si has conectado varios servidores MCP a Claude Code, la búsqueda de herramientas le permite cargar bajo demanda las herramientas que necesita, sin cargar todas las definiciones por adelantado. Al iniciarse, el agente recibe los nombres de las herramientas diferidas y las instrucciones de los servidores, y luego busca en el catálogo lo que necesita. Esto le ayuda a trabajar con un conjunto amplio de herramientas: la documentación de Anthropic indica que la precisión de selección disminuye cuando se cargan más de 30-50 herramientas a la vez. Es una orientación general, no una medición de tu sesión. La búsqueda de herramientas está activada de forma predeterminada cuando el modelo la admite, pero la plataforma, un proxy o la configuración pueden desactivarla.

Documentación de Ailoot: API, claves y configuración.

¿Qué ocurre con el contexto sin la búsqueda de herramientas?#

Cada servidor MCP conectado añade sus herramientas a la lista de cosas que el agente puede invocar. Sin la búsqueda de herramientas, sus definiciones —nombre, descripción y esquema de parámetros— se cargan en el contexto por adelantado. Los servidores se conectan en segundo plano cuando se inicia una sesión. Si se necesita una herramienta de un servidor que aún no ha terminado de conectarse, Claude Code espera mediante la herramienta interna WaitForMcpServers. Puedes evaluar por separado, para cada conexión, cuántas herramientas y tokens añade un servidor concreto.

La documentación oficial de Anthropic ofrece dos cifras aproximadas (números generales, sin indicar un método de medición):

• 50 herramientas pueden ocupar entre 10 y 20 mil tokens de contexto;
• la precisión al seleccionar la herramienta adecuada disminuye cuando se cargan más de 30-50 a la vez.

Cómo evaluar la búsqueda de herramientas a partir de la configuración#

Para saber si la búsqueda de herramientas debería funcionar en la sesión actual, comprueba estas condiciones:

• qué modelo responde —Sonnet/Haiku/Opus 4.5 o posterior: el mecanismo está disponible; un modelo anterior: no lo está—;
• si ANTHROPIC_BASE_URL está configurada con un host no estándar; en ese caso, el mecanismo está desactivado de forma predeterminada, a menos que se habilite explícitamente mediante ENABLE_TOOL_SEARCH;
• el valor de la variable ENABLE_TOOL_SEARCH: false desactiva el mecanismo por completo; auto/auto:N lo habilita solo cuando el volumen de las definiciones alcanza un umbral;
• si CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS está configurada; sin la configuración administrada de la organización, mantiene desactivada la búsqueda de herramientas aunque el usuario haya configurado ENABLE_TOOL_SEARCH;
• si la herramienta ToolSearch está bloqueada mediante permissions.deny en la configuración; una restricción así desactiva la búsqueda;
• qué plataforma se utiliza: el mecanismo no está disponible en las implementaciones de Microsoft Foundry en Azure, mientras que en Google Cloud Agent Platform su comportamiento depende de la versión de Claude Code y del modelo.

Esta comprobación te permite evaluar el estado a partir de la configuración, pero no observarlo dentro de la sesión. La sección MCP y la sección sobre búsqueda de herramientas de la documentación de Agent SDK no describen un indicador directo «tool search: on/off» en la interfaz. Que estos dos documentos no mencionen tal indicador no demuestra que no exista en ningún otro lugar.

Puedes configurar la variable antes de iniciar una sesión, por ejemplo, ENABLE_TOOL_SEARCH=auto:15 claude. Para asegurarte de que las herramientas de un servidor concreto siempre se carguen, utiliza el campo alwaysLoad: true en la configuración de ese servidor. Está disponible para todos los tipos de servidor; las condiciones y limitaciones se describen en la sección alwaysLoad más abajo.

Cómo funciona la búsqueda de herramientas#

Cuando la búsqueda de herramientas está habilitada, al inicio de la sesión solo se cargan en el contexto los nombres de las herramientas diferidas y las instrucciones del servidor. Las instrucciones del servidor describen para qué tareas resulta útil. Cuando una tarea requiere una capacidad que aún no está en el contexto, el agente busca por su cuenta una herramienta adecuada en el catálogo.

La documentación de Agent SDK describe con más detalle el mecanismo de búsqueda: de forma predeterminada, una sola búsqueda carga hasta cinco de las herramientas más relevantes del catálogo. Permanecen disponibles en los turnos siguientes de la sesión hasta que el SDK compacte los mensajes en los que el agente las encontró. Después de la compactación, las herramientas descubiertas previamente pueden salir del contexto, y el agente vuelve a buscarlas la próxima vez que las necesita. El catálogo admite hasta 10 000 herramientas. La documentación MCP de Claude Code no ofrece estas cifras concretas, pero describe el mismo principio de carga diferida.

Según la documentación de Agent SDK, cada búsqueda añade un viaje de ida y vuelta. La documentación no especifica exactamente qué incluye ese intercambio. Para Claude Code, la documentación MCP también describe una diferencia en la notificación de errores: sin la búsqueda de herramientas, Claude Code no informa al modelo de los fallos de conexión de los servidores. Cuando la búsqueda está habilitada, el modelo recibe información sobre qué servidor no pudo conectarse y cuál fue el error.

Claude Code no impone un límite fijo al número de herramientas de un solo servidor. El límite práctico es el presupuesto de la ventana de contexto de la sesión concreta.

Configurar herramientas es una de las tareas que intervienen en la gestión del contexto de un agente de IA.

Cuándo está desactivada de forma predeterminada la búsqueda de herramientas#

El mecanismo está habilitado de forma predeterminada, pero su funcionamiento depende del modelo, el host de la API y la plataforma.

Modelo. La búsqueda de herramientas requiere un modelo compatible con bloques tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 o posterior. Con modelos anteriores, Claude Code carga por adelantado las definiciones de las herramientas.

Host de la API. Claude Code desactiva la búsqueda de herramientas cuando la variable ANTHROPIC_BASE_URL apunta a un host de terceros: la mayoría de los proxies no transmiten los bloques tool_reference especiales. Esto se aplica cuando te conectas a Claude mediante tu propia pasarela o servidor proxy, en lugar de hacerlo directamente a través de la dirección de Anthropic. La causa de la desactivación es una ANTHROPIC_BASE_URL no estándar; la forma de pagar la suscripción no la provoca por sí misma. Puedes configurar explícitamente ENABLE_TOOL_SEARCH para anular este comportamiento. Si el proxy no admite bloques tool_reference, forzar la activación del mecanismo provoca un error de solicitud. En este caso, no se recurrirá a cargar las definiciones por adelantado.

Plataforma de implementación. La búsqueda de herramientas no funciona en las implementaciones de Microsoft Foundry alojadas en Azure: el servidor rechaza la solicitud y ENABLE_TOOL_SEARCH no puede anularlo. En Google Cloud Agent Platform, antes de la versión 2.1.221 de Claude Code, el mecanismo estaba desactivado para todos los modelos, salvo que se configurara explícitamente ENABLE_TOOL_SEARCH=true. A partir de esa versión, se habilita de forma predeterminada para Opus/Sonnet/Haiku 4.5 y posteriores. Para los modelos anteriores en esa plataforma, Claude Code sigue cargando todas las herramientas por adelantado porque la infraestructura de sus servidores rechaza el encabezado interno necesario.

La variable ENABLE_TOOL_SEARCH tiene cinco valores posibles:

• sin configurar: el comportamiento estándar, con las excepciones indicadas arriba;
• true: el mecanismo se habilita en los modelos que lo admiten, salvo en dos casos: Azure Foundry y los modelos antiguos de Agent Platform; las solicitudes enviadas a través de un proxy sin compatibilidad con bloques tool_reference fallarán;
• auto: Claude Code carga las herramientas por adelantado mientras sus definiciones combinadas ocupen menos del 10% de la ventana de contexto, y pasa a la carga diferida cuando se alcanza ese umbral;
• auto:N: el mismo principio, con un umbral porcentual especificado manualmente;
• false: el mecanismo se desactiva por completo y todas las herramientas se cargan por adelantado.

También está la variable CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: si está configurada, la búsqueda de herramientas permanece desactivada y la configuración de ENABLE_TOOL_SEARCH por parte del usuario no cambia esto. La excepción se da cuando la organización mantiene habilitada la búsqueda de herramientas mediante la configuración administrada, disponible desde la versión 2.1.227 de Claude Code.

Qué hace alwaysLoad y cómo afecta al contexto y al inicio#

El campo alwaysLoad: true en la configuración de un servidor está disponible para todos los tipos de servidor. Con él, todas las herramientas de ese servidor se cargan en el contexto al inicio, con independencia de la configuración de ENABLE_TOOL_SEARCH. El agente no necesita buscarlas antes de usarlas.

Cargar siempre las herramientas tiene dos consecuencias. Cada herramienta cargada por adelantado ocupa parte del contexto que, de otro modo, estaría disponible para la tarea en sí. Además, el inicio de la sesión espera a que se conecte este servidor, dentro del tiempo de espera estándar de cinco segundos.

La excepción es un servidor remoto con una entrada válida en la caché: proporciona las herramientas desde la caché sin conectarse y no retrasa el inicio. La caché de descubrimiento está desactivada de forma predeterminada, salvo que ya se haya habilitado para la cuenta durante el despliegue gradual de la función. También puedes habilitarla explícitamente mediante MCP_DISCOVERY_CACHE=1. La excepción de inicio rápido se aplica cuando la caché está activa y contiene una entrada válida. Las herramientas con alwaysLoad siguen ocupando contexto de forma permanente, independientemente de si el agente las habría necesitado al trabajar mediante la búsqueda.

Para quienes escriben sus propios servidores MCP: las instrucciones del servidor ayudan a Claude a entender cuándo buscar sus herramientas, de forma parecida a Skills. De forma predeterminada, Claude Code trunca a 2048 caracteres la descripción de cada herramienta y las instrucciones de cada servidor, así que coloca los detalles esenciales al principio.

Elegir cómo ampliar Claude Code depende de algo más que del número de servidores MCP conectados. Las guías Claude Code: cuántas extensiones mantener activas a la vez y Qué elegir en Claude Code: Skills, Subagents, MCP o Plugins examinan Skills, Subagents, MCP y Plugins para distintas tareas. Para configurar paso a paso servidores MCP concretos, consulta Servidores MCP para Claude Code: combinaciones listas para usar.

Qué hacer a continuación#

Para un conjunto de menos de aproximadamente 10 herramientas cuyas definiciones caben sin dificultad en el contexto, la documentación de Agent SDK señala que normalmente es más rápido cargarlas todas de una vez. Sin embargo, en el comportamiento predeterminado de Claude Code, cuando la variable no está configurada y no se aplica ninguna de las limitaciones anteriores, la búsqueda de herramientas está habilitada y la carga de herramientas MCP se difiere hasta que se buscan, excepto en los servidores con alwaysLoad.

En este caso, puedes configurar explícitamente ENABLE_TOOL_SEARCH=auto: las definiciones se cargarán por adelantado mientras su volumen combinado sea inferior al 10% de la ventana de contexto, y la búsqueda se habilitará al alcanzar el umbral. Otra opción es ENABLE_TOOL_SEARCH=false si sabes que el conjunto no va a crecer. En ese caso, Claude Code dejará de informar al modelo de los fallos de conexión de los servidores, tal como se describe arriba.

En los demás casos, vuelve a comprobar las condiciones de funcionamiento cuando cambie el entorno:

• cambia a Sonnet/Haiku/Opus 4.5 o posterior si la sesión utiliza un modelo anterior;
• si la conexión utiliza una ANTHROPIC_BASE_URL no estándar, configura explícitamente ENABLE_TOOL_SEARCH=true solo cuando el proxy transmita los bloques tool_reference;
• asegúrate de que la plataforma de implementación no esté entre las excepciones: Azure Foundry o los modelos antiguos de Google Cloud Agent Platform.

Si se cumplen las condiciones y la configuración no bloquea la búsqueda, puedes conectar los servidores MCP que necesites. Utiliza alwaysLoad solo para aquellos cuyos herramientas sean necesarias en cada turno de la sesión; deja que los demás se carguen mediante la búsqueda.

Si necesitas acceder a modelos de IA a través de Ailoot, echa un vistazo a Ailoot.