Skip to main content

MCP 集成

Myrm 支持 Model Context Protocol (MCP),将外部工具与服务接入 Agent。

什么是 MCP?

MCP 是开放标准,让 AI Agent 通过统一协议连接外部数据源与工具。无需为每个服务写定制集成,可连接任意 MCP 兼容服务。

服务目录(一键连接)

连接主流服务的最快方式。进入 设置 > 通信与集成 > 服务目录,浏览 9 大类别 29 项预配置集成: 每个服务包含:
  • 预配置的连接信息(命令、参数、URL)
  • 引导式凭证输入,附带指向服务商令牌页面的帮助链接
  • Keyless 零配置支持:部分服务(如 Firecrawl 免费层)无需 API Key 即可一键连接
  • 连接前安全扫描(SSRF + 恶意包检测)
  • 中英双语描述
点击服务卡片上的 连接 按钮。Firecrawl 等 Keyless 服务直接点击连接即可,无需填写任何凭证。其他服务填写所需 API Key 即可就绪。

云盘文件同步与导出

Myrm 通过 6 条路径覆盖任意云盘的文件同步与导出需求,无需为每个云盘内置专用连接器: :::tip 与将用户锁定在单一云生态的竞品不同,Myrm 的开放架构让你可以通过多条路径连接任意存储服务。Agent 会根据你的请求自动选择最佳方式。 :::

集成记忆(工作空间同步)

任何已连接的 MCP 服务都可以自动作为知识源。前往 设置 > 集成 > 集成记忆 将外部工作空间数据同步到 AI 的长期记忆中。

工作原理

  1. 通过服务目录 连接 一个服务(如 Notion、GitHub、Gmail)
  2. 在集成记忆区域点击 同步所有
  3. 系统自动完成:
    • 从 MCP 服务的工具目录中自动探测最佳 fetch 工具
    • 使用增量同步拉取数据(自动探测 since/after 参数)
    • 通过 provider::external_id 幂等去重(重复同步安全)
    • 将内容嵌入向量数据库
    • 在知识图谱中构建树形结构
    • 通过 MemoryExtractor 提取高价值特征信息

核心能力

管理已同步数据

  • 状态概览:查看 provider 数量、已索引条目数、Tree 数量
  • 按 Tree 管理:单独同步或移除某个数据 Tree
  • 同步结果详情:每个 provider 的新增/更新/跳过/失败数量

添加自定义 MCP 服务

从 GUI

  1. 进入 设置 > 工具 > MCP
  2. Add Server
  3. 填写配置:
    • Name:显示名
    • Command:启动命令(如 npx @mcp/server-github
    • Arguments:命令行参数
    • Environment Variables:所需环境变量(如 API Key)
  4. 保存 — 服务自动启动,工具对 Agent 可用

从配置文件

mcp_servers.json 添加:

构建自定义 MCP 服务(AI 引导式)

不想从零编写 MCP Server?激活 mcp-builder 技能,让 AI 帮你构建。

使用方式

  1. 进入 设置 > Agent > 技能,启用 mcp-builder 技能
  2. 开始对话并描述需求:“帮我建一个连接 Jira 的 MCP Server 来管理项目”
  3. Agent 按结构化 4 阶段工作流执行:

内置质量保障

  • 安全注解 — 只读操作设置 readOnlyHint: true(自动批准),危险操作设置 destructiveHint: true(警告标记)
  • 错误处理 — 所有 HTTP 请求有超时、重试和可操作的错误消息
  • 分页 — 大结果集自动分页,防止 Token 爆炸
  • 环境变量 — 密钥永不硬编码

Schema 处理

Myrm 自动优化 MCP 工具 Schema 以兼容 LLM:

连接管理

持久会话

每个 MCP 服务在 Agent 生命周期内维持单一会话。工具调用经内部队列串行化 — 每次调用不启子进程,调用间无需重新握手。

执行超时保护

每次 MCP 工具调用均受双层超时机制保护:
  • SDK 层read_timeout_seconds 传入 MCP SDK 会话,防止传输层无响应
  • 包裹层 — 独立的 asyncio.timeout 包裹完整执行(含响应规范化),拦截传输确认后仍卡住的工具
  • 按服务器可配 — 每个服务器可独立设置 connect_timeout(默认 15s)和 execute_timeout(默认 120s,最大 300s)
  • 优雅降级 — 超时后返回描述性错误字符串给 LLM(而非异常),由 Agent 自主决定下一步
  • 枚举自动重试 — 工具发现失败时最多重试 3 次(300ms 退避间隔)

错误透明化

当 MCP 工具报告失败(isError: true)时,完整错误链得到处理且不丢失信息:
  • 服务端错误原文透传 — MCP 服务端返回的原始错误文本完整提取并传递给 LLM
  • 安全消毒 — 自动脱敏凭证(redact_sensitive_text)+ 剥离结构化 framing token(sanitize)防止通过错误信息进行 prompt injection
  • 错误分类 — 错误被分类(network_blocked、timeout、sandbox_ro 等),支持熔断模式和针对性恢复
  • 熔断器 — 终端错误(如网络永久不可达)被注册,后续同类调用快速失败不再重试
  • 结构化诊断 — 记录执行阶段、工具名称、输出预览(首尾截断)、恢复提示,便于调试
  • 前端展示 — 错误以结构化进度步骤呈现在 UI 中,包含 i18n 消息、解决步骤和恢复操作 — 而非原始文本

自愈重连

传输中断(子进程崩溃、SSE/HTTP 断开、空闲超时)时,会话 Actor 原地重连:
  • 有界退避 — 最多 5 次,指数退避(0.5s 至 8s 上限)
  • 预算刷新 — 稳定运行 60s+ 后获得新重试预算
  • 进行中调用显式失败 — 命中中断的调用失败(非幂等工具不静默重试),后续调用在新会话成功
  • 代理稳定 — Agent 持有的工具对象重连后不变,保留 Prompt 前缀缓存命中

传输感知保活

远程传输(SSE、streamable HTTP)经负载均衡/NAT 会静默丢空闲 TCP。会话 Actor 每 180s 发送轻量 list_tools 保活。本地 stdio 不空闲断开,不探测。

连接池

  • 每服务单例 — 每 config-hash 一热连接防泄漏
  • 循环感知 — 事件循环变更自动重建
  • TTL 回收 — 长期空闲连接关闭,按需重建
  • 最后手段重建 — 仅当 Actor 内部重连预算耗尽时池才重建

CancelledError 防护

防止 Python CancelledError 穿透 MCP 通道导致服务进程崩溃。

指标

连接指标(成功率、延迟、错误率)可经诊断 API 查看。

安全

SSRF 防护

MCP 工具 URL 实施 DNS 固定:
  • 解析 IP 检查私有段(10.x、172.16-31.x、192.168.x)
  • 默认阻断 localhost 与 link-local
  • URL 校验防基于重定向的 SSRF

恶意包检测

MCP 工具安装依赖时实时查询 OSV API 检测已知恶意包。

工具审批

MCP 工具与内置工具相同审批流:
  • 只读工具自动执行
  • 写/破坏性工具需用户审批(YOLO 模式除外)
  • 可按 MCP 服务配置自定义审批策略

单工具粒度过滤

配置智能体时,可精确控制每个 MCP 服务中哪些工具可用——细化到单个工具级别。

使用方法

  1. 进入智能体配置(点击聊天窗口中的智能体头像)
  2. MCP 服务 区域,每个已启用的服务显示工具过滤开关
  3. 展开后可查看所有可用工具及风险标注
  4. 通过复选框单独开关每个工具

风险标注

每个工具自动按风险等级分类:

危险工具自动禁用

首次在智能体上启用 MCP 服务时,标记为破坏性的工具会自动排除。需要时可手动重新启用。

过滤摘要

工具过滤器标题显示计数徽章(如 5/20),表示当前激活的工具数量。

多模态工具结果

MCP 可返回截图、图片与结构化数据,原生处理。

图片内容

ImageContent(如 Playwright 截图)直接在聊天渲染:
  • Base64 经流式管道在 Tool Image Gallery 显示
  • 单结果多图(网格 + 灯箱)
  • 不支持视觉的模型由媒体过滤器自动剥离图片

结构化内容

structuredContent(JSON 元数据)提取为 LLM 补充上下文。

工具过滤

按 MCP 服务、按 Agent 控制暴露工具:
  • Include 列表 — 白名单
  • Exclude 列表 — 黑名单
  • 按 Agent 粒度 — 同服务不同 Agent 可见不同工具
  • Agent 配置面板 > MCP > Tool Selection 配置

安全注解

MCP 工具 annotation hints 用于自动风险管理:

默认安全集

首次为 Agent 启用 MCP 服务时,根据注解自动构建安全默认选择
  • 所有 readOnlyHint 工具启用
  • destructiveHint 禁用并横幅提示
  • 可在 Tool Selection GUI 覆盖

工具名隔离

多 MCP 服务时工具名可能冲突。Myrm 对每工具加服务前缀
  • 双下划线分隔 — 可无歧义解析回 (server, tool)
  • 权限安全 — 不与内置工具名冲突
  • 审计可追溯 — 日志标明来源 MCP 服务
  • 对用户透明 — GUI 显示友好原名

动态工具发现

MCP 服务运行时增删改工具时,经 notifications/tools/list_changed 自动检测:
  • 零停机刷新 — 重新拉取工具列表,不中断进行中调用
  • Prompt 缓存稳定 — 面向 Prompt 的代理工具冻结,仅更新内部执行映射
  • 超时保护 — 刷新拉取有界超时
  • 变更日志 — 增删记 WARNING;无变更记 INFO
  • 对 Agent 透明 — 新工具立即可用,移除工具下次调用显式失败
适用于按用户状态动态注册工具的服务(如新建看板时增加工具)。

延迟加载

防工具 Schema 撑爆系统提示词,支持延迟加载
  • 工具已注册但不进初始 Prompt
  • Agent 需要时按需加载
  • 保持系统提示词紧凑、利于缓存

反向 MCP 服务(Connect)

Myrm 也可作为 MCP 服务,将记忆系统暴露给外部 AI Agent(Claude Code、Cursor、Codex、Windsurf、Gemini CLI)。这意味着你的知识在所有 AI 工具间共享。

使用方法

导航至 设置 > 记忆 > Connect 启动连接向导:
  1. 选择 IDE — 从 5 种 MCP 客户端中选择
  2. 生成配置 — 一键生成 Bearer Token 和即粘即用的配置片段
  3. 粘贴到 IDE — 将片段复制到 IDE 的 MCP 设置文件
  4. 完成 — 外部 Agent 立即可访问 Myrm 记忆

暴露的工具

安全

  • Bearer Token 认证 — 每个连接器获得唯一 myrm_mcp_* Token
  • 一键撤销 — 立即失效某连接器的访问权,不影响其他连接器
  • HTTP 传输 — 支持远程网络访问(不限于本地 stdio)
  • Doctor 健康检查 — 在 GUI 中随时验证连接状态

支持的客户端

价值

在 Cursor 中写代码时存储的项目知识,切换到 Myrm WebUI 做研究时立即可用,反之亦然。无需手动同步上下文。

企业 Org MCP(云 SaaS)

云托管企业部署中,IT 管理员可集中管理组织级 MCP:
  1. 进入 设置 → Enterprise → Org MCP(仅 owner/admin)
  2. 添加 HTTP/SSE MCP 服务器(名称、URL、可选 auth header)
  3. 变更通过控制平面自动推送到各成员沙箱
  4. 沙箱休眠时标记 skipped,唤醒后自动补推(最多 3 次重试)
  5. 员工在 设置 → MCP只读方式查看组织托管 MCP,不可修改或删除
  6. 云沙箱禁止 stdio MCP(不允许本地进程型服务器)
:::tip 竞品普遍缺少:组织级 MCP 目录、空闲休眠后的自动同步、IT/员工权限分离。新员工入职首日即可获得与团队一致的内部工具,无需手改 YAML 或 curl。 :::

故障排除

服务无法启动

  1. 检查命令路径可访问
  2. 验证环境变量
  3. 查看 设置 > 工具 > MCP > Logs

工具未出现

  1. 启动后等待 5-10 秒发现
  2. MCP 设置面板点 Refresh
  3. 检查服务工具列表 JSON Schema 有效

连接断开

自愈重连通常透明处理。若因传输中断失败,重试消息即可;持续失败(5 次重连后)检查网络、进程健康、资源限制。

本地编辑器 MCP 探测诊断

当你连接本地限定集成(如 Unreal Engine、Blender)时,Myrm 会先调用 /api/v1/integrations/mcp/probe,再决定是否进入 scan/verify。这样可以避免“反复点连接但不知道根因”的死路流程。 补充保证:
  • shouldBlockConnect=true 时,连接链会立刻终止,不再触发 scan/verify,减少无效报错噪声。
  • 前端按 reasonCode 映射本地化运维文案,应用团队与基础设施团队可基于同一信号协同排障。
  • recommendedMode 支持一键可执行:start_local_editor_mcp / verify_local_network_and_editor 会触发重试探测并在成功后自动续接连接;local_or_tauri 会直接打开本地部署指引。
  • 相比仅返回通用网络错误的竞品,Myrm 提供可机读诊断信号,可直接用于 CI 检查与入职脚本自动化。

为什么迁移到 Myrm 的接入路径更顺滑

  • 在产品内修复,而不是把用户丢回终端:本地 MCP 失败可直接在同一个连接弹窗内修复并继续。对比之下,OpenClaw 的 MCP 页面定位为运维视图,文档明确需要在终端执行 openclaw mcp doctor --probe 做在线探测。
  • 可执行契约替代“仅成功/失败”:Myrm 返回 reasonCode + recommendedMode + shouldBlockConnect,前端可确定性执行(阻断扇出、展示本地化原因、一键建议动作)。Hermes 的 /api/mcp/servers/{name}/test 更偏 ok/error/tools 诊断结构,对新手接入引导的表达力较弱。
  • 架构级降噪:一旦探测判定需阻断,Myrm 立即停止 scan/verify 扇出,避免“明知失败仍继续请求”造成的连锁报错和误导性重试。
  • 未知失败安全可用:未知异常对前台返回脱敏文案,后端日志保留可排障细节,避免把底层异常细节直接暴露给终端用户。

OAuth Token 过期

当 MCP 服务的 OAuth Token 过期(GitHub、Linear、Notion、Slack 集成常见),Myrm 在运行时实时检测认证失败并引导重新授权:
  1. 即时检测 — 工具调用收到 MCP 服务返回的 HTTP 401 时立即捕获(无需等待重连重试耗尽)
  2. 用户通知 — 自动弹出 Toast 通知: 需要重新授权”,附带一键**“立即授权”**按钮
  3. 一键修复 — 点击按钮直接跳转到 设置 → 扩展,完成 OAuth 重新授权
  4. Token 热更新 — 授权完成后,活跃会话通过连接池自动拾取新 Token——无需刷新页面,无需重建连接,下一次工具调用即用新凭证

企业私网 MCP 隧道(仅云部署)

:::info 仅限云托管部署 此功能仅适用于由控制平面管理的云托管 Myrm 部署。本地和 Tauri 用户通过 stdio 直连 MCP 服务器,无需隧道。 ::: 对于 MCP 服务器运行在私有网络(防火墙内、VPC 中或本地机房)的企业客户,Myrm 提供反向隧道——让云端 AI 助手安全访问内网 MCP 服务器,无需暴露任何端口或修改防火墙规则。

工作原理

  1. 部署 tunnel-agent — 在企业内网的任意机器上安装开源的 myrm-tunnel-agent
  2. 注册隧道 — Agent 向控制平面注册并获取安全 Token
  3. 仅出站连接 — tunnel-agent 主动向控制平面发起出站 long-poll 连接,无需开放入站端口
  4. 透明中继 — 当云端 Myrm Agent 调用内网 MCP 工具时,请求通过隧道中继到内部 MCP 服务器,响应透明返回

安全特性

架构

配置步骤

  1. 在组织管理面板注册隧道(设置 → 组织 → MCP → 添加隧道
  2. 使用提供的 Token 和内部 MCP 服务器地址部署 myrm-tunnel-agent
  3. 隧道以 org 级 MCP 服务器形式出现——像其他 MCP 服务器一样分配给 Agent 使用

企业身份认证 — IdP 群组 MCP 权限管理(仅云部署)

:::info 仅限云托管部署 此功能仅适用于已配置 OIDC SSO 的云托管 Myrm 部署。本地和 Tauri 用户在本地设置中直接管理 MCP 访问。 ::: 对于使用身份提供商(Okta、Entra ID、Google Workspace 等)的企业客户,Myrm 自动将 IdP 群组成员关系映射到 组织 MCP 服务器访问权限——IT 管理员可以控制哪些团队看到哪些工具,无需逐人手动配置。

工作原理

  1. OIDC groups claim — 用户通过 SSO 登录时,Myrm 从 OIDC 响应中提取 groups claim 并存储到用户的组织成员记录
  2. Per-MCP 群组白名单 — 组织管理员为每个 org MCP 服务器配置可选的 acl_groups 列表(留空 = 全员可见)
  3. 自动过滤 — 当 MCP 配置推送到用户沙箱时,仅推送用户 IdP 群组与服务器 ACL 群组有交集的服务器
  4. 登录自动刷新 — 群组成员关系在每次 OIDC 登录时自动刷新,无需手动同步

配置群组权限

  1. 进入 设置 → 组织 → MCP 服务器
  2. 创建或编辑 MCP 服务器时,在访问群组字段输入 IdP 群组名称(逗号分隔)
  3. 留空则该服务器对所有组织成员可见
  4. IdP 群组匹配至少一个配置群组的成员将看到并使用该服务器

离职处理

通过组织管理面板执行员工离职操作时,Myrm 立即向其沙箱推送空的 MCP 服务器列表——即时撤销所有组织 MCP 访问权限,无需手动清理。

安全特性