Feb 23, 2026

Claude Tool Infrastructure 完整指南：從 MCP Connector 到 Tool Search 的全面解析

Claude 的 Tool Infrastructure 是支撐工具發現、編排和規模化的基礎設施層。當工具數量從幾個增長到數百甚至數千個時，這些基礎設施能力就變得不可或缺。本文將深入解析四大核心組件：Fine-grained Tool Streaming、MCP Connector、Programmatic Tool Calling 與 Tool Search。

一、Fine-grained Tool Streaming

核心概念

Fine-grained Tool Streaming 允許在串流模式下，工具使用的參數值不經過緩衝或 JSON 驗證就直接串流輸出，大幅降低接收大型參數的延遲。

啟用方式

在工具定義中設定 eager_input_streaming: true，並在請求中啟用 streaming：

{
  "name": "make_file",
  "description": "Write text to a file",
  "eager_input_streaming": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "filename": { "type": "string" },
      "lines_of_text": { "type": "array" }
    },
    "required": ["filename", "lines_of_text"]
  }
}

效能差異

模式	首次 chunk 延遲	Chunk 特性
標準 streaming	~15 秒	短小片段，較多斷詞
Fine-grained streaming	~3 秒	較長片段，較少斷詞

注意事項

不保證最終串流能組成合法的 JSON 字串
當 stop_reason 為 max_tokens 時，串流可能在參數中途中斷
需要在程式碼中處理無效或不完整的 JSON
將無效 JSON 回傳給模型時，建議包裝為 {"INVALID_JSON": "<your invalid json>"}
全面可用，無需 beta header，支援所有模型和平台

二、MCP Connector

核心概念

MCP Connector 讓開發者可以直接從 Messages API 連接到遠端 MCP 伺服器，無需自行實作 MCP 客戶端。這大幅簡化了與外部工具和服務的整合。

架構組件

MCP Connector 使用兩個核心組件：

MCP Server Definition（mcp_servers 陣列）：定義伺服器連線資訊
MCP Toolset（tools 陣列）：配置要啟用的工具及其設定

基本使用

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1000,
    messages=[{"role": "user", "content": "What tools do you have?"}],
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.example.com/sse",
            "name": "example-mcp",
            "authorization_token": "YOUR_TOKEN",
        }
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "example-mcp"}],
    betas=["mcp-client-2025-11-20"],
)

工具配置模式

MCP Toolset 支援靈活的工具配置：

Allowlist 模式（只啟用特定工具）：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": { "enabled": false },
  "configs": {
    "search_events": { "enabled": true },
    "create_event": { "enabled": true }
  }
}

Denylist 模式（停用特定工具）：

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "configs": {
    "delete_all_events": { "enabled": false }
  }
}

配置合併優先順序

configs 中的工具特定設定（最高）
default_config 的集合級設定
系統預設值（enabled: true, defer_loading: false）

多伺服器支援

可在單次請求中連接多個 MCP 伺服器，每個伺服器有獨立的 toolset 配置。每個 MCP 伺服器必須恰好被一個 MCPToolset 引用。

回應格式

使用 MCP 工具時，回應包含兩種新的 content block：

mcp_tool_use：Claude 呼叫 MCP 工具的請求
mcp_tool_result：MCP 工具的執行結果

OAuth 認證

支援 OAuth Bearer Token 認證。開發者需要自行處理 OAuth 流程並取得 access token，然後在 MCP 伺服器配置中傳入 authorization_token。

限制

目前只支援 MCP 規範中的 tool calls 功能
伺服器必須透過 HTTP 公開暴露（支援 Streamable HTTP 和 SSE）
不支援本地 STDIO 伺服器的直接連接
目前不支援 Amazon Bedrock 和 Google Vertex

TypeScript SDK MCP Helpers

如果需要自行管理 MCP 客戶端連線，TypeScript SDK 提供了輔助函式：

Helper	說明
`mcpTools(tools, mcpClient)`	將 MCP 工具轉換為 Claude API 工具格式
`mcpMessages(messages)`	將 MCP prompt 訊息轉換為 Claude API 訊息格式
`mcpResourceToContent(resource)`	將 MCP 資源轉換為 content block
`mcpResourceToFile(resource)`	將 MCP 資源轉換為檔案物件

三、Programmatic Tool Calling

核心概念

Programmatic Tool Calling 讓 Claude 能夠在 Code Execution 容器中撰寫程式碼來呼叫工具，而非每次工具呼叫都需要透過模型往返。這大幅減少了多工具工作流程的延遲和 token 消耗。

運作流程

Claude 撰寫 Python 程式碼來呼叫工具（可包含多次呼叫和前後處理邏輯）
程式碼在沙箱容器中執行
當工具函式被呼叫時，Code Execution 暫停，API 回傳 tool_use block
開發者提供工具結果，Code Execution 繼續執行（中間結果不會載入 Claude 的 context window）
所有程式碼執行完成後，Claude 接收最終輸出並繼續處理任務

啟用方式

使用 allowed_callers 欄位指定工具可被呼叫的方式：

{
  "name": "query_database",
  "description": "Execute a SQL query",
  "input_schema": { ... },
  "allowed_callers": ["code_execution_20260120"]
}

allowed_callers 的可能值：

["direct"]：只能由 Claude 直接呼叫（預設）
["code_execution_20260120"]：只能從 Code Execution 中呼叫
["direct", "code_execution_20260120"]：兩種方式都可以

建議為每個工具選擇其中一種方式，而非同時啟用兩者，以提供更明確的使用指引。

回應中的 `caller` 欄位

每個 tool use block 都包含 caller 欄位，指示呼叫方式：

{
  "type": "tool_use",
  "name": "query_database",
  "input": {"sql": "..."},
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

進階模式

批次處理迴圈：

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    data = await query_database(f"SELECT revenue FROM sales WHERE region='{region}'")
    results[region] = sum(row["revenue"] for row in data)

top_region = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top_region[0]} with ${top_region[1]:,}")

提前終止：

endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
    status = await check_health(endpoint)
    if status == "healthy":
        print(f"Found healthy endpoint: {endpoint}")
        break

條件式工具選擇：

file_info = await get_file_info(path)
if file_info["size"] < 10000:
    content = await read_full_file(path)
else:
    content = await read_file_summary(path)

Token 效率

Programmatic Tool Calling 的最大優勢之一：

工具結果不會加入 Claude 的 context，只有最終程式碼輸出會
中間處理（過濾、聚合等）不消耗模型 token
多次工具呼叫在單次 Code Execution 中完成，減少開銷
呼叫 10 個工具的 token 消耗大約只有直接呼叫的 1/10

限制

不支援 strict: true 的 Structured Outputs
不能透過 tool_choice 強制使用
不支援 disable_parallel_tool_use: true
不支援 MCP Connector 提供的工具
容器約在 4.5 分鐘不活動後過期

四、Tool Search

核心概念

Tool Search 讓 Claude 能夠處理數百甚至數千個工具。透過動態發現和按需載入，而非將所有工具定義預先載入 context window，解決了兩個關鍵挑戰：

Context 效率：50 個工具約消耗 10-20K tokens
工具選擇準確度：超過 30-50 個工具時，Claude 的選擇準確度會顯著下降

兩種搜尋變體

變體	搜尋方式	查詢格式
`tool_search_tool_regex_20251119`	正則表達式	Python `re.search()` 語法
`tool_search_tool_bm25_20251119`	BM25	自然語言查詢

運作流程

在工具列表中加入 Tool Search 工具
將大部分工具標記為 defer_loading: true
Claude 初始只看到 Tool Search 工具和非延遲載入的工具
當需要額外工具時，Claude 搜尋工具目錄
API 回傳 3-5 個最相關的 tool_reference blocks
這些引用自動展開為完整的工具定義
Claude 從發現的工具中選擇並呼叫

延遲載入

透過 defer_loading: true 標記工具為按需載入：

{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": { ... },
  "defer_loading": true
}

關鍵要點：

Tool Search 工具本身不能設定 defer_loading: true
保持 3-5 個最常用的工具為非延遲載入
至少要有一個非延遲載入的工具

與 MCP 整合

Tool Search 可以與 MCP Connector 搭配使用，在 MCP Toolset 中設定 default_config.defer_loading: true，並可透過 configs 為特定工具覆蓋設定。

自定義 Tool Search 實作

除了使用內建的 Server-side Tool Search，也可以實作自己的搜尋邏輯（如使用 embeddings 或語義搜尋），只需在自定義工具的回應中回傳 tool_reference blocks：

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [
    { "type": "tool_reference", "tool_name": "discovered_tool_name" }
  ]
}

限制和最佳實踐

限制：

最多 10,000 個工具
每次搜尋回傳 3-5 個最相關工具
Regex 查詢最長 200 字元
僅支援 Sonnet 4.0+ 和 Opus 4.0+（不支援 Haiku）

最佳使用場景：

系統中有 10 個以上工具
工具定義消耗超過 10K tokens
使用 MCP 連接多個伺服器（200+ 工具）
工具庫持續增長

最佳化建議：

撰寫清晰、描述性的工具名稱和描述
在描述中使用符合使用者描述任務方式的語義關鍵字
在 system prompt 中加入可用工具類別的描述
監控 Claude 發現了哪些工具，以持續改進描述

總結

Claude 的 Tool Infrastructure 提供了一套完整的工具基礎設施：Fine-grained Tool Streaming 降低了串流延遲；MCP Connector 簡化了與外部 MCP 伺服器的整合；Programmatic Tool Calling 透過在 Code Execution 中批次呼叫工具，大幅減少延遲和 token 消耗；Tool Search 讓系統能夠優雅地擴展到數千個工具。這些能力的組合，讓開發者能夠建構真正大規模的 AI Agent 系統。

Claude Tool Infrastructure 完整指南：從 MCP Connector 到 Tool Search 的全面解析

一、Fine-grained Tool Streaming

核心概念

啟用方式

效能差異

注意事項

二、MCP Connector

核心概念

架構組件

基本使用

工具配置模式

配置合併優先順序

多伺服器支援

回應格式

OAuth 認證

限制

TypeScript SDK MCP Helpers

三、Programmatic Tool Calling

核心概念

運作流程

啟用方式

回應中的 caller 欄位

進階模式

Token 效率

限制

四、Tool Search

核心概念

兩種搜尋變體

運作流程

延遲載入

與 MCP 整合

自定義 Tool Search 實作

限制和最佳實踐

總結

回應中的 `caller` 欄位