> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# Tool 設定

Editor 會將 Tool 選擇儲存為 Agent 版本的一部分。已儲存的設定可以加入已註冊的 Tool、整合 Provider 提供的 Tool，以及 Model Context Protocol (MCP) 使用者端提供的 Tool。

Studio 工作流程與常見用途請參閱 [Editor Tool](https://mastra.zisheng.pro/zh-TW/docs/editor/overview)。

## Tool 來源

| 來源                                                                               | 說明                                                           |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 已註冊的 Tool                                                                        | 在 Mastra 執行階段 Tool 登錄表中註冊的 Tool                              |
| MCP 使用者端                                                                         | 已儲存的本機或遠端 MCP 伺服器設定所公開的 Tool                                 |
| 整合 Tool                                                                          | 由舊版整合 Provider 設定解析的 Tool                                    |
| [Tool Provider](https://mastra.zisheng.pro/zh-TW/reference/editor/tool-provider) | 由 `MastraEditor` 上註冊的 Provider（例如 Composio 或 Arcade）解析的 Tool |

在程式碼中定義的 Agent 會保留既有 Tool。[`editor` 覆寫設定](https://mastra.zisheng.pro/zh-TW/reference/agents/agent)會控制 Editor 可新增及移除 Tool，或只能變更說明。

## 覆寫說明

每個已選取的 Tool 都可儲存 Agent 專屬說明。此說明會變更模型看到的內容，而不會修改原始 Tool 定義。

在僅限說明模式中，Editor 只會將覆寫套用至程式碼定義的 Agent 中既有的 Tool。對 MCP Tool 而言，Agent 層級的說明優先於 MCP 使用者端儲存的說明。

如果兩個來源解析出相同的 Tool ID，後面的來源會取代前面的完整 Tool，包括其說明。請參閱[解析順序](#resolution-order)。

## 條件式 Tool 集合

Editor 可為 `tools`、`mcpClients`、`integrationTools` 與 `toolProviders` 欄位儲存條件式變體。在執行階段，系統會依據 request context 值，將符合條件的變體進行淺層合併。

規則語言使用與[提示詞區塊顯示條件](https://mastra.zisheng.pro/zh-TW/reference/editor/prompt-blocks)相同的運算子與巢狀行為。

條件會套用至 Tool 欄位變體或 MCP 使用者端參照。目前的 Editor 解析器不會評估已儲存 Tool 項目中個別 Tool 的 `rules` 值。

## 已儲存的 MCP 使用者端

`editor.mcp` 命名空間可管理可重複使用的 MCP 使用者端設定。CRUD 方法簽章請參閱 [`mcp` 命名空間](https://mastra.zisheng.pro/zh-TW/reference/editor/mastra-editor)。

`@mastra/mcp` 是 `@mastra/editor` 的選用對等相依套件。設定已儲存的 MCP 使用者端之前請先安裝，讓 Editor 能在執行階段載入其 Tool：

**npm**:

```bash
npm install @mastra/mcp
```

**pnpm**:

```bash
pnpm add @mastra/mcp
```

**Yarn**:

```bash
yarn add @mastra/mcp
```

**Bun**:

```bash
bun add @mastra/mcp
```

### 傳輸方式

| 傳輸方式    | 已儲存的設定                                    |
| ------- | ----------------------------------------- |
| `stdio` | `command`，可搭配選用的 `args`、`env` 與 `timeout` |
| HTTP    | `url`，可搭配選用的 `timeout`                    |

已儲存的 HTTP 定義不接受任意標頭。request context 中存在保留的 `mastra__authToken` 值時，Editor 會將它以 `Authorization: Bearer` 標頭轉送。

### 篩選

MCP Tool 可在兩個層級設定允許清單：

1. **伺服器層級**：已儲存伺服器的 `tools` 對應表會限制每個使用該使用者端的 Agent 可用的 Tool。
2. **Agent 層級**：Agent 的 MCP 使用者端參照會進一步限制該 Agent 可用的剩餘 Tool。

Agent 層級的 Tool 名稱可以使用有命名空間或不含命名空間的名稱。明確指定空的 `tools` 對應表會選取所有 Tool。使用目前的解析器時，若 Agent 層級的 MCP 參照省略 `tools`，則不會選取任何 Tool。

### 命名空間

MCP Tool 使用 `serverName_toolName` ID 以避免衝突。`docs` 伺服器中的 `search` Tool 會變成 `docs_search`。

## 解析順序

Editor 會依下列順序合併 Tool 記錄。後面的記錄會取代 ID 相同的前面記錄。

1. 程式碼定義的 Tool
2. 已註冊且已儲存的 Tool
3. MCP Tool
4. 舊版整合 Tool
5. V1 Tool Provider 的 Tool

獨立儲存的 Agent 使用相同順序，但不包含程式碼定義的 Tool。靜態程式碼 Agent 的覆寫會在舊版整合 Tool 之後停止。

請盡可能讓不同來源使用唯一的 Tool ID。若發生衝突，系統會取代前面的完整 Tool，而非合併其欄位。