Claude Code MCPSearch 工具

#claudecode #claude #mcp #mcpsearch

Claude Code 在 2.1.7 版時改成預設啟用 MCPSearch 工具，它會在你的 MCP 工具資訊佔用的 token 數達到 context window 的 10%（預設值） 時干預 MCP 工具的使用方式，最主要有兩個效應：

延後把 MCP 工具的資訊加入 contex 的時間：只有在模型判斷目前資訊無法完成任務時，才會使用 MCPSearch 工具搜尋是否有適當的 MCP 工具可用，這時才會根據 MCPSearch 工具的搜尋結果載入 MCP 工具的資訊。優點就是在不需要使用 MCP 工具的情況下，不論你連接了多少個 MCP 伺服器，都完全不佔用 contex window。
只會提供所需工具的資訊，不會把所屬 MCP 伺服器的所有工具的資訊都加入 context。也就是說，如果某個 MCP 伺服器提供有 10 個工具，但只需要用到其中一項工具時，就只會提供給模型該項工具的資訊參考，不會把 10 個工具的資訊都放入 context 中，無端佔用額外的 contex window。

有興趣可以參考 Claude 中相對應的 Tool Search 工具的說明。

以 Notion MCP 伺服器實測

你很容易就可以發現為什麼要預設啟用 MCPSearch 工具，以 Notion 官方的 MCP 伺服器為例，即使我的 Claude Code 只連接了這一個 MCP 伺服器：

➜ claude mcp list
Checking MCP server health...

notion: https://mcp.notion.com/mcp (HTTP) - ✓ Connected

當你以 /context 查看時：

 Context Usage
⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-opus-4-5-20251101 · 41k/200k tokens (21%)
⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   ⛁ System prompt: 3.0k tokens (1.5%)
⛀ ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 17.0k tokens (8.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: 21.1k tokens (10.6%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 8 tokens (0.0%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛶ Free space: 114k (56.9%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛝ Autocompact buffer: 45.0k tokens (22.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝

MCP tools · /mcp
└ mcp__notion__notion-search: 1.5k tokens
└ mcp__notion__notion-fetch: 304 tokens
└ mcp__notion__notion-create-pages: 2.0k tokens
└ mcp__notion__notion-update-page: 2.0k tokens
└ mcp__notion__notion-move-pages: 611 tokens
└ mcp__notion__notion-duplicate-page: 220 tokens
└ mcp__notion__notion-create-database: 5.8k tokens
└ mcp__notion__notion-update-database: 6.0k tokens
└ mcp__notion__notion-create-comment: 1.6k tokens
└ mcp__notion__notion-get-comments: 108 tokens
└ mcp__notion__notion-get-teams: 229 tokens
└ mcp__notion__notion-get-users: 452 tokens
└ mcp__notion__notion-get-self: 79 tokens
└ mcp__notion__notion-get-user: 120 tokens

會發現光是 Notion 提供的 MCP 工具就有 14 個，總共耗用 21.1k 個 token，比所有系統（內建）工具的 17.0k 還多。當然，這樣的好處是模型可參考所有工具的資訊，直接挑選適當的使用，例如：

> 我有哪些跟提案相關的筆記？

● notion - notion-search (MCP)(query: "提案", query_type: "internal")

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Tool use

   notion - notion-search(query: "提案", query_type: "internal") (MCP)
   Perform a search over:
...（略）
 Do you want to proceed?
 > 1. Yes
   2. Yes, and don't ask again for notion - notion-search commands in C:\Users\meebo\code\tt
   3. No

 Esc to cancel · Tab to add additional instruction

你可以看到模型根據問題，馬上找出可以使用 Notion 提供的搜尋工具協助處理，但壞處就是如果提問內容根本不需要 MCP 工具的協助，還是得佔用這 21.1k 個 token 的空間，白白燒掉 token 額度。

我們沒有要真的測試 Notion 的工具效果，所以這裡先中斷離開 Claude Code。

使用 MCPSearch 工具

接著來看看如果啟用 MCPSearch 工具，會有什麼差別？要特別注意的是，雖然官方文件說預設會啟用 MCPSearch 工具，不過我自己的測試環境中，是已經升級到 2.1.11 的版本，但並不會自動啟用 MCPSearch 工具：

➜ claude --version
2.1.11 (Claude Code)

在 Claude Code 的 Github issue 頁面中，找到其他人類似的問題，提供了繞路的解法，設定環境變數 ENABLE_TOOL_SEARCH 為 true 就可以強制啟用 MCPSearch 工具，底下是我在 Windows 的 PowerShell 下測試：

➜ $env:ENABLE_TOOL_SEARCH="true"; claude

如果使用 macOS/Linux，就改用：

ENABLE_TOOL_SEARCH=true claude

如果覺得麻煩，也可以在 .claude/settings.json 檔中加入環境變數的設定：

{
  "env": {
    "ENABLE_TOOL_SEARCH": "true"
  }
}

執行後一樣使用 /context 觀察目前的 contex 用量：

 Context Usage
⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-opus-4-5-20251101 · 20k/200k tokens (10%)
⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: 3.1k tokens (1.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 17.0k tokens (8.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 8 tokens (0.0%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛶ Free space: 135k (67.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛝ Autocompact buffer: 45.0k tokens (22.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝

MCP tools · /mcp (loaded on-demand)

Available
└ mcp__notion__notion-search
└ mcp__notion__notion-fetch
└ mcp__notion__notion-create-pages
└ mcp__notion__notion-update-page
└ mcp__notion__notion-move-pages
└ mcp__notion__notion-duplicate-page
└ mcp__notion__notion-create-database
└ mcp__notion__notion-update-database
└ mcp__notion__notion-create-comment
└ mcp__notion__notion-get-comments
└ mcp__notion__notion-get-teams
└ mcp__notion__notion-get-users
└ mcp__notion__notion-get-self
└ mcp__notion__notion-get-user

你可以看到兩個主要的差異：

在上方的分類 token 用量統計中，原本佔用 21.1k 個 token 的 MCP tools 不見了，總用量也從原本看到的 41k 驟降成 20k，少掉的就是 MCP Tools 的 21.1k。
在底下標示 MCP tools 的區域，出現了 "（loaded on-emand）" 字樣，表示現在是依據需要才會載入 MCP 工具的資訊到 context 中。

很顯然 MCPSearch 生效了，不確定會需要使用 MCP 工具時，就不會把 MCP 工具放入 context 中。接著就來驗證看看：

> 我有哪些跟提案相關的筆記？

● 讓我搜尋你的 Notion 筆記中與提案相關的內容。

● MCPSearch(Search MCP tools: "select:mcp__notion__notion-search")
  ⎿  Found 1 tool

● notion - notion-search (MCP)(query: "提案", query_type: "internal")

───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 Tool use

   notion - notion-search(query: "提案", query_type: "internal") (MCP)
...（略）
 Do you want to proceed?
 > 1. Yes
   2. Yes, and don't ask again for notion - notion-search commands in C:\Users\meebo\code\tt
   3. No

 Esc to cancel · Tab to add additional instructions

我們問了同樣的問題，你會看到最終模型還是會使用 Notion 伺服器提供的搜尋工具，但是過程不大一樣：

模型先使用了 MCPSearch 工具，它的執行結果是 ""select:mcp_notion_notion-search")"，告訴模型可以選用 Notion 的搜尋工具。
接著模型依據 MCPSeach 工具的搜尋結果使用 Notion 的搜尋工具。

事情還不只如此，即使現在使用到了 Notion 伺服器提供的工具，如果中斷剛剛的交談，再使用 /context 查看用量：

 Context Usage
⛁ ⛀ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁ ⛁   claude-opus-4-5-20251101 · 22k/200k tokens (11%)
⛁ ⛀ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System prompt: 3.0k tokens (1.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ System tools: 17.0k tokens (8.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ MCP tools: 1.5k tokens (0.8%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛁ Messages: 685 tokens (0.3%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛶ Free space: 133k (66.4%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶   ⛝ Autocompact buffer: 45.0k tokens (22.5%)
⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛶ ⛝ ⛝ ⛝
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝
⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝ ⛝

MCP tools · /mcp (loaded on-demand)

Loaded
└ mcp__notion__notion-search: 1.5k tokens

Available
└ mcp__notion__notion-fetch
└ mcp__notion__notion-create-pages
└ mcp__notion__notion-update-page
└ mcp__notion__notion-move-pages
└ mcp__notion__notion-duplicate-page
└ mcp__notion__notion-create-database
└ mcp__notion__notion-update-database
└ mcp__notion__notion-create-comment
└ mcp__notion__notion-get-comments
└ mcp__notion__notion-get-teams
└ mcp__notion__notion-get-users
└ mcp__notion__notion-get-self
└ mcp__notion__notion-get-user

你會看到兩個不同的地方：

上方分類統計用量的地方出現了 MCP tools，但是總量是 1.5k，不是最前面看到的 21.1k，表示並不是所有 Notion 提供的工具資訊都放入了 context。
在下方標示 MCP tools 的地方，會看到多了 Loaded 區塊，這裡只列出了 mcp__notion__notion-search，佔用 1.5k 個 token。

正因為如此，所以雖然用到了 MCP 工具，但是 context 總量也還是只有 22k 而已，不會激增到最前面看到的 41k。

MCPSearch 工具的代價

MCPSearch 工具的基本概念很簡單，它想做到的就是像 Agent Skills 那樣，只有在需要的時候才提供完整資訊。如果 MCP 工具使用到的機率不高，廣度也不大，也就是不會一下要用 A 工具、一下要用 B 工具，一下又要用 C 工具，那麼沒有用到 MCP 工具時所省下的 token 量，應該可以讓你節省很多額度，代價則是在新的交談階段初次使用到特定的 MCP 工具前，都會先使用一次 MCPSearch 工具，多進行一次交談。

從上面的測試也可以看到，就算只連接了一個 MCP 伺服器，但如果提供的工具繁多，或是該工具比較複雜，那麼相關的資訊量也是可以多到你嚇一跳的。單單一個 Notion 伺服器提供的工具就佔了 21.1k 個 token，整個 context window 也才 200k，10%↑ 的量就不見了，是很有感的差異，更別說你可能連接了不只一個 MCP 伺服器。

當然，如果你就只會連接佔用量很少的 MCP 伺服器，整體用量可能比多一輪問答使用 MCPSearch 工具的 token 量（這會包含交談記錄、系統訊息、系統工具）少很多，或者使用到 MCP 工具的機率非常頻繁，那就可以權衡是否要啟用 MCPSearch 工具。