이 기사의 요점: 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 텍스트를 근거로, 메커니즘과 운용상의 설계 지침을 해설한다.

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가지 동작을 차례대로 살펴보겠다.

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

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)나 우리가 찾을 수 있는 그 어디에도 문서화되어 있지 않았다)"라고 명시하고 있다.

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

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 사양서에 "해당 사항이 없는 검색은 에러가 아니라 빈 결과를 반환한다"라는 유사한 기술이 있을 뿐, Claude Code의 CLI 상에서 표시되는 이 문구와 그 구분 방법에 대해서는 적혀 있지 않았다.

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일에 관측한 동작도 이 문구와 일치한다.

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

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

필요한 도구가 여러 개 있을 때, 도구 하나씩 ToolSearch를 호출하는 것은 낭비가 크다. 호출할 때마다 라운드트립 (round-trip, 왕복의 주고받음)이 발생하기 때문이다. select:

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

이 원칙의 1차 소스는 공식 문서 페이지가 아니라, 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개의 도구는 비지연 (non-deferred, 처음부터 로드된 상태)로 설정해 둔다"라는 유사한 최적화 조언이 있을 뿐, "한 번에 모아서 수행하라"라는 직접적인 권장 사항은 2026-07-09 시점의 조사에서는 찾아볼 수 없었다.

보충하자면, ToolSearch를 통한 로드는 서브 에이전트(sub-agent, 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)

| 동작 | 공식 문서 페이지 |
대체 단서 |
|---|---|
① 쿼리 형식 3종 (select: 등) | 기재 없음 |
GitHub Issue #31002 (v2.1.31에서 추가되었다는 자체 조사 및 공식 미문서화 보고자 명시), Anthropic 제작 MCP instructions에 실례 |
| ② No matching deferred tools found | 기재 없음 |
API 사양서의 '해당 없음은 빈 결과를 반환함(오류가 아님)'이라는 근접한 기술 문서만 |
| ③ 연결 끊김 시 no longer available화 | 기재 없음 |
GitHub Issue #38043에 시스템 메시지 원문 인용. 재연결 후 복구 가능 여부는 보고가 엇갈림 |
| ④ 일괄 로드 권장 | 직접적인 기술 문서 없음 |
Anthropic 제작 MCP 서버 (computer-use / claude-in-chrome)의 instructions에 명기. 공식 페이지에는 '자주 사용하는 도구는 비지연(non-deferred)으로'라는 조언만

혹시 몰라 강조하자면, 이는 '2026년 7월 9일 시점 조사에서 기술 문서가 없었다'는 이야기다. Claude Code의 문서는 업데이트가 빠르기 때문에 이러한 동작들도 미래에 기술 문서화될 가능성은 충분하다. 하지만 적어도 현재 시점에서는 공식 문서를 읽어도 나오는 내용이 아니다. 실측 로그와 GitHub Issue, 그리고 제품 내부에 실제로 존재하는 instructions 텍스트가 유일한 단서였다.

마지막으로, ToolSearch를 한 발짝 떨어진 관점에서 살펴보고 싶다.

ToolSearch가 해결하는 문제는 '항상 읽히는 정보를 줄이는 것'이라는 문제다. 같은 문제는 사실 도구 정의 이외의 장소에도 있다. CLAUDE.md에 작성한 지침/규칙은, 도구 정의와 마찬가지로 매 세션마다 로드되어 컨텍스트를 소비하고 계속 쌓인다. 나는 예전에 내 CLAUDE.md를 실제로 줄여본 기록을 썼는데, 그것은 **지침의 상주 비용(常駐コスト)**에 대한 이야기이고, 이번 ToolSearch는 도구 정의의 상주 비용에 대한 이야기다. '정말로 필요할 순간까지 읽히지 않게 한다'라는 동일한 설계 사상이 다른 레이어에 적용되고 있는 것이다.

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

본 기사의 내용은 나의 환경(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가 도구 정의의 상주 비용 (residency cost)을 낮춰준다는 것을 알게 되면, 다음 질문이 생긴다 —— 그렇다면 지시·규칙·절차는 어느 레이어(layer)에 전달해야 가장 효과적인가.

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

이 기사는 Hatena Blog로부터의 크로스 포스트입니다.