Tool 配置

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

有关 Studio 工作流和常见用法，请参阅 Editor Tool。

Tool 来源

来源	描述
已注册的 Tool	在 Mastra 运行时 Tool 注册表中注册的 Tool
MCP client	已存储的本地或远程 MCP server 配置所公开的 Tool
集成 Tool	通过旧版集成 Provider 配置解析的 Tool
Tool Provider	通过在 MastraEditor 上注册的 Provider（例如 Composio 或 Arcade）解析的 Tool

代码定义的 Agent 会保留其现有 Tool。editor 覆盖设置控制 Editor 可以添加和移除 Tool，还是只能更改描述。

描述覆盖

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

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

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

条件式 Tool 集

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

规则语言使用与 prompt block 显示条件相同的 operator 和嵌套行为。

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

已存储的 MCP client

editor.mcp 命名空间管理可复用的 MCP client 配置。CRUD 方法签名请参阅 mcp 命名空间。

@mastra/mcp 是 @mastra/editor 的可选 peer dependency。请先安装它再配置已存储的 MCP client，以便 Editor 在运行时加载其 Tool：

npm

npm install @mastra/mcp

pnpm

pnpm add @mastra/mcp

Yarn

yarn add @mastra/mcp

Bun

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，而不是合并其字段。