MCP 集成
Myrm 支持 Model Context Protocol (MCP),将外部工具与服务接入 Agent。什么是 MCP?
MCP 是开放标准,让 AI Agent 通过统一协议连接外部数据源与工具。无需为每个服务写定制集成,可连接任意 MCP 兼容服务。服务目录(一键连接)
连接主流服务的最快方式。进入 设置 > 通信与集成 > 服务目录,浏览 9 大类别 29 项预配置集成:
每个服务包含:
- 预配置的连接信息(命令、参数、URL)
- 引导式凭证输入,附带指向服务商令牌页面的帮助链接
- Keyless 零配置支持:部分服务(如 Firecrawl 免费层)无需 API Key 即可一键连接
- 连接前安全扫描(SSRF + 恶意包检测)
- 中英双语描述
云盘文件同步与导出
Myrm 通过 6 条路径覆盖任意云盘的文件同步与导出需求,无需为每个云盘内置专用连接器:
:::tip
与将用户锁定在单一云生态的竞品不同,Myrm 的开放架构让你可以通过多条路径连接任意存储服务。Agent 会根据你的请求自动选择最佳方式。
:::
集成记忆(工作空间同步)
任何已连接的 MCP 服务都可以自动作为知识源。前往 设置 > 集成 > 集成记忆 将外部工作空间数据同步到 AI 的长期记忆中。工作原理
- 通过服务目录 连接 一个服务(如 Notion、GitHub、Gmail)
- 在集成记忆区域点击 同步所有
- 系统自动完成:
- 从 MCP 服务的工具目录中自动探测最佳 fetch 工具
- 使用增量同步拉取数据(自动探测
since/after参数) - 通过
provider::external_id幂等去重(重复同步安全) - 将内容嵌入向量数据库
- 在知识图谱中构建树形结构
- 通过 MemoryExtractor 提取高价值特征信息
核心能力
管理已同步数据
- 状态概览:查看 provider 数量、已索引条目数、Tree 数量
- 按 Tree 管理:单独同步或移除某个数据 Tree
- 同步结果详情:每个 provider 的新增/更新/跳过/失败数量
添加自定义 MCP 服务
从 GUI
- 进入 设置 > 工具 > MCP
- 点 Add Server
- 填写配置:
- Name:显示名
- Command:启动命令(如
npx @mcp/server-github) - Arguments:命令行参数
- Environment Variables:所需环境变量(如 API Key)
- 保存 — 服务自动启动,工具对 Agent 可用
从配置文件
在mcp_servers.json 添加:
构建自定义 MCP 服务(AI 引导式)
不想从零编写 MCP Server?激活 mcp-builder 技能,让 AI 帮你构建。使用方式
- 进入 设置 > Agent > 技能,启用
mcp-builder技能 - 开始对话并描述需求:“帮我建一个连接 Jira 的 MCP Server 来管理项目”
- 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 防护
防止 PythonCancelledError 穿透 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 服务中哪些工具可用——细化到单个工具级别。使用方法
- 进入智能体配置(点击聊天窗口中的智能体头像)
- 在 MCP 服务 区域,每个已启用的服务显示工具过滤开关
- 展开后可查看所有可用工具及风险标注
- 通过复选框单独开关每个工具
风险标注
每个工具自动按风险等级分类:危险工具自动禁用
首次在智能体上启用 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 启动连接向导:- 选择 IDE — 从 5 种 MCP 客户端中选择
- 生成配置 — 一键生成 Bearer Token 和即粘即用的配置片段
- 粘贴到 IDE — 将片段复制到 IDE 的 MCP 设置文件
- 完成 — 外部 Agent 立即可访问 Myrm 记忆
暴露的工具
安全
- Bearer Token 认证 — 每个连接器获得唯一
myrm_mcp_*Token - 一键撤销 — 立即失效某连接器的访问权,不影响其他连接器
- HTTP 传输 — 支持远程网络访问(不限于本地 stdio)
- Doctor 健康检查 — 在 GUI 中随时验证连接状态
支持的客户端
价值
在 Cursor 中写代码时存储的项目知识,切换到 Myrm WebUI 做研究时立即可用,反之亦然。无需手动同步上下文。企业 Org MCP(云 SaaS)
在云托管企业部署中,IT 管理员可集中管理组织级 MCP:- 进入 设置 → Enterprise → Org MCP(仅 owner/admin)
- 添加 HTTP/SSE MCP 服务器(名称、URL、可选 auth header)
- 变更通过控制平面自动推送到各成员沙箱
- 沙箱休眠时标记 skipped,唤醒后自动补推(最多 3 次重试)
- 员工在 设置 → MCP 以只读方式查看组织托管 MCP,不可修改或删除
- 云沙箱禁止 stdio MCP(不允许本地进程型服务器)
故障排除
服务无法启动
- 检查命令路径可访问
- 验证环境变量
- 查看 设置 > 工具 > MCP > Logs
工具未出现
- 启动后等待 5-10 秒发现
- MCP 设置面板点 Refresh
- 检查服务工具列表 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 在运行时实时检测认证失败并引导重新授权:- 即时检测 — 工具调用收到 MCP 服务返回的 HTTP 401 时立即捕获(无需等待重连重试耗尽)
- 用户通知 — 自动弹出 Toast 通知:” 需要重新授权”,附带一键**“立即授权”**按钮
- 一键修复 — 点击按钮直接跳转到 设置 → 扩展,完成 OAuth 重新授权
- Token 热更新 — 授权完成后,活跃会话通过连接池自动拾取新 Token——无需刷新页面,无需重建连接,下一次工具调用即用新凭证
企业私网 MCP 隧道(仅云部署)
:::info 仅限云托管部署 此功能仅适用于由控制平面管理的云托管 Myrm 部署。本地和 Tauri 用户通过 stdio 直连 MCP 服务器,无需隧道。 ::: 对于 MCP 服务器运行在私有网络(防火墙内、VPC 中或本地机房)的企业客户,Myrm 提供反向隧道——让云端 AI 助手安全访问内网 MCP 服务器,无需暴露任何端口或修改防火墙规则。工作原理
- 部署 tunnel-agent — 在企业内网的任意机器上安装开源的
myrm-tunnel-agent - 注册隧道 — Agent 向控制平面注册并获取安全 Token
- 仅出站连接 — tunnel-agent 主动向控制平面发起出站 long-poll 连接,无需开放入站端口
- 透明中继 — 当云端 Myrm Agent 调用内网 MCP 工具时,请求通过隧道中继到内部 MCP 服务器,响应透明返回
安全特性
架构
配置步骤
- 在组织管理面板注册隧道(设置 → 组织 → MCP → 添加隧道)
- 使用提供的 Token 和内部 MCP 服务器地址部署
myrm-tunnel-agent - 隧道以 org 级 MCP 服务器形式出现——像其他 MCP 服务器一样分配给 Agent 使用
企业身份认证 — IdP 群组 MCP 权限管理(仅云部署)
:::info 仅限云托管部署 此功能仅适用于已配置 OIDC SSO 的云托管 Myrm 部署。本地和 Tauri 用户在本地设置中直接管理 MCP 访问。 ::: 对于使用身份提供商(Okta、Entra ID、Google Workspace 等)的企业客户,Myrm 自动将 IdP 群组成员关系映射到 组织 MCP 服务器访问权限——IT 管理员可以控制哪些团队看到哪些工具,无需逐人手动配置。工作原理
- OIDC groups claim — 用户通过 SSO 登录时,Myrm 从 OIDC 响应中提取
groupsclaim 并存储到用户的组织成员记录 - Per-MCP 群组白名单 — 组织管理员为每个 org MCP 服务器配置可选的
acl_groups列表(留空 = 全员可见) - 自动过滤 — 当 MCP 配置推送到用户沙箱时,仅推送用户 IdP 群组与服务器 ACL 群组有交集的服务器
- 登录自动刷新 — 群组成员关系在每次 OIDC 登录时自动刷新,无需手动同步
配置群组权限
- 进入 设置 → 组织 → MCP 服务器
- 创建或编辑 MCP 服务器时,在访问群组字段输入 IdP 群组名称(逗号分隔)
- 留空则该服务器对所有组织成员可见
- IdP 群组匹配至少一个配置群组的成员将看到并使用该服务器