MCP Specification · 2026-07-28 · zh-TW

工具

Tools

Server 向模型暴露可執行函式，支援 JSON Schema、structuredContent、MRTR、狀態 handle 與安全控制。

MCP 允許 server 暴露可由 language model 呼叫的 Tools。Tool 可以查詢 database、呼叫 API、執行計算或進行其他外部動作；每個 tool 由唯一 name 與 JSON Schema metadata 描述。

請求中繼資料（Request metadata）

本頁範例為簡潔省略 _meta；實際每個 request 仍 MUST（必須）包含 io.modelcontextprotocol/protocolVersion 與 io.modelcontextprotocol/clientCapabilities。io.modelcontextprotocol/clientInfo 為選用欄位，但 client SHOULD（應該）在未特別停用時提供。

使用者互動模型（User Interaction Model）

Tools 是 model-controlled primitive：模型可以依 context 與 user prompt 自動 discover / invoke tools。不過 protocol 不強制 UI。

人類介入（Human in the loop）

基於 trust & safety，SHOULD（應該）始終保留能拒絕 tool invocation 的 human-in-the-loop。應用程式 SHOULD（應該）清楚顯示哪些 tools 暴露給模型、在 tool 被呼叫時提供明顯指示，並以 confirmation 讓使用者審核操作。

能力宣告（Capabilities）

支援 tools 的 server MUST（必須）宣告：

{
  "capabilities": {
    "tools": {"listChanged": true}
  }
}

宣告 tools capability 的 server MUST（必須）回應 tools/list。集合 MAY（可以）為空，也 MAY（可以）隨時間改變，並 MAY（可以）依每個 request 的 authorization 不同，但 MUST NOT（不得）因 connection state 或同 connection 其他 request 的副作用而變化。

Server SHOULD（應該）以 deterministic order 回傳 tools；在集合未變時保持相同順序，有利 client cache 與 LLM prompt-cache hit rate。

列出工具（Listing Tools）

tools/list 支援 pagination 與 caching。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {"cursor": "optional-cursor-value"}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "tools": [{
      "name": "get_weather",
      "description": "Get current weather",
      "inputSchema": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"]
      }
    }],
    "ttlMs": 300000,
    "cacheScope": "public"
  }
}

呼叫工具（Calling Tools）

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {"location": "New York"}
  }
}

成功結果以 resultType: "complete" 回傳，可包含 content、structuredContent 與 isError。

需要額外輸入（Input Required）

Server MAY（可以）對 tools/call 回 InputRequiredResult，以 MRTR 要求 Elicitation、Sampling 或 Roots 等額外 input。Client retry 時帶回 inputResponses 與 server 提供的 requestState，而新的 JSON-RPC id MUST（必須）與初始 request 不同。

清單變更通知（List Changed Notification）

若 server 宣告 listChanged，當 tool 清單改變時，對已用 subscriptions/listen 訂閱 toolsListChanged: true 的 client SHOULD（應該）送出 notifications/tools/list_changed。

工具定義（Tool Definition）

name：唯一 tool identifier。
title：選用的 UI display name。
description：功能說明。
icons：選用 UI icons。
inputSchema：MUST（必須）是有效 JSON Schema object（不得為 null）；未指定 $schema 時預設 2020-12。沒有參數的 tool 建議用 {"type":"object","additionalProperties":false}。
outputSchema：選用 JSON Schema；未指定 $schema 時同樣預設 2020-12。
annotations：描述 tool behavior 的選用 hints；client 除非信任 server，MUST（必須）把 annotations 視為 untrusted。

工具名稱（Tool Names）

名稱 SHOULD（應該）長度為 1–128 characters。
名稱 SHOULD（應該）視為 case-sensitive。
名稱 SHOULD（應該）只使用 ASCII letters、digits、underscore、hyphen、dot。
名稱 SHOULD NOT（不應）包含 spaces、commas 或其他 special characters。
名稱在單一 server 內 SHOULD（應該）唯一。

聚合多個 servers 的 client / proxy MAY（可以）遇到同名 tool，並 SHOULD（應該）採 disambiguation strategy，例如加上 server identifier prefix。serverInfo.name 不保證唯一，SHOULD NOT（不應）單獨依賴它做 disambiguation。

`x-mcp-header`

x-mcp-header 可在 tool inputSchema property 上指定 Streamable HTTP 要鏡射的 Mcp-Param-{Name} header。限制與 Streamable HTTP 頁一致：

value MUST NOT（不得）為空，且 MUST（必須）符合 RFC 9110 HTTP field-name token syntax。
MUST NOT（不得）包含 CR/LF 或其他 control characters。
同一 inputSchema 內 MUST（必須）case-insensitively unique。
MUST（必須）只套用於 integer、string、boolean primitive；number 不允許，integer MUST（必須）落在 JavaScript safe integer range。
MUST（必須）只套用於從 schema root statically reachable 的 property；完整 path rules 依 Streamable HTTP 頁。

Streamable HTTP client MUST（必須）拒絕含無效 x-mcp-header 的 tool definition，亦即 MUST（必須）從 tools/list 結果排除該 tool，並 SHOULD（應該）記錄包含 tool name 與原因的 warning。stdio 等 transport MAY（可以）忽略 annotation。

不要把秘密鏡射到 HTTP header

Server developer SHOULD NOT（不應）對 passwords、API keys、tokens、PII 使用 x-mcp-header，因為 header 可被 network intermediaries 看見。

工具結果（Tool Result）

Tool result 可以同時提供 unstructured content 與 structured structuredContent；所有 text/image/audio/resource-link/embedded-resource content type 都可帶 Resources 所定義的 annotations。

Tool MAY（可以）回傳 Resource Link；這些 links 不保證一定出現在 resources/list。
Resource MAY（可以）直接 embedded 在 tool result 中；使用 embedded resources 的 server SHOULD（應該）實作 resources capability。
structuredContent 可以是任何 JSON value；若 tool 定義 outputSchema，server MUST（必須）提供符合 schema 的 structured result，client SHOULD（應該）驗證。
為向後相容，server 回 structured content 時 SHOULD（應該）也以 TextContent 提供 serialized JSON。

具狀態工具（Stateful Tools）

非規範性設計指引

MCP wire protocol 沒有 state handle 這個概念；handle 在協定上只是一個普通 result value 與後續 tool argument。以下是 tool design guidance，而不是新的 protocol requirement。

2026-07-28 沒有 protocol-level session，因此跨 calls 的 state 不應依賴 connection。需要 shopping cart、browser context、transaction 等 state 時，server 可以由 creation tool 明確回傳 opaque handle，後續 call 再把 handle 當普通 argument 傳回。

Handle design 應考慮：

Authorization：authenticated server 應在每次 call 重新驗證 caller 對 handle 的權限；unauthenticated handle 實質是 bearer token，應有足夠 entropy 與 bounded lifetime。
Opacity：避免讓 handle 暴露可猜測 internal structure。
Lifetime：應在 creation tool description 說明 retention / expiry policy。
Expiry error：expired / unknown handle 應回可供 model recovery 的 tool execution error。

錯誤處理（Error Handling）

Tools 有兩類錯誤：

Protocol errors：unknown tool、malformed request、server error，以標準 JSON-RPC error 回傳，例如 -32602。
Tool execution errors：API failure、input validation、business logic error，回正常 tool result 並設 isError: true。

Client MAY（可以）把 protocol errors 提供給 LLM，但這類錯誤通常較難由模型自我修正；client SHOULD（應該）把 tool execution errors 提供給 LLM，以便模型調整參數後重試。

安全考量（Security Considerations）

Server MUST（必須）驗證 tool inputs、實作 access control、rate limit invocations 並 sanitize outputs。Client SHOULD（應該）：

敏感操作要求 user confirmation。
呼叫前顯示 tool inputs，避免惡意或意外 data exfiltration。
把 result 交給 LLM 前先驗證。
依規範的 $ref resolution rules 驗證 input/output schema。
實作 timeout 與 audit logging。