# Tool Calling 與 MCP 整合

在 PrivAI 中，`/v1/chat/completions` 除了支援一般對話生成外，也支援模型在回應過程中使用工具（Tool Calling），以擴展 AI Agent 的能力範圍。  
透過工具呼叫機制，模型不再只能依賴自身參數知識進行回答，而可以根據任務需求呼叫外部功能，例如查詢外部資料、存取第三方系統、執行檢索流程，或串接其他應用服務。  
在 PrivAI 中，Tool Calling 能力**透過 MCP（Model Context Protocol）定義的工具整合方式提供**。目前 Chat Completions API 僅支援以 **MCP Tool** 形式傳入工具，**不支援**直接傳入自定義的 Function Tool 定義。模型在推理過程中呼叫 MCP Tool 時，底層會以 function-calling 格式進行，並由 PrivAI 內部負責工具定義的轉換與呼叫路由。

#### Tool Calling 的目的

Tool Calling 的核心目的，是讓模型在生成答案的同時，能根據上下文判斷是否需要借助額外工具完成任務。  
這種設計特別適合建構 AI Agent、企業內部助手、流程自動化工具與多步驟任務系統。  
常見使用情境包括：

- 查詢外部 API 或企業內部服務

- 存取外部知識來源或資料平台

- 執行特定系統操作或業務流程

- 讓模型具備更完整的 Agent tool-use 能力

在 PrivAI 中，開發者可於呼叫 Chat Completions API 時，透過 `tools` 欄位提供 MCP Tool 定義，讓模型在推理過程中選擇是否使用這些工具。MCP Tool 的欄位說明請參考 [Chat Completions](https://privstation-docs.apmic.ai/latest/privai-400/chat-completions.md)。

---

#### MCP 是什麼

MCP（Model Context Protocol）是一種用於定義模型如何存取外部工具與資源的協定。  
透過 MCP，開發者可以用一致的方式描述工具介面，使模型能在推理過程中理解有哪些工具可用、各工具需要哪些參數，以及工具執行後的結果如何回傳。  
相較於單純手工定義 function schema，MCP 的優點在於：

- 可用標準化方式整合外部工具

- 有利於 Agent 系統擴充更多外部能力

- 可與多種支援 MCP 的工具服務互通

- 有助於建立可維護、可擴展的工具生態

---

#### MCP Tool 的執行方式

1. PrivAI 依 `tools` 中每個 MCP Tool 定義連線對應的 MCP server，取得工具清單；若有設定 `allowed_tools`，只暴露清單內的工具。

1. 每個工具會以 `{server_label}--{工具名稱}` 的名稱提供給模型，例如 `deepwiki--read_wiki_structure`。若同一請求中有多個 MCP Tool 使用相同的 `server_label`，會依序加上 `_1`、`_2` 後綴（例如 `deepwiki_1--read_wiki_structure`）。在串流的 `tool_calls` 中看到的就是這個名稱。

1. 模型決定呼叫工具時，PrivAI 會執行工具，並將結果交回模型，重複直到模型不再呼叫工具。Stream 模式下，每個工具呼叫會回傳一個 `role = "tool"` 的 chunk 表示工具輸出結果。

1. 工具執行失敗或逾時時，PrivAI 會把 `Tool error: ...` 當作工具結果交回模型，由模型決定如何回覆，不會讓整個請求失敗。

:::info[💡]

建議先用 [探索 MCP 工具](https://privstation-docs.apmic.ai/latest/privai-400/探索-mcp-工具.md) 確認 MCP server 提供哪些工具與其正確名稱，再填入 `allowed_tools`，避免一次把大量工具暴露給模型。

:::

- MCP server 無法連線或 `server_url` 不是 `http://` / `https://` 開頭時，整個請求會失敗。

- MCP Tool 的 `authorization` 值會原樣放入 `Authorization` header，且不可與 `headers` 中的 `Authorization` 同時提供。

---

#### 本階段支援範圍

目前 PrivAI 在 Chat Completions API 中支援 MCP Tool，範圍如下：

- 支援於 `tools` 欄位中傳入 MCP Tool 定義

- 支援使用與 Responses API tools 欄位相容的 MCP Tool 格式

- 僅支援 **remote MCP / MCP connector**

- 僅支援透過 **Streamable HTTP** 連接的外部 MCP server

本階段 **不支援** 的範圍包括：

- 直接傳入自定義的 Function Tool 定義

- local MCP server

- SSE 型態的 MCP server

- 非 HTTP 型態的 MCP 連線方式

---

#### Tool Calling 與 Tenant Scope 的關係

PrivAI 支援多租戶資料隔離機制，系統會依據呼叫 API 所使用的 API Key，自動套用對應的 Tenant Scope（見「Tenant Scope 與資料隔離」章節）。  
即使在使用 Tool Calling 或 MCP Tool 的情境下，API 請求本身仍應遵守既有的租戶權限與資料範圍限制。
