Claude Code MCP Tool Search: 토큰 85% 절약하는 동적 도구 로딩 완벽 가이드

“MCP 서버 4개 연결했더니 토큰이 67,000개나 사라졌어요.”

Reddit의 한 개발자가 올린 글입니다. Claude Code를 쓰는 개발자라면 한 번쯤 겪어봤을 상황이죠.

MCP(Model Context Protocol)는 Claude Code의 핵심 기능입니다. GitHub, Docker, 데이터베이스 등 외부 도구를 연결해서 AI의 능력을 확장할 수 있거든요. 문제는 이 도구들이 **컨텍스트 윈도우를 잡아먹는다**는 겁니다.

오늘은 이 문제를 해결하는 **MCP Tool Search** 기능을 파헤쳐보겠습니다.

문제: MCP가 컨텍스트를 잡아먹는다

숫자로 보는 현실

Claude Code에 MCP 서버를 연결하면 어떤 일이 벌어질까요?

Docker MCP 서버 **하나**만 연결해도 125,000 토큰이 사라집니다. Claude Code의 컨텍스트 윈도우가 200K 토큰이라고 치면, 서버 하나에 **62.5%**가 날아가는 거예요.

왜 이런 일이 생기나?

기존 방식에서는 MCP 서버를 연결하면 **모든 도구 정의**가 컨텍스트에 사전 로드됩니다:

• 도구 이름
• 설명
• JSON 스키마
• 파라미터, 타입, 제약 조건

50개, 100개, 135개 도구에 이걸 곱하면? 토큰이 순식간에 증발합니다.

더 큰 문제는 **성능 저하**입니다. 도구가 너무 많으면:

• 도구 선택 정확도 하락
• 파라미터 환각(hallucination) 증가
• 주의(attention) 분산
• 응답 지연 증가

해결책: MCP Tool Search

2026년 1월 14일, Anthropic의 Thariq Shihipar가 트위터에서 발표했습니다:

작동 원리: 5단계 프로세스

MCP Tool Search는 **지연 로딩(Lazy Loading)** 패턴을 도구에 적용한 것입니다.

핵심은 **”필요할 때만 로드”**입니다. 모든 도구 정의를 미리 올리는 대신, Claude가 실제로 필요한 도구만 그때그때 검색해서 가져옵니다.

성능 개선: 숫자로 증명

Anthopic 엔지니어링 팀의 내부 테스트 결과, 대규모 도구 라이브러리에서 정확도가 크게 향상되었습니다.

설정 방법: 3가지 옵션

1. 기본값 (자동 모드)

Claude Code **2.1.7 버전부터 기본 활성화**되어 있습니다. 별도 설정 없이도 작동합니다.

2. 환경 변수로 제어

# 기본값: 컨텍스트 10% 초과 시 활성화
ENABLE_TOOL_SEARCH=auto claude

# 커스텀 임계값: 5% 초과 시 활성화 (더 적극적)
ENABLE_TOOL_SEARCH=auto:5 claude

# 항상 활성화 (도구 수 상관없이)
ENABLE_TOOL_SEARCH=true claude

# 비활성화 (기존 방식으로 전체 로드)
ENABLE_TOOL_SEARCH=false claude

3. settings.json 설정

영구적으로 설정하려면:

{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5"
  }
}

옵션 정리

주의사항: 모델 호환성

MCP Tool Search는 **`tool_reference` 블록을 지원하는 모델**에서만 작동합니다.

Haiku를 사용 중이라면 Tool Search가 작동하지 않으니 주의하세요.

MCP 서버 개발자를 위한 팁

Tool Search가 활성화되면 **서버 명령어(server instructions)** 필드의 중요성이 커집니다. Claude가 도구를 검색할 때 이 설명을 참고하거든요.

GitHub 관련 모든 작업 처리: PR 리뷰, 이슈 생성, 코드 변경 사항 조회.
코드 리뷰나 GitHub 인터랙션이 필요할 때 이 서버의 도구를 검색하세요.

핵심은:

• 서버가 처리하는 작업 카테고리 명시
• Claude가 언제 검색해야 하는지 안내
• 주요 기능 나열

버전 히스토리

트러블슈팅: 문제가 생겼다면

자주 묻는 질문 (FAQ)

Q. Tool Search를 끄면 성능이 좋아지나요?

아니요, 반대입니다. MCP 도구가 많을수록 Tool Search를 켜두는 게 유리합니다. 끄면 모든 도구가 사전 로드되어 토큰을 많이 소비하고, 오히려 도구 선택 정확도가 떨어집니다.

Q. auto:N에서 N 값은 뭘로 설정하는 게 좋나요?

대부분의 경우 기본값(auto, 10%)이 적절합니다. MCP 서버를 많이 사용한다면 auto:5로 더 적극적으로 활성화할 수 있고, 도구가 적다면 auto:15로 느슨하게 설정할 수 있습니다.

Q. Tool Search가 켜지면 뭔가 달라지나요?

사용자 입장에서는 거의 차이를 못 느낍니다. MCP 도구가 평소처럼 작동하고, Claude가 내부적으로 필요한 도구만 검색해서 로드합니다. 토큰 절약은 자동으로 이루어집니다.

Q. 특정 MCP 서버만 Tool Search에서 제외할 수 있나요?

현재는 전체 활성화/비활성화만 가능합니다. 특정 서버만 제외하려면 해당 서버의 도구를 줄이거나, ENABLE_TOOL_SEARCH=false로 전체를 끄고 수동 관리해야 합니다.

마무리: 컨텍스트 경제의 패러다임 전환

이 기능은 단순한 토큰 절약을 넘어서, **”컨텍스트 경제”의 패러다임을 바꿉니다**.

기존에는 “MCP 서버 3개만 연결할까, 아니면 컨텍스트 절반을 포기할까”라는 트레이드오프가 있었습니다. 이제는 수십 개의 MCP 서버를 연결해도 실제로 필요한 도구만 로드되니까, **희소성 모델에서 접근성 모델**로 전환된 셈이죠.

Claude Code로 개발하고 계시다면, MCP Tool Search는 이미 켜져 있을 겁니다. /context 명령으로 토큰 사용량을 확인해보세요.