Claude Code의 도구 검색: 에이전트가 필요한 MCP 도구를 찾는 방법

Claude Code에 여러 MCP 서버를 연결한 경우, 도구 검색을 사용하면 모든 정의를 미리 로드하지 않고 필요한 도구를 요청 시 로드할 수 있습니다. 시작할 때 에이전트는 지연 로드되는 도구의 이름과 서버의 지침을 받은 다음, 필요한 항목을 카탈로그에서 검색합니다. 이를 통해 많은 도구를 다룰 수 있습니다. Anthropic 문서에 따르면 한 번에 30-50개가 넘는 도구를 로드하면 선택 정확도가 떨어집니다. 이는 일반적인 안내이며 사용자의 세션을 측정한 결과는 아닙니다. 모델이 지원하는 경우 도구 검색은 기본적으로 활성화되어 있지만, 플랫폼, 프록시 또는 설정에 의해 비활성화될 수 있습니다.

Ailoot 문서: API, 키 및 설정.

도구 검색이 없을 때 컨텍스트에 발생하는 일#

연결된 각 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를 설정했더라도 도구 검색이 꺼진 상태로 유지됩니다.
• 설정의 permissions.deny에서 ToolSearch 도구가 차단되어 있는지 — 이러한 제한은 검색을 비활성화합니다.
• 사용하는 플랫폼 — Azure의 Microsoft Foundry 배포에서는 이 메커니즘을 사용할 수 없습니다. Google Cloud Agent Platform에서는 Claude Code 버전과 모델에 따라 동작이 달라집니다.

이 확인을 통해 설정에서 상태를 평가할 수는 있지만, 세션 내부에서 직접 관찰할 수는 없습니다. Agent SDK 문서의 MCP 섹션과 도구 검색 섹션에는 인터페이스에 “도구 검색: 켜짐/꺼짐”을 표시하는 직접적인 표시기가 설명되어 있지 않습니다. 이 두 문서에 언급이 없다고 해서 어디에도 그런 표시기가 존재하지 않는다는 뜻은 아닙니다.

세션을 시작하기 전에 변수를 설정할 수 있습니다. 예: ENABLE_TOOL_SEARCH=auto:15 claude. 특정 서버의 도구를 항상 로드하려면 해당 서버 설정에서 alwaysLoad: true 필드를 사용하세요. 모든 서버 유형에서 사용할 수 있으며, 조건과 제한 사항은 아래 alwaysLoad 섹션에 설명되어 있습니다.

도구 검색의 작동 방식#

도구 검색이 활성화되면 세션 시작 시 지연 로드되는 도구의 이름과 서버 지침만 컨텍스트에 로드됩니다. 서버 지침은 해당 서버가 어떤 작업에 유용한지 설명합니다. 작업에 아직 컨텍스트에 없는 기능이 필요하면 에이전트가 적절한 도구를 카탈로그에서 직접 검색합니다.

Agent SDK 문서에는 검색 메커니즘이 더 자세히 설명되어 있습니다. 기본적으로 한 번 검색하면 카탈로그에서 관련성이 가장 높은 도구를 최대 5개 로드합니다. 에이전트가 해당 도구를 찾은 메시지를 SDK가 압축할 때까지 세션의 후속 턴에서도 계속 사용할 수 있습니다. 압축 후에는 이전에 발견한 도구가 컨텍스트에서 빠질 수 있으며, 다음에 필요할 때 에이전트가 다시 검색합니다. 카탈로그는 최대 10 000개의 도구를 지원합니다. Claude Code 자체의 MCP 문서에는 이 구체적인 수치가 없지만 지연 로드라는 동일한 원칙을 설명합니다.

Agent SDK 문서에 따르면 검색할 때마다 왕복이 한 번 추가됩니다. 문서에는 그 왕복에 정확히 무엇이 포함되는지 명시되어 있지 않습니다. Claude Code의 MCP 문서에는 오류 보고 방식의 차이도 설명되어 있습니다. 도구 검색이 꺼져 있으면 Claude Code는 서버 연결 실패를 모델에 알리지 않습니다. 검색이 켜져 있으면 어느 서버의 연결이 실패했는지와 오류가 무엇이었는지에 관한 정보를 모델이 받습니다.

Claude Code는 단일 서버에서 가져올 수 있는 도구 수에 고정된 제한을 두지 않습니다. 실질적인 한도는 해당 세션의 컨텍스트 창 예산입니다.

도구 구성은 AI 에이전트의 컨텍스트 관리에 포함되는 작업 중 하나입니다.

도구 검색이 기본적으로 비활성화되는 경우#

이 메커니즘은 기본적으로 활성화되어 있지만, 작동 여부는 모델, API 호스트 및 플랫폼에 따라 달라집니다.

모델. 도구 검색에는 tool_reference 블록을 지원하는 모델이 필요합니다. Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 또는 이후 버전이 이에 해당합니다. 이전 모델의 경우 Claude Code는 도구 정의를 미리 로드합니다.

API 호스트. ANTHROPIC_BASE_URL 변수가 타사 호스트를 가리키면 Claude Code는 도구 검색을 비활성화합니다. 대부분의 프록시가 특수 tool_reference 블록을 전달하지 않기 때문입니다. 이는 Anthropic 주소로 직접 연결하는 대신 자체 게이트웨이나 프록시 서버를 통해 Claude에 연결할 때 적용됩니다. 비활성화되는 이유는 표준이 아닌 ANTHROPIC_BASE_URL이며, 구독 결제 방식 자체가 원인은 아닙니다. 이 동작을 재정의하려면 ENABLE_TOOL_SEARCH를 명시적으로 설정할 수 있습니다. 프록시 자체가 tool_reference 블록을 지원하지 않으면 메커니즘을 강제로 켰을 때 요청 오류가 발생합니다. 이 경우 정의를 미리 로드하는 방식으로 전환되지 않습니다.

배포 플랫폼. Azure에서 호스팅되는 Microsoft Foundry 배포에서는 도구 검색이 작동하지 않습니다. 서버가 요청을 거부하며 ENABLE_TOOL_SEARCH로 이 제한을 재정의할 수 없습니다. Google Cloud Agent Platform에서는 Claude Code 버전 2.1.221 이전에 ENABLE_TOOL_SEARCH=true를 명시적으로 설정하지 않으면 모든 모델에서 메커니즘이 꺼져 있었습니다. 해당 버전부터는 Opus/Sonnet/Haiku 4.5 이상에서 기본적으로 활성화됩니다. 이 플랫폼의 이전 모델에서는 서버 인프라가 필요한 내부 헤더를 거부하기 때문에 Claude Code가 여전히 모든 도구를 미리 로드합니다.

ENABLE_TOOL_SEARCH 변수에는 다음 다섯 가지 설정이 있습니다.

• 설정되지 않음 — 위에 나열된 예외가 적용되는 표준 동작입니다.
• true — 지원 모델에서 메커니즘을 활성화합니다. 단, Azure Foundry와 이전 Agent Platform 모델은 예외입니다. tool_reference 블록을 지원하지 않는 프록시를 통해 보낸 요청은 실패합니다.
• auto — 도구 정의의 총량이 컨텍스트 창의 10% 미만인 동안 Claude Code는 도구를 미리 로드하고, 해당 임계값에 도달하면 지연 로드로 전환합니다.
• auto:N — 같은 원칙을 적용하되 백분율 임계값을 직접 지정합니다.
• false — 메커니즘을 완전히 비활성화하고 모든 도구를 미리 로드합니다.

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 변수도 있습니다. 이 변수가 설정되면 도구 검색은 계속 꺼져 있으며 사용자가 ENABLE_TOOL_SEARCH를 설정해도 바뀌지 않습니다. 예외는 Claude Code 버전 2.1.227부터 사용할 수 있는 관리형 설정을 통해 조직이 도구 검색을 활성화해 둔 경우입니다.

alwaysLoad의 기능과 컨텍스트 및 시작 시간에 미치는 영향#

서버 설정의 alwaysLoad: true 필드는 모든 서버 유형에서 사용할 수 있습니다. 이 설정을 사용하면 ENABLE_TOOL_SEARCH의 설정과 관계없이 해당 서버의 모든 도구가 시작 시 컨텍스트에 로드됩니다. 에이전트는 도구를 사용하기 전에 검색할 필요가 없습니다.

도구를 항상 로드하면 두 가지 결과가 발생합니다. 미리 로드되는 각 도구는 작업 자체에 사용할 수 있었을 컨텍스트의 일부를 차지합니다. 또한 세션을 시작할 때 표준 5초 시간 제한 안에서 해당 서버의 연결이 완료될 때까지 기다립니다.

유효한 캐시 항목이 있는 원격 서버는 예외입니다. 연결하지 않고 캐시에서 도구를 제공하므로 시작이 지연되지 않습니다. 기능의 점진적 출시 과정에서 해당 계정에 이미 활성화된 경우가 아니면 검색 캐시는 기본적으로 꺼져 있습니다. MCP_DISCOVERY_CACHE=1을 통해 명시적으로 활성화할 수도 있습니다. 빠른 시작 예외는 캐시가 활성 상태이고 유효한 항목을 포함하는 경우에 적용됩니다. alwaysLoad가 지정된 도구는 에이전트가 검색을 통해 작업할 때 필요했는지와 관계없이 컨텍스트를 계속 차지합니다.

자체 MCP 서버를 작성하는 경우 참고하세요. 서버 지침은 Skills와 마찬가지로 Claude가 해당 서버의 도구를 언제 검색해야 하는지 이해하는 데 도움이 됩니다. 기본적으로 Claude Code는 각 도구의 설명과 각 서버의 지침을 2048자로 자르므로 중요한 세부 사항을 앞부분에 배치하세요.

Claude Code를 확장하는 방법은 연결된 MCP 서버의 수만으로 결정되지 않습니다. Claude Code: 한 번에 몇 개의 확장 기능을 유지할 것인가와 Claude Code에서 무엇을 선택할까: Skills, Subagents, MCP 또는 Plugins 가이드에서는 여러 작업에 맞춰 Skills, Subagents, MCP 및 Plugins를 살펴봅니다. 특정 MCP 서버의 설정을 단계별로 알아보려면 Claude Code용 MCP 서버: 바로 사용할 수 있는 조합을 참고하세요.

다음 단계#

정의가 컨텍스트에 무리 없이 들어가는 약 10개 미만의 도구 집합이라면, Agent SDK 문서에서는 보통 도구를 한 번에 모두 로드하는 편이 더 빠르다고 설명합니다. 하지만 Claude Code의 기본 동작에서는 변수가 설정되지 않았고 위의 제한 사항이 적용되지 않는 경우 도구 검색이 활성화되며, alwaysLoad가 지정된 서버를 제외한 MCP 도구는 검색할 때까지 지연 로드됩니다.

이 경우 ENABLE_TOOL_SEARCH=auto를 명시적으로 설정할 수 있습니다. 정의의 총량이 컨텍스트 창의 10% 미만인 동안에는 미리 로드되고, 임계값에 도달하면 검색이 활성화됩니다. 집합이 늘어나지 않을 것을 알고 있다면 ENABLE_TOOL_SEARCH=false를 사용할 수도 있습니다. 이 경우 앞서 설명한 대로 Claude Code는 서버 연결 실패를 모델에 알리지 않습니다.

그 밖의 경우에는 환경이 바뀔 때 작동 조건을 다시 확인하세요.

• 세션에서 이전 모델을 사용 중이라면 Sonnet/Haiku/Opus 4.5 이상으로 전환합니다.
• 연결에 표준이 아닌 ANTHROPIC_BASE_URL을 사용하는 경우 프록시 자체가 tool_reference 블록을 전달할 때만 ENABLE_TOOL_SEARCH=true를 명시적으로 설정합니다.
• 배포 플랫폼이 예외 목록에 없는지 확인합니다. 예외는 Azure Foundry 또는 Google Cloud Agent Platform의 이전 모델입니다.

조건이 충족되고 설정에서 검색이 차단되지 않았다면 필요한 MCP 서버를 연결할 수 있습니다. 세션의 모든 턴에서 도구가 필요한 서버에만 alwaysLoad를 사용하고 나머지는 검색을 통해 로드되도록 하세요.

Ailoot를 통해 AI 모델에 접근해야 한다면 Ailoot를 살펴보세요.