# Поиск инструментов в Claude Code: как агент находит MCP-инструмент > Узнайте, как работает поиск инструментов в Claude Code: что попадает в контекст при запуске, при каких условиях поиск отключается и как настроить ENABLE_TOOL_SEARCH и alwaysLoad. Source: https://ailoot.ai/blog/ru/claude-code-tool-search-mcp-limit/ Canonical: https://ailoot.ai/blog/ru/claude-code-tool-search-mcp-limit/ Language: ru Publisher: Ailoot (https://ailoot.ai/) Translation: guide-055 Revision: sha256-3587876c3c4b2148479854a4b7e4dc9394d1f35896404ebd904098c9a3a8ca6e Если к Claude Code подключено несколько MCP-серверов, поиск инструментов позволяет загружать подходящие средства по мере необходимости, а не помещать все их описания в контекст заранее. При запуске агент получает названия отложенных инструментов и инструкции серверов, после чего ищет нужные варианты в каталоге. Это удобно при большом наборе инструментов: согласно документации Anthropic, точность выбора снижается, когда одновременно загружено более 30–50 инструментов. Это общий ориентир, а не измерение вашей сессии. Поиск инструментов включён по умолчанию для поддерживаемых моделей, однако его могут отключить платформа, прокси или параметры конфигурации. [Документация Ailoot: API, ключи и подключение](https://ailoot.ai/docs/). ## Как 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: сколько расширений держать одновременно](https://ailoot.ai/blog/ru/claude-code-skills-subagents-mcp-plugins/) и [Что выбрать в Claude Code: Skills, Subagents, MCP или Plugins](https://ailoot.ai/blog/ru/skills-subagents-mcp-plugins-claude-code/). Пошаговая настройка конкретных MCP-серверов рассмотрена в статье [MCP-серверы для Claude Code: готовые связки](https://ailoot.ai/blog/ru/mcp-servers-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` только для серверов, инструменты которых нужны на каждом шаге сессии; остальные можно загружать через поиск.
### Источники - [Поиск инструментов MCP в Claude Code — официальная документация Anthropic](https://code.claude.com/docs/en/mcp.md) - [Поиск инструментов в Agent SDK — официальная документация Anthropic](https://code.claude.com/docs/en/agent-sdk/tool-search.md)
Если вам нужен доступ к нейросетям через Ailoot, ознакомьтесь с [Ailoot](https://ailoot.ai/). ## Вопросы и ответы ### Почему поиск инструментов через прокси не работает даже после включения? Сторонний API-хост должен поддерживать блоки tool_reference. Принудительное включение ENABLE_TOOL_SEARCH не добавляет поддержку: несовместимый прокси может отклонить запрос вместо перехода к предварительной загрузке. ### Когда включать alwaysLoad для MCP-сервера? Когда его инструменты нужны на каждом ходу. Все определения займут стартовый контекст, а запуск может ждать подключения, если не применяется действующая запись кеша обнаружения. ## Ailoot · Компания и портфель её проектов Ailoot опирается на накопленный опыт работы, большую клиентскую базу, стабильный сервис и постоянный контроль KPI. Компания и портфель её проектов: миллионы клиентов; продажи на миллиарды ежемесячно. Этот опыт Ailoot использует для API-доступа к нейросетям в продуктах клиентов, агентах, приложениях и автоматизациях.