使用 MCP 工具
添加并连接 MCP 服务器后，其提供的工具会自动注册到 Agent 的可用工具集中。本页介绍工具如何被发现、命名、使用，以及如何进行精细管理。
工具自动发现
当 MCP 服务器成功连接后，Elftia 会自动执行以下操作：
- 工具列表获取 — 调用服务器的
listTools接口获取所有可用工具 - 格式注册 — 将工具注册到内部工具系统中
- 缓存存储 — 工具列表缓存 5 分钟，避免频繁请求
缓存行为
| 行为 | 说明 |
|---|---|
| 缓存时间 | 5 分钟（300 秒） |
| 缓存范围 | 按服务器 ID 分别缓存 |
| 自动刷新 | 缓存过期后下次请求时自动获取最新列表 |
| 手动刷新 | 在 MCP 服务器列表中点击 发现 按钮强制刷新 |
| 重新连接 | 断开并重连服务器会清除该服务器的缓存 |
手动发现
在 MCP 服务器页面，你可以对每个服务器执行 发现 操作，查看其提供的完整能力清单：
- 工具（Tools） — Agent 可调用的功能
- 资源（Resources） — 服务器提供的数据资源（如文件、数据库表等）
- 提示词（Prompts） — 服务器预定义的提示词模板
工具命名格式
每个 MCP 工具在 Agent 中的标识符格式为：
mcp__<服务器名>__<工具名>
命名规则：
- 服务器名和工具名中的非字母数字字符会被替换为下划线
_ - 使用双下划线
__作为分隔符
示例：
| 服务器名 | 原始工具名 | Agent 中的标识符 |
|---|---|---|
filesystem | read_file | mcp__filesystem__read_file |
brave-search | brave_web_search | mcp__brave_search__brave_web_search |
github | create_issue | mcp__github__create_issue |
MCP 使用模式
Elftia 提供三种 MCP 使用模式，控制工具在对话中的可用性：
| 模式 | 说明 | 适用场景 |
|---|---|---|
| 自动（默认） | 所有已启用服务器的工具自动可用 | 日常使用，希望 Agent 自主选择工具 |
| 手动 | 每次对话前选择使用哪些服务器 | 需要精确控制工具范围的场景 |
| 禁用 | 完全关闭 MCP 工具 | 不需要外部工具的简单对话 |
自动模式
默认模式。所有状态为活跃（isActive）的 MCP 服务器的工具会自动加入 Agent 的工具列表。Agent 会根据对话内容自主判断是否需要调用某个工具。
手动模式
在手动模式下，你可以精确选择本次对话中使用哪些 MCP 服务器：
- 在对话设置中切换 MCP 模式为 手动
- 从可用服务器列表中勾选需要的服务器
- 只有选中的服务器的工具才会在对话中可用
禁用模式
完全关闭 MCP 功能，Agent 不会加载任何 MCP 工具。
工具格式适配
Elftia 支持多种 LLM 提供商，不同提供商的工具调用格式不同。MCP 工具会被自动转换为当前提供商要求的格式：
| 提供商 | 工具格式 | 说明 |
|---|---|---|
| OpenAI / DeepSeek / 国产大模型 | function 格式 | { type: "function", function: { name, description, parameters } } |
| Anthropic (Claude) | tool 格式 | { name, description, input_schema } |
| Google (Gemini) | functionDeclarations 格式 | { functionDeclarations: [{ name, description, parameters }] } |
这一转换完全自动，无需手动干预。
工具在对话中的展示
当 Agent 调用 MCP 工具时，对话界面中会以专门的工具调用卡片展示：
- 调用中 — 显示工具名称和传入的参数
- 返回结果 — 展示工具返回的内容（文本、图片等）
- 错误信息 — 如果调用失败，显示错误详情
工具返回内容类型
MCP 工具可以返回以下类型的内容：
| 内容类型 | 说明 |
|---|---|
text | 文本结果，直接显示 |
image | 图片数据（Base64 编码），以图片形式渲染 |
audio | 音频数据（Base64 编码），以播放器形式渲染 |
调用超时
单次工具调用的超时时间为 2 分钟（120 秒）。如果工具在此时间内未返回结果，调用将被终止并返回超时错误。
关联 MCP 服务器与 Agent
你可以将特定的 MCP 服务器关联到特定的 Agent，实现更精细的工具分配：
关联操作
- 在 MCP 服务器列表中，点击目标服务器的 管理 按钮
- 在弹出的对话框中查看已关联的 Agent 列表
- 点击 添加到 Agent 展开可用 Agent 列表
- 选择要关联的 Agent
管理关联
在管理对话框中，你可以：
| 操作 | 说明 |
|---|---|
| 查看已关联 Agent | 显示当前关联了哪些 Agent |
| 启用/禁用 | 通过开关控制工具对特定 Agent 的可用性 |
| 解除关联 | 点击删除按钮移除 Agent 关联 |
| 搜索 Agent | 在添加时搜索过滤 Agent 列表 |
禁用特定工具
如果某个 MCP 服务器提供的工具过多，或某些工具你不希望 Agent 使用，可以选择性禁用：
- 服务器级别的
disabledTools列表记录了被禁用的工具名称 - 被禁用的工具不会出现在 Agent 的工具列表中
- 禁用操作通过服务器更新接口完成
信任管理
MCP 服务器分为两个信任级别：
| 级别 | 说明 | 行为差异 |
|---|---|---|
| 未受信任（默认） | 新添加的服务器默认为未受信任 | 正常使用，但可能受到额外限制 |
| 受信任 | 用户明确标记为可信的服务器 | 完全信任其工具调用 |
标记为受信任
在服务器管理中更新服务器的 isTrusted 属性即可将其标记为受信任。受信任的服务器在自动审批工具调用时享有更高权限。
启用与禁用服务器
每个 MCP 服务器都有一个 isActive 开关：
- 启用 — 服务器参与工具加载（自动模式下会自动连接）
- 禁用 — 服务器被跳过，不参与工具加载，不消耗连接资源
禁用服务器不会删除其配置，随时可以重新启用。
故障排除
工具调用返回错误
症状：Agent 调用工具后显示错误信息。
解决方案：
- 检查工具所需的 API Key 是否正确配置
- 确认工具参数是否符合预期格式
- 查看服务器是否仍在运行（对 Stdio 服务器而言）
- 尝试重新连接服务器
工具列表为空
症状：服务器已连接但未发现任何工具。
解决方案：
- 使用 发现 功能手动获取工具列表
- 确认服务器版本是否支持
tools/list接口 - 检查服务器的日志输出是否有错误
Agent 未使用可用工具
症状：工具已注册但 Agent 在对话中不调用它。
解决方案：
- 在提示词中明确提及工具名称或相关功能
- 检查是否处于禁用模式
- 确认工具的描述信息是否准确，以便 Agent 判断何时使用
- 减少可用工具数量，避免选择困难
下一步
- 添加 MCP 服务器 — 配置更多 MCP 服务器
- JSON 批量导入 — 通过 JSON 快速导入配置
- MCP 概览 — 回顾 MCP 核心概念