이 기사의 요점: Claude Code에는 MCP 도구의 스키마 정의를 「사용하기 직전」까지 로드하지 않는 deferred tools (지연 도구)라는 메커니즘과, 이를 검색·로드하는 내장 도구인 ToolSearch가 있다. 나는 2026년 7월 8일에 이 동작을 실측하였고, 다음 날인 7월 9일에 공식 문서 4페이지와 대조하였다. 본 기사에서 다루는 4가지 동작——① 쿼리 형식은 3종류가 있다, ② 에러 「No matching deferred tools found」는 도구의 부재와 MCP 서버 미연결을 구분하지 않는다, ③ 서버 절단 시 로드된 도구도 「no longer available」이 된다, ④ 로드는 1회의 ToolSearch 호출로 묶어야 한다——는 2026-07-09 시점의 조사 결과 모두 공식 문서 페이지에 기술되어 있지 않았다. 실측 로그와 GitHub Issue, Anthropic제 MCP 서버의 instructions 텍스트를 근거로, 메커니즘과 운용상의 설계 지침을 해설한다.

ToolSearch란——도구 정의를 「사용하기 직전」까지 읽히지 않는 메커니즘

MCP 서버를 아직 하나도 연결하지 않았거나 (혹은 하나만 연결한) 사람에게는 현시점에서 실질적인 해가 없는 이야기로 보일지도 모른다. 하지만 이는 여러 서버를 연결하는 순간 영향을 미치는 메커니즘이며, 연결하기 전에 알고 있으면 「어떤 서버를 상시 연결로 둘 것인가」라는 설계 판단 자체가 달라진다. 실제로 나는 이 메커니즘을 이해하지 못한 채 ToolSearch 에러를 마주하여 의미를 오독할 뻔했다 (후술).

배경에 있는 문제는 단순하다. MCP 서버를 여러 개 연결하면, 모든 도구의 스키마 정의 (인자·설명문)가 시스템 프롬프트(System Prompt)에 상주하여 컨텍스트(Context)를 압박한다. 도구를 한 번도 사용하지 않는 세션에서도 정의문은 계속 그 자리에 머물러 있게 된다.

ToolSearch는 이를 「도구 이름만 먼저 보여주고, 스키마 본체는 사용하기 직전에 로드한다」는 설계로 해결한다. 스키마가 로드되지 않은 도구는 deferred tools (지연 도구)라고 불리는 리스트에 이름만 올라가 있으며, Claude가 필요해진 타이밍에 ToolSearch를 호출하여 검색·로드한다.

공식 문서의 Tools reference에도 ToolSearch는 나와 있다. 다만 설명은 「Searches for and loads deferred tools when tool search is enabled (도구 검색이 활성화된 경우 deferred tools를 검색하여 로드한다)」라는 취지의 한 줄뿐이다. 이 이후의 내용——쿼리 작성법, 에러 읽는 법, 서버 절단 시의 동작——은 2026-07-09 시점의 조사로는 공식 문서에 적혀 있지 않다. 이하, 실측으로 확인한 4가지 동작을 차례대로 살펴보겠다.

동작 ① 쿼리 형식은 3종류가 있다

ToolSearch의 쿼리에는 세 가지 형식이 있다.

ToolSearch를 직접 호출하는 것은 Claude 자신이지만, 사용자 측에서 「ToolSearch로 select:mcp__claude-in-chrome__tabs_context_mcp를 로드해줘」와 같이 요청하면 의도한 형식으로 호출하게 할 수 있다 (MCP 도구의 내부 이름은 이 예시처럼 mcp__서버명__도구명 형식을 취하고 있다). 스킬이나 서브 에이전트(Sub-agent)용 지시서에 로드해야 할 도구를 적어둘 경우에도 이 서식을 사용하여 지정하게 된다.

이 서식 정의는 2026-07-09 시점의 조사로는 공식 문서 페이지 어디에서도 찾아볼 수 없었다. Anthropic의 API 사양서 (Platform 문서)에는 정규 표현식 버전과 자연어 검색 버전이라는 두 종류의 쿼리 형식을 가진 tool search 기능이 정의되어 있지만, 이는 API 범용 기능의 사양이며, Claude Code 내장 ToolSearch가 받아들이는 select: 구문과는 계층이 다르다.

select:

구문의 유래에 대한 단서는 GitHub Issue #31002(커뮤니티 보고, Anthropic 공식 성명 아님)이다. 보고자의 독자적인 조사에 따르면 select: 구문은 v2.1.31에서 추가된 것으로 알려져 있으며, 보고자 스스로도 "the change was not documented in the release notes or anywhere else we could find (이 변경 사항은 릴리스 노트(release notes)나 우리가 찾을 수 있는 그 어디에도 문서화되어 있지 않았다)"라고 명시하고 있다.

동작 ② 「No matching deferred tools found」는 도구의 부재를 의미하지 않는다

솔직히 말해서 이 메커니즘은 몰라도 평소에는 사용하는 데 지장이 없다. ToolSearch는 Claude가 자동으로 호출하기 때문에 사용자가 의식하는 상황은 적다. 문제는 에러가 발생한 순간 원인을 분류(troubleshooting)할 수 없게 된다는 점이다.

2026년 7월 8일, 나는 MCP 서버가 비활성화된 상태에서 select:를 지정하여 ToolSearch를 실행시켰다. 돌아온 메시지는 다음과 같았다.

No matching deferred tools found

이 문구만으로는 다음 두 가지를 구분할 수 없다.

• (a) 도구 자체가 존재하지 않음 (도구 이름 오타, 애초에 해당 서버에 없는 도구)
• (b) MCP 서버가 연결되지 않았을 뿐임 (도구는 실재하지만, deferred 리스트에 올라와 있지 않음)

나는 처음에 이를 (a)로 오독할 뻔했다. 실제로는 (b)였으며, /mcp 명령어로 서버를 활성화하자 해당 서버의 도구가 deferred 리스트에 등장했고, ToolSearch로 로드한 후에는 일반적인 도구와 마찬가지로 호출할 수 있었다. 도구는 처음부터 실재하고 있었던 것이다.

이러한 모호함에서 얻을 수 있는 설계상의 교훈은 명확하다. 스킬(skill)이나 서브 에이전트(sub-agent)를 위한 지시사항을 작성할 때는 폴백(fallback) 절차를 명시해야 한다는 것이다. ToolSearch의 에러 메시지만으로는 원인을 분류할 수 없기 때문에, 지시를 받은 쪽이 "도구가 없다"라고 오판하여 태스크를 포기할 수 있다. 나는 지시서에 다음과 같은 구절을 넣으려 노력한다.

## 도구를 찾을 수 없는 경우의 폴백(fallback)
- ToolSearch가 "No matching deferred tools found"를 반환하더라도, 도구가 존재하지 않는다고 단정하지 말 것
- 먼저 MCP 서버의 연결 상태를 의심하고, `/mcp`로 대상 서버가 연결되었는지 확인할 것
...

이 에러 메시지 자체도 2026-07-09 기준 조사 결과 공식 문서에는 등장하지 않는다. API 사양서에 "해당 사항 없는 검색은 에러가 아니라 빈 결과(empty result)를 반환한다"라는 유사한 기술이 있을 뿐, Claude Code의 CLI 상에서 표시되는 이 문구와 그 분류 방법에 대해서는 적혀 있지 않았다.

동작 ③ 서버 연결 끊김으로 로드된 도구도 「no longer available」이 된다

ToolSearch로 로드한 도구는 로드 후에도 MCP 서버의 연결에 계속 의존한다. 서버가 연결 해제되면 한 번 로드된 도구도 "no longer available" 상태가 되어 사용할 수 없게 된다.

이 동작은 GitHub Issue #38043(커뮤니티 버그 보고)에서 Claude Code가 실제로 출력하는 시스템 메시지의 원문으로 인용되어 있다.

The following deferred tools are no longer available (their MCP server disconnected). Do not search for them — ToolSearch will return no match

(다음의 deferred tools는 더 이상 사용할 수 없습니다 (해당 MCP 서버의 연결이 끊겼습니다). 이들을 검색하지 마십시오 — ToolSearch는 일치하는 항목을 반환하지 않습니다.)

내가 2026년 7월 8일에 관측한 동작도 이 문구와 일치한다.

그렇다면 서버가 재연결되었을 때 도구(Tool)는 복구되는가? 이 부분에 대해서는 보고가 엇갈리고 있다. 나의 환경에서는 2026년 7월 8일 시점에 재연결을 통해 도구가 복구되었다. 반면, 동일한 Issue #38043에는 "재연결 후에도 도구는 세션에서 제거된 상태로 유지되며, 복구하려면 세션을 재시작하는 방법뿐이다"라는 상반된 보고가 있다. 참고로 이 Issue는 "duplicate" 라벨과 함께 이미 클로즈(closed)되었으며, Anthropic 공식 스태프의 답변은 확인되지 않았다. 어디까지나 한 사용자의 보고라는 점을 유의해야 한다. 두 보고 모두 Anthropic 공식의 명시적 발언이 아니며, 버전이나 연결 방식에 따른 차이일 가능성도 있다. 현시점에서는 연결 끊김으로부터의 자동 복구를 전제로 운영을 설계하지 않는 것이 안전하다는 것이 나의 판단이다.

덧붙여, 공식 문서에는 MCP 서버의 자동 재연결 사양(HTTP / SSE 서버는 1초부터 시작하여 간격을 배수로 늘리며 최대 5회 재시도하며, stdio 서버는 자동 재연결을 하지 않음)이 기재되어 있다. 하지만 그동안 로드된 deferred tools가 어떻게 처리되는지—유지되는지, 무효화되는지—는 2026-07-09 시점의 조사에서는 명시되어 있지 않았다.

동작 ④ 로드는 1회의 ToolSearch로 통합한다

필요한 도구가 여러 개일 때, 도구 하나당 한 번씩 ToolSearch를 호출하는 것은 낭비가 크다. 호출할 때마다 라운드트립 (Round-trip, 왕복 통신)이 발생하기 때문이다. select:

쿼리는 쉼표(comma)로 구분된 다중 지정(multiple specification)을 허용하므로, 필요한 도구는 1회의 ToolSearch 호출에 모아서 로드하는 것이 원칙이다.

이 원칙의 일차 출처는 공식 문서 페이지가 아니라, Anthropic 제 MCP 서버의 instructions 텍스트(서버 연결 시 세션에 주입되는 서버 자체의 사용법 지침)이다. computer-use 서버의 instructions에는 다음과 같이 명시되어 있다.

Loading via ToolSearch — load in bulk, not one-by-one: if computer-use tools are in the deferred list, load them ALL in a single ToolSearch call（중략）Don't use select: for individual tools — that's one round-trip per tool.

(ToolSearch를 통한 로드는 일괄로 처리할 것. 하나씩이 아니라: 만약 computer-use 도구들이 deferred 리스트에 있다면, 단 한 번의 ToolSearch 호출로 전부 로드할 것. 개별 도구에 대해 select:를 사용하지 말 것 — 이는 도구 하나당 한 번의 라운드트립을 소모함)

claude-in-chrome 서버의 instructions에도 동일한 취지의 문구가 별도로 존재한다.

batch every tool you expect to need into ONE ToolSearch call (the select query accepts a comma-separated list). Do NOT load tools one at a time; each separate ToolSearch call wastes a full round-trip.

(필요할 것으로 예상되는 모든 도구를 하나의 ToolSearch 호출로 배치할 것 (select 쿼리는 쉼표로 구분된 리스트를 허용함). 도구를 하나씩 로드하지 말 것. 별도의 ToolSearch 호출을 할 때마다 전체 라운드트립이 낭비됨)

이러한 instructions는 해당 MCP 서버에 접속한 일반적인 세션에서 시스템 리마인더(system reminder)로서 자동으로 주입되는 정보이며, 특별한 수단으로 추출해낸 것이 아니다.

일괄 로드가 단일 서버의 편의를 위한 것이 아니라, 확인된 computer-use 및 claude-in-chrome 두 서버 모두에 공통된 운영 지침임을 알 수 있다 (다른 Anthropic 제 MCP 서버까지 전수 조사를 수행한 것은 아니다). 직접 MCP 서버나 스킬의 지침서를 작성하는 사람이라면, 동일한 원칙을 자신의 instructions에도 작성해 둘 가치가 있다.

반면, 공식 문서 페이지 측에는 "자주 사용하는 3~5개의 툴은 비지연(처음부터 로드된 상태)으로 설정해 둔다"라는 유사한 최적화 조언이 있을 뿐, "한 번에 묶어서 처리하라"는 직접적인 권장 사항은 2026-07-09 시점의 조사 결과 발견되지 않았다.

보충하자면, ToolSearch를 통한 로드는 서브 에이전트(Task 툴로 기동되는 자식 에이전트)에서도 기능한다. 나는 2026년 5월 30일에 서브 에이전트로부터 claude-in-chrome의 탭 취득 툴(mcp__claude-in-chrome__tabs_context_mcp)을 ToolSearch로 로드하여 호출할 수 있음을 확인했다.

"공식 문서를 읽으면 되는 것 아닌가"에 대한 답변

여기까지 읽고 "공식 문서를 읽으면 끝날 이야기 아닌가?"라고 생각한 사람을 위해, 대조 조사 결과를 정리해 둔다. 나는 2026년 7월 9일에 다음 4개 페이지를 대상으로 교차 검증 조사를 수행했다.

• Claude Code 문서 "Connect Claude Code to tools via MCP" (code.claude.com/docs/en/mcp)
• Claude Code 문서 "Scale to many tools with tool search" (code.claude.com/docs/en/agent-sdk/tool-search)
• Claude Code 문서 "Tools reference" (code.claude.com/docs/en/tools-reference.md)
• Claude Platform 문서 "Tool search tool" (platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool)

만약을 위해 강조하자면, 이것은 "2026-07-09 시점의 조사에서 기술되지 않았다"는 이야기다. Claude Code의 문서는 업데이트가 빠르며, 이러한 동작들도 향후 문서화될 가능성은 충분히 있다. 다만 적어도 현시점에서는 공식 문서를 읽어도 나오지 않는다. 실측 로그와 GitHub Issue, 그리고 제품 내에 실제로 존재하는 instructions 텍스트가 단서의 전부였다.

툴 정의의 "상주 비용"이라는 관점

마지막으로, ToolSearch를 조금 떨어진 시점에서 바라보고 싶다.

ToolSearch가 해결하고 있는 것은 "항상 읽히는 정보를 줄이는" 문제다. 동일한 문제는 사실 툴 정의 이외의 장소에도 존재한다. CLAUDE.md에 작성한 지시·규칙은 툴 정의와 마찬가지로 매 세션마다 읽히며 컨텍스트(Context)를 계속 소비한다. 나는 이전에 나의 CLAUDE.md를 실제로 줄여보았던 기록을 썼는데, 그것은 지시 사항의 상주 비용에 관한 이야기였고, 이번 ToolSearch는 툴 정의의 상주 비용에 관한 이야기다. "정말로 필요해지는 순간까지 읽히지 않게 한다"라는 동일한 설계 사상이 다른 레이어에 적용되어 있는 것이다.

MCP 서버를 늘릴지 말지 고민될 때, "툴이 늘어난다"는 점뿐만 아니라 "상주하는 정의가 늘어난다"는 점을 비용으로서 의식한다. deferred tools와 ToolSearch는 그 비용을 구조적으로 낮추기 위한 메커니즘이라고 이해해 두면, 연결 설계의 판단을 내리기 쉬워질 것이다.

요약——자신의 환경에서 확인하는 3단계

본 기사의 내용은 나의 환경(2026년 7월 8일 기준)에서의 실측에 기반하고 있다. 동작 ③과 같이 환경이나 버전에 따라 차이가 발생할 가능성이 있는 내용도 포함되어 있으므로, 반드시 자신의 환경에서 확인해 보길 권한다. 절차는 간단하다.

deferred 리스트 살펴보기: MCP 서버를 연결한 상태에서, Claude에게 "ToolSearch로 키워드 검색을 해서, 지금 deferred 리스트에 있는 툴을 보여줘"라고 요청한다 -
에러의 모호함 체감하기: /mcp로 서버를 비활성화한 상태에서 select:툴이름 형태의 ToolSearch를 시도한다. "No matching deferred tools found"가 반환되며, 툴이 존재하지 않는 것과 구별할 수 없음을 확인한다 -
연결 해제→재연결 동작 관찰하기: 로드된 툴이 있는 세션에서 서버를 연결 해제 및 재연결하여, 툴이 복구되는지 관찰한다. 이 부분은 보고가 갈리는 동작이므로 확인할 가치가 가장 높다

공식 문서가 따라잡을 때까지 의지할 수 있는 것은 자신의 실측 로그다. 그리고 실측한 결과가 본 기사나 GitHub Issue의 보고와 다르다면, 그 자체로 버전 차이에 대한 귀중한 관측 기록이 된다.

MCP나 툴 연동을 포함한 Claude Code의 기초를 체계적으로 익히고 싶은 분들을 위한 입문서가 나와 있다. 메커니즘의 전체상을 먼저 파악해 두면, 본 기사와 같은 개별 동작의 위치를 이해하기 쉬워진다.

• Claude Code를 통한 AI 구동 개발 입문 (히라카와 토모히데 저)
• 실전 Claude Code 입문 (니시미 키미히로·요시다 신고·오시마 유키 저)

ToolSearch가 툴 정의의 상주 비용을 낮춰준다는 것을 알게 되면, 다음 질문이 생긴다——그렇다면 지시·규칙·절차는 어느 레이어에 전달해야 가장 효과적인가.

규칙이 지켜지지 않는 것도, 서브 에이전트(Sub-agent)가 작동하지 않는 것도, 대부분은 "어디에 전달할 것인가"의 설계 문제다. CLAUDE.md · 서브 에이전트 · 스킬 · Playbook · 메모리 · 설정/권한 · MCP라는 7가지 레이어 중, 그 정보는 어디에 두어야 하는가. 그것을 한 장씩 해부한 것이 Zenn Books의 「코드를 쓰지 못하는 내가 Claude Code에 '메커니즘'을 전달하기까지」(Vol.4)이다. 본 기사에서 다룬 MCP와 툴 계층은 그 7개 레이어의 가장 깊은 곳에 해당한다.

이 기사는 はてなブログ(Hatena Blog)로부터의 크로스 포스트입니다.

Discussion