# Tool Calling 與 MCP 整合

### Tool Calling 與 MCP 整合

在 PrivAI 中，`/v1/chat/completions` 除了支援一般對話生成外，也支援模型在回應過程中使用工具（Tool Calling），以擴展 AI Agent 的能力範圍。

透過工具呼叫機制，模型不再只能依賴自身參數知識進行回答，而可以根據任務需求呼叫外部功能，例如查詢外部資料、存取第三方系統、執行檢索流程，或串接其他應用服務。

本節所述的 Tool Calling 能力，包含一般 Function Tool，以及透過 MCP（Model Context Protocol）定義的工具整合方式。

#### Tool Calling 的目的

Tool Calling 的核心目的，是讓模型在生成答案的同時，能根據上下文判斷是否需要借助額外工具完成任務。

這種設計特別適合建構 AI Agent、企業內部助手、流程自動化工具與多步驟任務系統。

常見使用情境包括：

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

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

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

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

在 PrivAI 中，開發者可於呼叫 Chat Completions API 時，透過 `tools` 欄位提供工具定義，讓模型在推理過程中選擇是否使用這些工具。

---

#### MCP 是什麼

MCP（Model Context Protocol）是一種用於定義模型如何存取外部工具與資源的協定。

透過 MCP，開發者可以用一致的方式描述工具介面，使模型能在推理過程中理解有哪些工具可用、各工具需要哪些參數，以及工具執行後的結果如何回傳。

相較於單純手工定義 function schema，MCP 的優點在於：

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

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

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

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

---

#### 本階段支援範圍

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

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

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

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

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

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

- local MCP server

- SSE 型態的 MCP server

- 非 HTTP 型態的 MCP 連線方式

若傳入未支援的 MCP 類型，系統將依統一錯誤格式回傳錯誤資訊。

---

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

PrivAI 支援多租戶資料隔離機制，系統會依據呼叫 API 所使用的 API Key，自動套用對應的 Tenant Scope。

即使在使用 Tool Calling 或 MCP Tool 的情境下，API 請求本身仍應遵守既有的租戶權限與資料範圍限制。
