> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 集成

> 使用 Model Context Protocol 连接外部工具与服务。

# MCP 集成

Myrm 支持 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)，将外部工具与服务接入 Agent。

## 什么是 MCP？

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

## 服务目录（一键连接）

连接主流服务的最快方式。进入 **设置 > 通信与集成 > 服务目录**，浏览 9 大类别 29 项预配置集成：

| 类别         | 服务                                                          |
| ---------- | ----------------------------------------------------------- |
| **API 工具** | Postman                                                     |
| **浏览器**    | Playwright, Browserbase                                     |
| **通信协作**   | Gmail, Slack, 飞书, 钉钉                                        |
| **数据存储**   | PostgreSQL, 本地文件系统, Google Drive, Supabase                  |
| **设计**     | Figma（描述性输出，优化代码生成）                                         |
| **开发工具**   | GitHub, GitLab, Gitee, Gitee 企业版, Sentry, 代码审查图谱, CodeGraph |
| **文档**     | Context7, Microsoft Learn, AWS 文档                           |
| **效率工具**   | Notion, Todoist, Google 日历, Linear                          |
| **网页搜索**   | Firecrawl（Keyless 免费层一键连接）, Exa, Brave Search               |

每个服务包含：

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

点击服务卡片上的 **连接** 按钮。Firecrawl 等 Keyless 服务直接点击连接即可，无需填写任何凭证。其他服务填写所需 API Key 即可就绪。

## 云盘文件同步与导出

Myrm 通过 6 条路径覆盖任意云盘的文件同步与导出需求，无需为每个云盘内置专用连接器：

| 路径                | 覆盖范围                                 | 使用示例                     |
| ----------------- | ------------------------------------ | ------------------------ |
| **内置 MCP**        | Google Drive、Notion（一键连接）            | "帮我把这篇文章存到 Google Drive" |
| **代码执行沙箱**        | 任意云盘 SDK（boto3/dropbox/onedrive-sdk） | "上传 report.pdf 到我的 S3 桶" |
| **浏览器自动化**        | 无 API 的国内云盘（百度网盘等）                   | "帮我存到百度网盘"               |
| **MCP 市场**        | 社区 MCP Server（Dropbox/OneDrive 等）    | 从注册中心一键安装                |
| **双向文件传输**        | Agent 文件通过 IM 渠道自动推送                 | 文件自动出现在飞书/钉钉/Telegram 中  |
| **Artifact 分享链接** | HMAC 安全的公开分享 URL                     | 与外部团队分享 Agent 生成的报告      |

:::tip
与将用户锁定在单一云生态的竞品不同，Myrm 的开放架构让你可以通过多条路径连接**任意**存储服务。Agent 会根据你的请求自动选择最佳方式。
:::

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

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

### 工作原理

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

### 核心能力

| 能力                | 说明                                           |
| ----------------- | -------------------------------------------- |
| **通用桥接**          | MCPBridgeProvider 自动桥接任何 MCP Server，无需编写适配代码 |
| **并发同步**          | 最多 5 个 provider 并行同步                         |
| **智能解析**          | 兼容 list/dict/原始字符串等多种 MCP 工具返回格式             |
| **树形管理**          | 层级结构 + 自动摘要，支持浏览和删除                          |
| **自动知识萃取**        | 新同步数据经 MemoryExtractor 提取关键洞察                |
| **按 Provider 同步** | 支持同步单个 provider 或一键全部同步                      |

### 管理已同步数据

* **状态概览**：查看 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` 添加：

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

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

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

### 使用方式

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

| 阶段     | 执行内容                                                       |
| ------ | ---------------------------------------------------------- |
| **调研** | 调查目标 API（认证方式、端点、限流）                                       |
| **实现** | 用 Python (FastMCP) 或 TypeScript (MCP SDK) 编写 Server，设置正确注解 |
| **验证** | 运行验证脚本确认 Server 启动、通过安全扫描                                  |
| **注册** | 生成配置 JSON，填入设置页，在对话中测试工具调用                                 |

### 内置质量保障

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

## Schema 处理

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

| 特性                       | 说明                                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Schema 扁平化**           | 深度 >2 或叶子 >10 的嵌套 Schema 自动扁平化                                                                                                        |
| **类型智能修复**               | 7 种 Schema 问题自动修复：nullable 缺失补全、mixed-union 容器解析、enum/const null 识别、反向 coercion、boolean/number 字符串转换、markdown 代码块剥离、深嵌套 dot-path 平铺   |
| **点路径检测**                | 检测模型是否用点号表示嵌套参数                                                                                                                       |
| **\$ref 解析**             | 完整递归 JSON Schema `$ref` 解析                                                                                                            |
| **循环引用防护**               | 最大深度 + 访问追踪防无限递归                                                                                                                      |
| **Anthropic Schema 自适应** | 自动剥离 Claude 不支持的 JSON Schema 关键字（`minimum`、`maximum`、`pattern`、`format`、`default`、`title` 等），约束语义折叠到 `description` 保留 LLM 理解能力，无需手动配置 |
| **描述长度安全阀**              | 超长第三方描述自动截断至 2048 字符，防止 Token 浪费                                                                                                      |
| **Schema 缓存稳定**          | Key 递归排序 + set 类字段排序，消除 MCP 服务器重启导致的序列化随机性，确保 Prompt Cache 命中                                                                         |
| **Coercion 可观测**         | 运行时计数器追踪每种修复类型的触发频次，支持 DEBUG 日志排查                                                                                                     |
| **内容边界防御**               | 所有 MCP 返回值经 5 层 `wrap_untrusted` 防御链处理，防止 Prompt Injection                                                                            |

## 连接管理

### 持久会话

每个 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. 通过复选框单独开关每个工具

### 风险标注

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

| 风险等级   | 图标    | 说明                             |
| ------ | ----- | ------------------------------ |
| **安全** | 🟢 盾牌 | 只读操作（`readOnlyHint: true`）     |
| **注意** | 🟡 眼睛 | 写操作（非只读、非破坏性）                  |
| **危险** | 🔴 警告 | 破坏性操作（`destructiveHint: true`） |

### 危险工具自动禁用

首次在智能体上启用 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](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#annotations) 用于自动风险管理：

| 注解                | 效果                                                                   |
| ----------------- | -------------------------------------------------------------------- |
| `readOnlyHint`    | 只读；当 `readOnly && !openWorld && !destructive` 时自动审批（PTC 和直接 MCP 双路径） |
| `destructiveHint` | 危险；**默认禁用**于安全集，GUI 警告徽章                                             |
| `idempotentHint`  | 可安全重试                                                                |
| `openWorldHint`   | 可能与 MCP 服务外系统交互                                                      |

### 默认安全集

首次为 Agent 启用 MCP 服务时，根据注解自动构建**安全默认选择**：

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

### 工具名隔离

多 MCP 服务时工具名可能冲突。Myrm 对每工具加**服务前缀**：

```
mcp__{server}__{tool}
```

* **双下划线分隔** — 可无歧义解析回 `(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 记忆

### 暴露的工具

| 工具                   | 说明                                                                           |
| -------------------- | ---------------------------------------------------------------------------- |
| `memory_search_tool` | 通过 `corpus` 参数统一搜索 memory / wiki / 历史会话；memory corpus 支持类别过滤与 profile key 查询 |
| `memory_list`        | 枚举和审计记忆：overview 模式查看全局统计与预览，category 模式分页浏览单类别记忆                            |
| `memory_store`       | 存储新知识、偏好、规则、事件或指令                                                            |
| `memory_manage`      | 评分、更新、纠正或删除已有记忆                                                              |

### 安全

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

### 支持的客户端

| 客户端         | 配置格式 | 配置文件路径                              |
| ----------- | ---- | ----------------------------------- |
| Claude Code | JSON | `~/.claude/claude_code_config.json` |
| Cursor      | JSON | `.cursor/mcp.json`                  |
| Codex       | TOML | `codex.toml`                        |
| Windsurf    | JSON | `~/.windsurf/mcp_config.json`       |
| Gemini CLI  | JSON | `~/.gemini/settings.json`           |

### 价值

在 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。这样可以避免“反复点连接但不知道根因”的死路流程。

| 分类        | 信号                                                                                    | 含义                      | 下一步                                 |
| --------- | ------------------------------------------------------------------------------------- | ----------------------- | ----------------------------------- |
| 可达        | `reasonCode=reachable`                                                                | MCP 端点在超时内正常响应          | 继续执行 scan/verify                    |
| 编辑器端服务未启动 | `reasonCode=connection_refused`                                                       | 端口存在但无服务监听              | 启动编辑器侧 MCP 服务/插件                    |
| 本地路由不可达   | `reasonCode=connection_unreachable`                                                   | 回环链路存在但被本地路由/VPN/代理策略阻断 | 检查 localhost 路由、VPN/代理策略与编辑器 MCP 配置 |
| TLS 信任失败  | `reasonCode=tls_verification_failed`                                                  | 证书链或主机名校验失败             | 导入企业 CA，或配置每服务器 CA bundle / mTLS    |
| 连接超时      | `reasonCode=connection_timeout`                                                       | 目标可达性不稳定或响应过慢           | 检查本地网络稳定性与编辑器 MCP 服务健康后重试           |
| 探测出现未知失败  | `reasonCode=probe_failed_unknown` + `recommendedMode=verify_local_network_and_editor` | 探测阶段出现非网络类运行时异常         | 检查编辑器 MCP 配置后重试；详细诊断请查看服务端日志        |
| 回环策略拦截    | HTTP 400 + `localhost addresses only` 详情                                              | 非回环地址被 SSRF 防护阻断        | 本地集成改用 `127.0.0.1` / `localhost`    |

补充保证：

* 当 `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 服务器，响应透明返回

### 安全特性

| 特性           | 说明                                     |
| ------------ | -------------------------------------- |
| **零入站暴露**    | 企业网络仅发起出站连接——无需防火墙端口、VPN 或公网 IP        |
| **mTLS 加密**  | tunnel-agent 与控制平面之间端到端双向 TLS          |
| **Token 轮换** | 认证 Token 可随时轮换，服务不中断                   |
| **心跳监控**     | 60 秒过期阈值 + 30 秒扫描间隔——离线隧道在 90 秒内被检测并标记 |
| **即时撤销**     | IT 管理员可通过组织管理面板立即撤销隧道访问                |

### 架构

```
┌─ 企业内网 ─────────────────────┐     ┌─ 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 权限管理（仅云部署）

:::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 访问权限，无需手动清理。

### 安全特性

| 特性         | 说明                                  |
| ---------- | ----------------------------------- |
| **零接触配置**  | 新员工根据 IdP 群组自动看到正确的 MCP 工具，无需 IT 工单 |
| **默认最小权限** | 配置了 ACL 群组的服务器对不匹配的成员不可见            |
| **即时撤销**   | 离职操作立即切断 MCP 访问                     |
| **审计友好**   | 群组成员关系可通过组织成员 API 查看，便于合规审查         |