Поиск инструментов в Claude Code: как агент находит MCP-инструмент

Если к Claude Code подключено несколько MCP-серверов, поиск инструментов позволяет загружать подходящие средства по мере необходимости, а не помещать все их описания в контекст заранее. При запуске агент получает названия отложенных инструментов и инструкции серверов, после чего ищет нужные варианты в каталоге. Это удобно при большом наборе инструментов: согласно документации Anthropic, точность выбора снижается, когда одновременно загружено более 30–50 инструментов. Это общий ориентир, а не измерение вашей сессии. Поиск инструментов включён по умолчанию для поддерживаемых моделей, однако его могут отключить платформа, прокси или параметры конфигурации.

Документация Ailoot: API, ключи и подключение.

Как MCP-инструменты расходуют контекст Claude Code?#

Каждый подключённый MCP-сервер расширяет перечень инструментов, которые агент может вызвать. Если поиск отключён, описания инструментов — их имена, пояснения и схемы параметров — заранее помещаются в контекст. При старте сессии серверы подключаются в фоновом режиме. Если агенту нужен инструмент сервера, подключение которого ещё не завершилось, Claude Code ожидает его с помощью служебного инструмента WaitForMcpServers. Объём инструментов и токенов, добавляемых конкретным сервером, можно оценить отдельно для каждого подключения.

В официальной документации Anthropic приведены два приблизительных ориентира без описания методики подсчёта:

• 50 инструментов могут занимать от 10 до 20 тысяч токенов контекста;
• если одновременно загружено больше 30–50 инструментов, точность выбора нужного инструмента снижается.

Как проверить по настройкам, активен ли поиск инструментов#

Чтобы определить, должен ли поиск работать в текущей сессии, проверьте следующие условия:

• какая модель используется — Sonnet, Haiku или Opus 4.5 либо более новая версия поддерживает механизм; более ранние модели — нет;
• установлена ли переменная ANTHROPIC_BASE_URL для нестандартного хоста: в таком случае механизм по умолчанию отключён, пока его явно не активируют через ENABLE_TOOL_SEARCH;
• какое значение задано для ENABLE_TOOL_SEARCH: false полностью выключает механизм, а auto и auto:N включают его только после достижения порога объёма описаний;
• задана ли CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: без управляемых настроек организации эта переменная сохраняет поиск выключенным, даже если пользователь установил ENABLE_TOOL_SEARCH;
• запрещён ли инструмент ToolSearch в параметре permissions.deny настроек: такой запрет не позволяет выполнять поиск;
• какая платформа развёртывания используется: поиск недоступен в Azure-развёртываниях Microsoft Foundry, а его работа в Google Cloud Agent Platform зависит от версии Claude Code и модели.

Эти настройки помогают оценить состояние механизма, но не показывают его непосредственно внутри сессии. В разделах документации о MCP и поиске инструментов в Agent SDK не описан прямой индикатор «поиск инструментов: вкл./выкл.» в интерфейсе. При этом отсутствие такого указания в этих двух документах само по себе не доказывает, что индикатора нигде нет.

Переменную можно установить перед запуском сессии, например: ENABLE_TOOL_SEARCH=auto:15 claude. Чтобы всегда загружать инструменты определённого сервера, добавьте в его конфигурацию параметр alwaysLoad: true. Он предусмотрен для серверов всех типов; подробности и ограничения приведены в разделе об alwaysLoad ниже.

Принцип работы поиска инструментов#

Когда поиск включён, при старте сессии в контекст попадают только имена отложенных инструментов и инструкции сервера (server instructions) — пояснение, для каких задач он предназначен. Если для выполнения задачи нужна возможность, которой в контексте пока нет, агент самостоятельно ищет подходящий инструмент в каталоге.

В документации Agent SDK механизм описан подробнее: по умолчанию один поиск загружает из каталога до пяти наиболее подходящих инструментов. Они остаются доступными на последующих шагах сессии, пока SDK не сожмёт сообщения, в которых агент обнаружил эти инструменты (в документации это называется compacts). После сжатия найденные инструменты могут исчезнуть из контекста; если они понадобятся снова, агент выполнит новый поиск. Каталог вмещает до 10 000 инструментов. В документации MCP для Claude Code именно эти числа не указаны, однако там описан тот же подход с отложенной загрузкой.

Согласно документации Agent SDK, каждый поиск добавляет один дополнительный цикл обмена (round-trip). Документация не уточняет, что именно входит в этот цикл. Документация MCP для Claude Code также описывает разницу в сообщениях об ошибках: без поиска инструментов Claude Code не передаёт модели сведения о неудачных подключениях серверов. При включённом поиске модель узнаёт, какой сервер не подключился и какую ошибку вернул.

Claude Code не задаёт фиксированного ограничения на число инструментов одного сервера. На практике их количество ограничено бюджетом контекстного окна конкретной сессии.

Управление инструментами — одна из задач при работе с контекстом ИИ-агента.

Случаи, когда поиск отключается по умолчанию#

По умолчанию механизм активен, но его доступность определяется моделью, API-хостом и платформой развёртывания.

Модель. Для поиска нужны модели, поддерживающие блоки tool_reference: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 и более поздние версии. Для более старых моделей Claude Code заранее загружает описания всех инструментов.

API-хост. Claude Code отключает поиск, если переменная ANTHROPIC_BASE_URL указывает на сторонний хост: большинство прокси не передают специальные блоки tool_reference. Это относится к случаям, когда Claude подключается через собственный шлюз или прокси-сервер, а не напрямую по адресу Anthropic. Причина отключения — нестандартное значение ANTHROPIC_BASE_URL; выбранный способ оплаты подписки сам по себе на это не влияет. Чтобы изменить поведение, можно явно задать ENABLE_TOOL_SEARCH. Если прокси не поддерживает блоки tool_reference, принудительная активация приведёт к ошибке запроса. В этом случае возврата к предварительной загрузке не произойдёт.

Платформа развёртывания. Поиск инструментов не работает в развёртываниях Microsoft Foundry на Azure: сервер отклонит запрос, и параметр ENABLE_TOOL_SEARCH этого не изменит. В Google Cloud Agent Platform до версии Claude Code 2.1.221 поиск был выключен для всех моделей, если явно не задавали ENABLE_TOOL_SEARCH=true. Начиная с версии 2.1.221 он включён по умолчанию для Opus, Sonnet и Haiku 4.5 и новее. Для более ранних моделей Claude Code продолжает заранее загружать все инструменты, так как серверная инфраструктура платформы отклоняет обязательный служебный заголовок.

Для ENABLE_TOOL_SEARCH предусмотрено пять вариантов:

• переменная не задана — действует стандартное поведение с исключениями, описанными выше;
• true — механизм активен на поддерживаемых моделях, за исключением Azure Foundry и старых моделей Agent Platform; запросы через прокси без поддержки блоков tool_reference завершатся ошибкой;
• auto — Claude Code заранее загружает инструменты, пока совокупный объём их описаний меньше 10% контекстного окна, а после достижения порога переключается на отложенную загрузку;
• auto:N — применяется тот же принцип, но порог в процентах задаётся вручную;
• false — механизм полностью отключён, все инструменты загружаются заранее.

Также существует переменная CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS. Если она установлена, поиск остаётся выключенным, и пользователь не может изменить это установкой ENABLE_TOOL_SEARCH. Исключение — организация активировала поиск через управляемые (managed) настройки, доступные с версии Claude Code 2.1.227.

Как параметр alwaysLoad влияет на контекст и запуск#

Параметр alwaysLoad: true в конфигурации сервера доступен для серверов любого типа. С ним все инструменты этого сервера включаются в контекст при старте вне зависимости от значения ENABLE_TOOL_SEARCH. Перед вызовом агенту не нужно искать их в каталоге.

Постоянная загрузка имеет два последствия. Каждый заранее добавленный инструмент использует часть контекста, которая могла бы остаться для самой задачи. Кроме того, запуск сессии ожидает подключения этого сервера в пределах стандартного таймаута в пять секунд.

Есть исключение для удалённого сервера с актуальной записью в кэше: его инструменты берутся из кэша без подключения, поэтому запуск не задерживается. Кэш обнаружения (discovery cache) по умолчанию выключен, если его не активировали для аккаунта в ходе постепенного запуска функции. Его также можно включить параметром MCP_DISCOVERY_CACHE=1. Быстрый запуск возможен только при активном кэше с действительной записью. При этом инструменты, помеченные alwaysLoad, постоянно занимают контекст, даже если агенту не понадобилось бы находить их через поиск.

Если вы разрабатываете собственный MCP-сервер, инструкции сервера (server instructions) помогают Claude определить, когда искать его инструменты, подобно тому, как это делают навыки (Skills). По умолчанию Claude Code ограничивает описания каждого инструмента и инструкции каждого сервера 2048 символами. Поэтому важные сведения следует размещать в начале.

Расширять Claude Code можно разными способами, и выбор зависит не только от количества MCP-серверов. Сравнение Skills, Subagents, MCP и Plugins для разных задач приведено в материалах Claude Code: сколько расширений держать одновременно и Что выбрать в Claude Code: Skills, Subagents, MCP или Plugins. Пошаговая настройка конкретных MCP-серверов рассмотрена в статье MCP-серверы для Claude Code: готовые связки.

Следующие шаги#

Для набора примерно из десяти инструментов или меньшего размера, описания которых без затруднений помещаются в контекст, документация Agent SDK отмечает, что загрузка всех инструментов сразу обычно быстрее. При этом в Claude Code поиск по умолчанию включён, если переменная не задана и не действуют перечисленные выше ограничения; загрузка MCP-инструментов откладывается до поиска, кроме серверов с параметром alwaysLoad.

Можно явно задать ENABLE_TOOL_SEARCH=auto: тогда определения инструментов загружаются заранее, пока их общий объём составляет меньше 10% контекстного окна, а при достижении этого порога активируется поиск. Другой вариант — установить ENABLE_TOOL_SEARCH=false, если вы уверены, что набор инструментов не будет расширяться. Тогда Claude Code перестанет сообщать модели о сбоях подключения серверов, как описано выше.

В остальных случаях после изменения окружения повторно проверьте условия работы:

• если используется более старая модель, переключитесь на Sonnet, Haiku или Opus 4.5 либо новее;
• при подключении через нестандартный ANTHROPIC_BASE_URL явно установите ENABLE_TOOL_SEARCH=true, только если ваш прокси передаёт блоки tool_reference;
• проверьте, что платформа развёртывания не относится к исключениям: Azure Foundry или старые модели Google Cloud Agent Platform.

Если условия соблюдены и настройки не запрещают поиск, подключите необходимые MCP-серверы. Устанавливайте alwaysLoad только для серверов, инструменты которых нужны на каждом шаге сессии; остальные можно загружать через поиск.

Если вам нужен доступ к нейросетям через Ailoot, ознакомьтесь с Ailoot.