# Claude Code 的工具搜尋：代理程式如何找到所需的 MCP 工具 > Claude Code 的工具搜尋如何運作：哪些內容會立即載入 context、此機制何時會自行關閉，以及如何設定 ENABLE_TOOL_SEARCH 和 alwaysLoad。 Source: https://ailoot.ai/blog/zh-hant-tw/claude-code-tool-search-mcp-limit/ Canonical: https://ailoot.ai/blog/zh-hant-tw/claude-code-tool-search-mcp-limit/ Language: zh-Hant-TW Publisher: Ailoot (https://ailoot.ai/) Translation: guide-055 Revision: sha256-e195d284e86c807de92edd6117bca90db16cdcb9c00fa2ee1c05cb7775811388 如果你已將多個 MCP 伺服器連接到 Claude Code，工具搜尋就能讓它依需求載入所需工具，而不必事先載入所有定義。啟動時，代理程式會收到延後載入工具的名稱和伺服器指示，接著從目錄中搜尋所需項目。這有助於它處理大量工具：Anthropic 的文件指出，一次載入超過 30-50 個工具時，選擇準確度會下降。這是一般性指引，並非對你目前工作階段的測量結果。模型支援時，工具搜尋預設為啟用，但平台、代理伺服器或設定可能會將它停用。 [Ailoot 文件：API、金鑰與設定](https://ailoot.ai/docs/)。 ## 未使用工具搜尋時，context 會發生什麼事 每個連接的 MCP 伺服器都會將其工具加入代理程式可呼叫的項目清單。未使用工具搜尋時，工具定義（名稱、說明和參數結構描述）會預先載入 context。工作階段開始時，伺服器會在背景連線。如果需要使用尚未完成連線的伺服器所提供的工具，Claude Code 會透過內部的 `WaitForMcpServers` 工具等待。你可以針對每個連線，分別評估特定伺服器會增加多少工具和 token。 Anthropic 的官方文件提供了兩個約略數字（一般性數據，未說明測量方法）： - 50 個工具可能會占用 1 萬至 2 萬個 context token； - 一次載入超過 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 章節。 ## 工具搜尋的運作方式 啟用工具搜尋時，工作階段啟動後載入至 context 的只有延後載入工具的名稱和伺服器指示。伺服器指示會說明該伺服器適用於哪些工作。當某項工作需要尚未載入 context 的功能時，代理程式會自行搜尋目錄，尋找合適的工具。 Agent SDK 文件更詳細地說明了搜尋機制：預設情況下，單次搜尋會從目錄載入最多五個相關性最高的工具。在 SDK 壓縮代理程式找到這些工具時所用的訊息之前，這些工具會在工作階段後續的回合中繼續提供使用。壓縮後，先前探索到的工具可能會從 context 中移除，代理程式會在下次需要時再次搜尋。目錄最多支援 10 000 個工具。Claude Code 本身的 MCP 文件沒有提供這些具體數字，但說明了相同的延後載入原則。 根據 Agent SDK 文件，每次搜尋都會增加一次額外的往返。文件沒有明確說明該往返究竟包含哪些內容。至於 Claude Code，MCP 文件也說明了錯誤回報方面的差異：未使用工具搜尋時，Claude Code 不會將伺服器連線失敗的資訊告知模型。啟用搜尋後，模型會收到哪些伺服器連線失敗，以及錯誤內容為何的資訊。 Claude Code 不會限制單一伺服器可提供的工具數量。實際限制取決於該工作階段的 context window 預算。 設定工具是管理 AI 代理程式 context 的工作之一。 ## 工具搜尋預設為停用的情況 此機制預設為啟用，但是否運作取決於模型、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 區塊。若你是透過自己的閘道或代理伺服器連接 Claude，而非直接連到 Anthropic 的位址，就適用此情況。停用的原因是使用非標準的 `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` — 當工具定義的總量占 context window 不到 10% 時，Claude Code 會預先載入工具；達到此門檻後，便切換為延後載入； - `auto:N` — 原則相同，但可手動指定百分比門檻； - `false` — 完全停用此機制，並預先載入所有工具。 此外還有 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 變數：若已設定，工具搜尋就會維持關閉，使用者設定 `ENABLE_TOOL_SEARCH` 也不會改變此狀態。例外情況是，自 Claude Code 版本 2.1.227 起，組織可透過受管理設定維持工具搜尋的啟用狀態。 ## alwaysLoad 的功能及其對 context 和啟動的影響 伺服器設定中的 `alwaysLoad: true` 欄位適用於所有伺服器類型。使用後，該伺服器的所有工具都會在啟動時載入至 context，不受 `ENABLE_TOOL_SEARCH` 設定影響。代理程式不需要在使用前先搜尋這些工具。 一律載入工具會造成兩項影響。每個預先載入的工具都會占用部分 context，而這些 context 原本可用於任務本身。此外，工作階段啟動時會等待此伺服器連線，並遵守標準的五秒逾時設定。 例外情況是具有有效快取項目的遠端伺服器：它會直接從快取提供工具，不必連線，也不會延遲啟動。除非帳戶已在功能逐步推出期間啟用探索快取，否則此快取預設為關閉。你也可以透過 `MCP_DISCOVERY_CACHE=1` 明確啟用。只有在快取已啟用且包含有效項目時，才適用快速啟動的例外情況。即使代理程式透過搜尋工作時不需要這些工具，設定了 `alwaysLoad` 的工具仍會一直占用 context。 如果你要撰寫自己的 MCP 伺服器：伺服器指示能協助 Claude 理解何時該搜尋其工具，作用方式與 Skills 類似。Claude Code 預設會將每個工具的說明和每個伺服器的指示截斷至 2048 個字元，因此請將重要細節放在最前面。 選擇如何擴充 Claude Code，考量的不只是已連接的 MCP 伺服器數量。[Claude Code：一次保留多少個擴充功能](https://ailoot.ai/blog/zh-hant-tw/claude-code-skills-subagents-mcp-plugins/)和[Claude Code 該選什麼：Skills、Subagents、MCP 還是 Plugins](https://ailoot.ai/blog/zh-hant-tw/skills-subagents-mcp-plugins-claude-code/)這兩篇指南，會依不同工作探討 Skills、Subagents、MCP 和 Plugins。若要逐步設定特定 MCP 伺服器，請參閱[MCP 伺服器 for Claude Code：可直接使用的組合](https://ailoot.ai/blog/zh-hant-tw/mcp-servers-claude-code/)。 ## 接下來 對於少於約 10 個、且定義可輕鬆放入 context 的工具，Agent SDK 文件指出，一次全部載入通常更快。不過，在 Claude Code 的預設行為中，若變數未設定且沒有遇到上述限制，工具搜尋就會啟用，MCP 工具會延後至搜尋時載入，但設定了 `alwaysLoad` 的伺服器除外。 在此情況下，你可以明確設定 `ENABLE_TOOL_SEARCH=auto`：只要工具定義的總量不到 context window 的 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`；其餘伺服器則交由搜尋載入。
### 來源 - [Claude Code 中的 MCP，「透過 MCP 工具搜尋擴充規模」章節 — Anthropic 官方文件](https://code.claude.com/docs/en/mcp.md) - [Agent SDK 中的工具搜尋 — Anthropic 官方文件](https://code.claude.com/docs/en/agent-sdk/tool-search.md)
如果你需要透過 Ailoot 使用 AI 模型，請看看 [Ailoot](https://ailoot.ai/)。 ## 常見問題：Claude Code 的工具搜尋：代理程式如何找到所需的 MCP 工具 ### 即使開啟工具搜尋，為什麼仍可能在代理伺服器後失敗？ 第三方 API 主機必須支援 tool_reference 區塊。強制開啟 ENABLE_TOOL_SEARCH 不會增加該支援；不相容的代理可能直接拒絕請求，而非回退到預先載入全部工具。 ### 什麼時候該對 MCP server 設定 alwaysLoad？ 工具每個回合都會用到時適用。它會讓該伺服器全部工具定義占用啟動上下文；除非有有效的 discovery-cache 紀錄，啟動也可能等待連線。 ## Ailoot · 公司及其專案組合 Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。 公司及其專案組合：數百萬客戶，每月銷售額達數十億。 Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。