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

# Tool 配置

Editor 将 Tool 选择存储为 Agent 版本的一部分。已存储配置可以添加已注册的 Tool、集成 Provider 提供的 Tool，以及 Model Context Protocol（MCP）client 提供的 Tool。

有关 Studio 工作流和常见用法，请参阅 [Editor Tool](https://mastra.zisheng.pro/docs/editor/overview)。

## Tool 来源

| 来源                                                                         | 描述                                                             |
| -------------------------------------------------------------------------- | -------------------------------------------------------------- |
| 已注册的 Tool                                                                  | 在 Mastra 运行时 Tool 注册表中注册的 Tool                                 |
| MCP client                                                                 | 已存储的本地或远程 MCP server 配置所公开的 Tool                               |
| 集成 Tool                                                                    | 通过旧版集成 Provider 配置解析的 Tool                                     |
| [Tool Provider](https://mastra.zisheng.pro/reference/editor/tool-provider) | 通过在 `MastraEditor` 上注册的 Provider（例如 Composio 或 Arcade）解析的 Tool |

代码定义的 Agent 会保留其现有 Tool。[`editor` 覆盖设置](https://mastra.zisheng.pro/reference/agents/agent)控制 Editor 可以添加和移除 Tool，还是只能更改描述。

## 描述覆盖

每个选中的 Tool 都可以存储 Agent 专用描述。该描述会更改模型看到的内容，而不会修改原始 Tool 定义。

在仅描述模式下，Editor 只对代码定义 Agent 上已存在的 Tool 应用覆盖。对于 MCP Tool，Agent 级描述的优先级高于 MCP client 上存储的描述。

如果两个来源解析出相同的 Tool ID，后面的来源会完整替换前面的 Tool，包括其描述。请参阅[解析顺序](#resolution-order)。

## 条件式 Tool 集

Editor 可以为 `tools`、`mcpClients`、`integrationTools` 和 `toolProviders` 字段存储条件式变体。运行时，会根据 request context 值对匹配的变体进行浅合并。

规则语言使用与 [prompt block 显示条件](https://mastra.zisheng.pro/reference/editor/prompt-blocks)相同的 operator 和嵌套行为。

条件应用于 Tool 字段变体或 MCP client 引用。当前 Editor resolver 不会对已存储 Tool 条目中每个 Tool 的 `rules` 值求值。

## 已存储的 MCP client

`editor.mcp` 命名空间管理可复用的 MCP client 配置。CRUD 方法签名请参阅 [`mcp` 命名空间](https://mastra.zisheng.pro/reference/editor/mastra-editor)。

`@mastra/mcp` 是 `@mastra/editor` 的可选 peer dependency。请先安装它再配置已存储的 MCP client，以便 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 定义不接受任意 header。当 request context 中存在保留值 `mastra__authToken` 时，Editor 会将其作为 `Authorization: Bearer` header 转发。

### 筛选

可在两个层级将 MCP Tool 加入 allowlist：

1. **Server 级别**：已存储 server 的 `tools` map 会限制每个使用该 client 的 Agent 可用的 Tool。
2. **Agent 级别**：Agent 的 MCP client 引用会限制该 Agent 剩余可用的 Tool。

Agent 级 Tool 名称可以使用带命名空间或不带命名空间的名称。显式的空 `tools` map 会选择所有 Tool。使用当前 resolver 时，从 Agent 级 MCP 引用中省略 `tools` 将不会选择任何 Tool。

### 命名空间

MCP Tool 使用 `serverName_toolName` ID 来避免冲突。`docs` server 中的 `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，而不是合并其字段。