​

MCP 集成

​

什么是 MCP？

​

服务目录（一键连接）

• 预配置的连接信息（命令、参数、URL）
• 引导式凭证输入，附带指向服务商令牌页面的帮助链接
• Keyless 零配置支持：部分服务（如 Firecrawl 免费层）无需 API Key 即可一键连接
• 连接前安全扫描（SSRF + 恶意包检测）
• 中英双语描述

​

云盘文件同步与导出

​

集成记忆（工作空间同步）

​

工作原理

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 可用

​

从配置文件

{
  "servers": [
    {
      "name": "github",
      "command": "npx",
      "args": ["@mcp/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  ]
}

​

Agent Plugins 1.0.0 标准插件

​

导入插件包

1. 进入 设置 > 技能，打开插件管理器
2. 导入标准 Agent Plugins 插件包（.zip 或目录）
3. Myrm 自动解析清单、持久化自带文件树、注册插件的 MCP 服务

​

管理插件的 MCP 服务（启停状态）

• 运行时过滤 —— 工具发现阶段只加载已启用的服务。被禁用（或损坏）的服务永远不会进入智能体的工具集，因此单个坏服务无法拖垮插件其余部分，也不会阻塞智能体启动。
• 逐服务控制 —— 可只启用其中一个服务而保留另一个关闭，随时独立切换任一服务的启停，无需重新导入插件。

​

运行时：PLUGIN_ROOT / PLUGIN_DATA（规范 §9）

• PLUGIN_ROOT — 插件的安装目录（自带可执行文件所在）
• PLUGIN_DATA — 插件的持久化数据目录，跨更新保留

import os

root = os.environ["PLUGIN_ROOT"]
data = os.environ["PLUGIN_DATA"]

​

卸载

​

构建自定义 MCP 服务（AI 引导式）

​

使用方式

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

​

内置质量保障

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

​

Schema 处理

​

OpenAPI Bridge（连接任意 REST API）

​

工作方式

1. 添加服务——提供 OpenAPI spec 地址（或 Swagger 2.0 文档）
2. 自动生成工具——每个端点都变成一个 Agent 工具，带完整、LLM 可读的参数 schema
3. 连接即用——Agent 以正确的类型、正确的路由、无损的数值精度调用你的 API

​

内置保障

​

为什么重要

​

连接管理

​

持久会话

​

无状态 HTTP 与云负载均衡

• Round-robin 负载均衡开箱即用，无需 session affinity
• 协议自动协商：通过 server/discover 探测自动检测服务器能力
• 路由头（Mcp-Method、Mcp-Name、MCP-Protocol-Version）每次请求自动注入，支持网关层智能请求路由
• 本地/桌面会话继续使用持久热连接以获得最佳性能（两全其美）

​

执行超时保护

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

​

错误透明化

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

​

自愈重连

• 有界退避 — 最多 5 次，指数退避（0.5s 至 8s 上限）
• 预算刷新 — 稳定运行 60s+ 后获得新重试预算
• 进行中调用显式失败 — 命中中断的调用失败（非幂等工具不静默重试），后续调用在新会话成功
• 代理稳定 — Agent 持有的工具对象重连后不变，保留 Prompt 前缀缓存命中

​

传输感知保活

​

连接池

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

​

连接可靠性（真实协议验证）

• 失败路径零泄漏 — 连接失败、重连失败、正常关闭的所有退出路径都释放传输 HTTP 客户端，数小时长任务内存平稳
• 断线自愈回归 — 服务器崩溃后原地重建会话继续服务，新连接同样受资源安全保护
• 全量验证 — MCP 模块 720 项测试全通过，94.3% 覆盖率

​

CancelledError 防护

​

指标

​

安全

​

SSRF 防护

• 解析 IP 检查私有段（10.x、172.16-31.x、192.168.x）
• 默认阻断 localhost 与 link-local
• URL 校验防基于重定向的 SSRF

​

恶意包检测

​

工具审批

• 只读工具自动执行
• 写/破坏性工具需用户审批（YOLO 模式除外）
• 可按 MCP 服务配置自定义审批策略

​

MCP 服务器交互确认（Elicitation）

• 显示服务器的确认消息
• 60 秒倒计时
• 批准 / 拒绝 按钮

​

单工具粒度过滤

​

使用方法

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

​

风险标注

​

危险工具自动禁用

​

过滤摘要

​

多模态工具结果

​

图片内容

• Base64 经流式管道在 Tool Image Gallery 显示
• 单结果多图（网格 + 灯箱）
• 不支持视觉的模型由媒体过滤器自动剥离图片

​

结构化内容

​

工具过滤

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

​

安全注解

​

默认安全集

• 所有 readOnlyHint 工具启用
• destructiveHint 禁用并横幅提示
• 可在 Tool Selection GUI 覆盖

​

工具名隔离

mcp__{server}__{tool}

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

​

动态工具发现

• 零停机刷新 — 重新拉取工具列表，不中断进行中调用
• Prompt 缓存稳定 — 面向 Prompt 的代理工具冻结，仅更新内部执行映射
• 超时保护 — 刷新拉取有界超时
• 变更日志 — 增删记 WARNING；无变更记 INFO
• 对 Agent 透明 — 新工具立即可用，移除工具下次调用显式失败

​

延迟加载

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

​

反向 MCP 服务（Connect）

​

使用方法

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

​

暴露的工具

​

安全

• Bearer Token 认证 — 每个连接器获得唯一 myrm_mcp_* Token
• 一键撤销 — 立即失效某连接器的访问权，不影响其他连接器
• 无状态 HTTP 传输 — 每个请求自包含（无需 Mcp-Session-Id 跟踪），支持任何兼容 MCP 的客户端远程访问
• Doctor 健康检查 — 在 GUI 中随时验证连接状态

​

支持的客户端

​

价值

​

企业 Org MCP（云 SaaS）

1. 进入 设置 → Enterprise → Org MCP（仅 owner/admin）
2. 添加 HTTP/SSE MCP 服务器（名称、URL、可选 auth header）
3. 变更通过控制平面自动推送到各成员沙箱
4. 沙箱休眠时标记 skipped，唤醒后自动补推（最多 3 次重试）
5. 员工在 设置 → MCP 以只读方式查看组织托管 MCP，不可修改或删除
6. 云沙箱禁止 stdio MCP（不允许本地进程型服务器）

​

故障排除

​

服务无法启动

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

​

工具未出现

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

​

连接断开

​

本地编辑器 MCP 探测诊断

• 当 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 过期

1. 即时检测 — 工具调用收到 MCP 服务返回的 HTTP 401 时立即捕获（无需等待重连重试耗尽）
2. 用户通知 — 自动弹出 Toast 通知：” 需要重新授权”，附带一键**“立即授权”**按钮
3. 一键修复 — 点击按钮直接跳转到 设置 → 扩展，完成 OAuth 重新授权
4. Token 热更新 — 授权完成后，活跃会话通过连接池自动拾取新 Token——无需刷新页面，无需重建连接，下一次工具调用即用新凭证

​

企业私网 MCP 隧道（仅云部署）

​

工作原理

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

​

安全特性

​

架构

┌─ 企业内网 ─────────────────────┐     ┌─ Myrm 云端 ───────────────────┐
│                                │     │                               │
│  内部 MCP 服务器               │     │  CP 隧道中继（内存级）         │
│       ↑                        │     │       ↑                       │
│  myrm-tunnel-agent ─── 出站 ──────→  │  org MCP → streamable_http    │
│  （开源）              HTTPS   │     │       ↓                       │
│                                │     │  云端 Agent（沙箱内）         │
└────────────────────────────────┘     └───────────────────────────────┘

​

配置步骤

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

​

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

​

工作原理

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 群组匹配至少一个配置群组的成员将看到并使用该服务器

​

离职处理

​

安全特性