🔍 MCP 도구 67,000 토큰 문제, Tool Search Tool로 끝냈다

MCP 서버 7개 연결한 유저가 GitHub에 올린 이슈가 있어요. 도구 설명만으로 67,000 토큰이 날아갔다는 내용이었는데, Anthropic에서 가장 많이 요청받은 기능이었다고 해요.

이번에 Claude Code에 Tool Search Tool이 정식 롤아웃되면서 이 lazy loading 문제가 해결됐어요. 사실 저도 tool registry 기반으로 tool calling 을 자체적으로 하던 입장에서 이번 클로드 코드 업데이트는 반가웠습니다.

1️⃣ 작동 방식은 단순해요

Claude Code가 MCP 도구 설명이 컨텍스트의 10%를 넘는지 자동으로 체크합니다.

• 10% 초과 시: 도구를 미리 로드하지 않고, 필요할 때 검색해서 가져옴 • 10% 이하 시: 기존과 완전히 동일하게 동작 • 사용자 입장에서 별도 설정 필요 없음

2️⃣ 두 가지 검색 방식 지원

상황에 따라 Regex와 BM25 중 선택할 수 있어요.

• Regex(tool_search_tool_regex): get_.*_data 같은 패턴 매칭. 도구 네이밍 규칙이 명확할 때 유용 • BM25(tool_search_tool_bm25): 자연어 쿼리 지원. “슬랙 메시지 보내는 도구” 같은 검색 가능 • 검색당 3~5개 도구만 로드, 최대 10,000개 도구 카탈로그 지원

3️⃣ API 사용자는 Custom Search도 가능

임베딩 기반 시맨틱 검색 같은 고급 로직을 직접 구현할 수 있어요.

• 커스텀 도구에서 tool_reference 블록을 반환하면 됨 • 반환된 도구명에 해당하는 정의가 tools 파라미터에 defer_loading: true로 있어야 함 • Anthropic Cookbook에 임베딩 활용 예제도 공개되어 있음

4️⃣ MCP 서버 개발자라면 체크할 것

Tool Search가 활성화되면 “server instructions” 필드가 중요해져요.

• Claude가 언제 해당 서버의 도구를 검색해야 하는지 판단하는 기준이 됨 • Skills 설명하듯이 “이 서버는 ~할 때 사용” 형태로 작성하면 검색 정확도 올라감 • 도구 이름과 description에 시맨틱 키워드 잘 넣어두는 게 핵심

한 가지 참고할 점은, Anthropic이 MCP 도구끼리 코드로 조합하는 programmatic tool calling도 실험했는데, 컨텍스트 절약이 더 급해서 Tool Search를 먼저 출시했다고 해요. 이 부분은 계속 개발 중이라고 하니 후속 업데이트 기대해봐도 될 것 같아요.