# Gumloop 功能规格 — MCP Hosting & Proxying（MCP 托管与代理基础设施）

版本：v1.0 | 来源：官方帮助文档 | 日期：2026-05-30

> **文档状态**：已完成 — 基于官方文档验证
> **标记说明**：`[文档已验证]` 表示内容直接来自官方帮助文档，`[推断]` 表示基于可用信息的合理推导。

---

## 初始上下文

- **产品/团队**：Gumloop / AI Agent 平台
- **功能**：MCP Hosting & Proxying — 为 Enterprise 客户提供 MCP 服务器的全托管部署与外部代理连接
- **版本**：v9.1.0 "Ucluelet"（2026-04-29）
- **战略定位**：Gumstack 企业基础设施战略三大支柱之一（与 App Policies、Audit Logs、Data Drains 并列）
- **目标用户**：Enterprise 客户——需要部署内部 MCP 服务的开发团队，以及需要安全连接第三方 MCP 服务的企业IT团队
- **核心价值**：降低 MCP 基础设施运维成本（Hosted），同时提供统一的安全代理层连接一切外部 MCP（Proxied）
- **解决的问题**：企业部署和连接MCP服务器缺乏统一的基础设施层——自建MCP需要手动管理CI/CD、监控和日志，连接第三方MCP缺乏统一的认证、权限和可观测性
- **评分**：9/13（战略2 护城河2 用户2 复杂度2 创新1）

---

## 1. 概览

### 背景

Gumloop 的 MCP 生态已扩展至 100+ 预构建集成。然而，企业的 MCP 基础设施需求远不止"连接现成的 MCP 服务"——他们还需要：

1. **部署自有 MCP 服务**：团队内部开发的定制 MCP 服务器，需要在生产环境中持续运行
2. **安全管理外部连接**：企业内部自建的 MCP 端点需要通过统一的代理层进行访问控制、流量监控和认证管理

v9.1.0 发布的 MCP Hosting & Proxying 以双模式架构解决上述两个需求：Hosted MCP 覆盖"我需要部署但不想管理服务器"的场景，Proxied MCP 覆盖"我已经有MCP服务但需要企业级代理管控"的场景。

### 目标

1. **零运维部署**：从 GitHub 仓库一键部署 MCP 服务器，Gumloop 管理全部 CI/CD 和监控
2. **统一代理入口**：所有外部 MCP 流量经过 Gumloop 代理层，实现统一的认证、权限和可观测性
3. **细粒度访问控制**：通过 custom-role 矩阵精确控制每个角色对每个 MCP 工具的访问权限
4. **企业级可观测性**：延迟分位数着色、实时日志、活动直方图——让运维团队一眼判断健康状态

---

## 2. 核心机制 [文档已验证]

### 2.1 架构总览：双模式数据流

```
+------------------------------------------------------------------+
|                        Gumloop Enterprise                         |
|                                                                   |
|   ┌───────────────────────┐          ┌───────────────────────┐   |
|   │     HOSTED MCPs        │          │     PROXIED MCPs       │   |
|   │                        │          │                        │   |
|   │  GitHub Repo           │          │  3rd-party MCP Server  │   |
|   │     │                  │          │   (any infra)          │   |
|   │     │ git push         │          │        │               │   |
|   │     v                  │          │   URL: https://...     │   |
|   │  CI/CD Pipeline        │          │        │               │   |
|   │     │                  │          │        v               │   |
|   │     │ build+deploy     │          │  Gumloop Proxy Layer   │   |
|   │     v                  │          │   (auth + routing)     │   |
|   │  Gumloop Pods          │          │        │               │   |
|   │  (managed infra)       │          │        v               │   |
|   │     │                  │          │  Custom-Role Matrix    │   |
|   │     v                  │          │        │               │   |
|   │  MCP Server URL ───────┼──────────┼──> Agent Tools         │   |
|   │  (gumloop-managed)     │          │  (proxy-managed)       │   |
|   │                        │          │                        │   |
|   │  Observability:        │          │  Observability:        │   |
|   │  Pods | Logs | CPU     │          │  Latency | Uptime      │   |
|   │  Deploy History        │          │  Auto-Discovery        │   |
|   └───────────────────────┘          └───────────────────────┘   |
|                                                                   |
|   ┌───────────────────────────────────────────────────────────┐  |
|   │              共享能力层                                    │  |
|   │  Custom-Role Matrix | Activity Histogram | CSV Export     │  |
|   │  Latency Color Coding | Tool Discovery | API Key / OAuth  │  |
|   └───────────────────────────────────────────────────────────┘  |
+------------------------------------------------------------------+
```

### 2.2 Hosted MCP：从代码到部署

**生命周期（三步创建向导）**：`[文档已验证]`

1. **Basic Info**：名称、描述、关联 GitHub 仓库、可见性（仅 Enterprise workspace 内）
2. **Auth 配置**：None / API Key / OAuth 2.0，外加环境变量（开发者密钥，加密存储）
3. **Review & Create**：确认配置后，Gumloop 自动创建含 Python 样板代码的 GitHub 仓库并注册 MCP 服务器

**部署触发**：推送至 main 分支自动触发 CI/CD pipeline `[文档已验证]`

**六标签详情页**：`[文档已验证]`

| 标签 | 核心能力 |
|------|---------|
| **Overview** | 7 天快照（调用量、用户数、错误率、延迟）、MCP Server URL、当前部署状态 |
| **Tools** | Custom-role 矩阵——按工具 × 角色切换开关，可对某角色整体禁用该服务器 |
| **Activity** | 延迟直方图（P25 绿色 / P85-P95 橙色 / P95+ 红色）、请求明细表、CSV 导出 |
| **Deployments** | 部署历史（Building → Deploying → Live / Ready / Failed / Rolled Back）、手动从分支/commit 部署 |
| **Monitoring** | 活跃 Pod 数、Pod 重启次数、实时流式运行时日志 |
| **Settings** | 头像、名称、描述、环境变量、禁用/删除服务器 |

**GitHub 连接方式**：`[文档已验证]`
- **GitHub OAuth (Personal)**：按开发者绑定，允许创建仓库
- **GitHub App (Organization)**：一次性安装，启用推送 main 后自动部署

### 2.3 Proxied MCP：URL 即服务

**连接流程（三步向导）**：`[文档已验证]`

1. **输入 URL** → Gumloop 探测服务器能力（工具列表、资源列表、传输协议）
2. **配置**：名称、认证方式（None / API Key / OAuth 2.0）、配置界面支持 UI 模式和 Raw JSON 模式切换
3. **发现并激活**：自动检测 tools/resources，添加凭据后展示工具发现摘要

**四标签详情页**：`[文档已验证]`

| 标签 | 核心能力 |
|------|---------|
| **Overview** | 7 天快照、代理 URL、路由状态（可达时为 Live）、**Fetch New Tools** 按钮（手动触发工具重新发现） |
| **Tools** | Custom-role 矩阵（同 Hosted） |
| **Activity** | 同 Hosted：延迟直方图 + 请求明细表 |
| **Settings** | 名称、描述、URL、禁用/删除 |

**关键行为**：`[文档已验证]`
- 内嵌凭据在 UI 中自动脱敏显示
- 仅支持 HTTP 传输（Streamable HTTP 或 SSE）
- 外部服务器无需感知 Gumloop 存在
- 中断恢复后自动重连
- 认证方式创建后即固定（需删除重建才能更换）

### 2.4 Hosted vs Proxied 对比矩阵

```
                    Hosted MCP          Proxied MCP
──────────────────────────────────────────────────────
 代码部署           ✅ GitHub 仓库       ❌ 无需部署
 运行位置           Gumloop 基础设施     第三方基础设施
 CI/CD             ✅ 自动构建部署       ❌ 不适用
 Pod 监控           ✅ 实时 Pod + 日志    ❌ 仅可用性检查
 工具自动发现       创建时               创建时 + Fetch New Tools
 活动追踪           ✅                    ✅
 Custom-Role 矩阵   ✅                    ✅
 部署历史           ✅（6 种状态）        ❌
 实时日志           ✅                    ❌
 环境变量管理        ✅                    ❌
 URL 管理           自动生成             用户提供的代理 URL
 标签页数           6                    4
```

### 2.5 工具权限矩阵（Custom-Role Matrix）`[文档已验证]`

两种模式共享同一套权限控制机制：

- **粒度**：每个工具 × 每个自定义角色 = 独立开关
- **默认**：所有工具对所有角色启用（开放）
- **操作**：Toggle 关闭 → 该角色下 Agent 调用该工具时返回"无权访问"
- **服务器级**：对整个 MCP 服务器按角色禁用（一键关闭该角色对所有工具访问）
- **适用场景**：限制初级角色访问敏感 MCP 工具（如写数据库、删除文件），同时保持高级角色不受影响

### 2.6 可观测性：延迟颜色编码 `[文档已验证]`

Activity 标签页内的延迟直方图采用三色编码，让运维团队一眼判断系统健康：

- **绿色**：P25 及以下——正常响应
- **橙色**：P85-P95 区间——需关注，接近性能边界
- **红色**：P95 以上——高延迟告警，需排查

请求明细表格同步着色，支持导出为 CSV 文件用于离线分析或 SIEM 集成。

---

## 3. 功能需求

### 模块 A：Hosted MCP 生命周期

| ID | 需求 | 优先级 |
|----|------|--------|
| A1 | 通过 GitHub OAuth 或 GitHub App 连接开发者/组织账号 | P0 |
| A2 | 三步创建向导：Basic Info → Auth → Review & Create | P0 |
| A3 | 仓库创建后自动填充 Python MCP 样板代码 | P0 |
| A4 | 推送 main 分支自动触发 CI/CD pipeline 构建与部署 | P0 |
| A5 | 部署状态机：Building → Deploying → Live / Ready / Failed / Rolled Back | P0 |
| A6 | 支持手动从指定分支或 commit SHA 部署 | P1 |
| A7 | 环境变量加密存储，UI 中可增删改但不展示明文 | P0 |
| A8 | 实时流式运行时日志（< 5s 延迟） | P1 |
| A9 | Pod 级别监控：活跃 Pod 数、重启次数 | P1 |
| A10 | 服务器禁用/删除（含级联影响提示） | P0 |

### 模块 B：Proxied MCP 连接

| ID | 需求 | 优先级 |
|----|------|--------|
| B1 | 输入 URL 后自动探测服务器能力（tools、resources、transport） | P0 |
| B2 | 三步连接向导：URL → Auth Config → Discover & Activate | P0 |
| B3 | 认证配置支持 UI 模式和 Raw JSON 模式切换 | P1 |
| B4 | 仅支持 Streamable HTTP 和 SSE 传输协议 | P0 |
| B5 | 中断恢复后自动重连（指数退避，最长 30s 间隔） | P1 |
| B6 | 内嵌凭据自动脱敏（UI 中显示为 `****`） | P0 |
| B7 | Fetch New Tools：手动触发重新发现工具列表（无需重建连接） | P1 |
| B8 | 代理 URL 路由状态监控（Live / Degraded / Unreachable） | P1 |
| B9 | 认证方式创建后不可变更（需删除重建） | P0 |

### 模块 C：工具发现与权限

| ID | 需求 | 优先级 |
|----|------|--------|
| C1 | 创建/连接时自动发现并列出所有 tools 和 resources | P0 |
| C2 | 按 custom-role × tool 维度设置访问开关 | P0 |
| C3 | 服务器级别按角色整体禁用 | P1 |
| C4 | 权限变更即时生效（无需重新部署或重建连接） | P0 |
| C5 | Hosted MCP 每次部署后自动同步最新工具列表 | P1 |

### 模块 D：活动监控与导出

| ID | 需求 | 优先级 |
|----|------|--------|
| D1 | 7 天滚动窗口快照（总调用量、活跃用户数、错误率、平均延迟） | P0 |
| D2 | 延迟直方图 + 三色编码（绿/橙/红） | P1 |
| D3 | 请求明细表（时间戳、工具名、用户、延迟、状态码） | P0 |
| D4 | 支持导出 CSV 文件 | P1 |
| D5 | 错误率超过阈值（建议 5%）时高亮标记 | P2 |

---

## 4. 用户场景

### 场景 1 — 开发团队部署内部 MCP 服务 `[文档已验证]`

**用户画像**：某金融科技公司后端团队，3 名工程师，维护一个内部 PostgreSQL 查询 MCP 服务器。团队需要将此 MCP 服务化供公司内所有 Gumloop Agent 使用，但不想管理服务器运维。

**当前痛点**：
- 搭建和维护 MCP 服务器基础设施占用工程师精力
- 缺乏统一的部署历史和回滚能力
- 团队 Leader 需要知道"谁在什么时候用了哪个工具"，缺乏审计数据

**使用流程**：
1. 团队 Lead 在 Gumloop Enterprise 中点击 New Hosted MCP
2. 连接 GitHub（Organization App 已安装），选择私有仓库
3. 选择 API Key 认证，配置 PostgreSQL 连接字符串为环境变量
4. Gumloop 自动创建含 MCP 样板代码的仓库，团队只需实现工具函数
5. 推送 main → 自动部署 → Agent 立即可用
6. 团队 Lead 在 Activity 标签查看 7 天延迟直方图，Config Tool Access 为实习生角色关闭写操作工具
7. 需要回滚时，在 Deployments 标签选择上一版本一键 Rollback

**预期收益**：
- 部署时间从"数小时"降至"推送后 2 分钟内"
- 运维工作归零（Gumloop 管理 Pod、日志、监控）
- 工具级权限控制消除了"实习生误操作生产数据库"的隐患

### 场景 2 — 企业 IT 连接第三方 MCP 代理 `[文档已验证]`

**用户画像**：某跨国企业 IT 部门，公司内部有三个自建的 MCP 服务器（Jira 集成、Confluence 集成、内部知识库搜索），运行在公司私有云上。IT 部门需要通过 Gumloop 代理层统一管理这些端点的认证和访问控制。

**当前痛点**：
- 每个 MCP 端点需要单独配置认证，管理复杂
- 不同团队的 Gumloop Agent 需要对不同工具有不同权限
- IT 安全要求所有 MCP 流量可审计，但自建端点缺乏统一的可观测性

**使用流程**：
1. IT 管理员在 Gumloop Enterprise 中点击 New Proxied MCP
2. 输入第一个 MCP 服务器的内网 URL（`https://mcp-jira.internal.company.com`）
3. Gumloop 自动探测到 12 个 tools 和 3 个 resources
4. 配置 API Key 认证，凭据自动脱敏
5. 在 Tools 标签通过 custom-role 矩阵为"只读分析师"角色仅开放查询类工具
6. 重复上述流程添加 Confluence 和知识库 MCP 端点
7. 管理员在 Activity 标签统一查看三个代理的所有调用记录，导出 CSV 对接 SIEM

**预期收益**：
- 三个 MCP 端点的认证管理从"三地分散"变为"一处统一"
- Agent 通过 Gumloop 代理层访问 MCP，IT 获得完整的审计链路
- 新增 MCP 端点时仅需 3 步 URL 连接，无需代码变更

---

## 5. 竞争分析

| 竞品/方案 | 功能/行为 | 优势 | 劣势 | 洞察/机会 |
|-----------|----------|------|------|----------|
| **自建 MCP 服务器** | GitHub 开源 MCP SDK，手动 Docker 部署 | 完全自主可控 | 无 CI/CD 集成、无监控面板、无权限矩阵 | `[推断]` Gumloop 的托管化体验是自建方案 10x 简化 |
| **AWS API Gateway + Lambda** | 通过 API Gateway 代理 HTTP 端点 + Lambda 托管代码 | 生态成熟、自动扩缩容 | 非 MCP 原生，需手动处理 MCP 协议的工具发现和会话管理 | MCP-native 的托管层是差异化壁垒 |
| **Kong / Zuul API Gateway** | 开源 API 网关，支持认证、限流、路由 | 功能强大、社区活跃 | 面向 REST API 通用场景，无 MCP 协议感知（工具发现、角色级工具权限） | MCP 协议层的代理比 HTTP 代理更深——需要理解 tools/resources 语义 |
| **OpenAI Agents SDK / Claude MCP** | OpenAI 和 Anthropic 提供 MCP 协议支持和基础工具 | 协议标准制定者 | 仅提供 SDK 和协议层，不提供企业级托管/代理基础设施 | `[推断]` AI 厂商专注协议层，Gumloop 的机会在"企业运维层" |

**关键洞察**：

1. **MCP 托管是基础设施赛道**：不同于"连接更多 MCP 服务"的应用层竞争，Hosted & Proxied 是 MCP 生态的基础设施——类似于 Vercel 之于前端、Railway 之于后端。这是一个"先发优势显著"的定位。

2. **Custom-Role 矩阵是护城河**：通用 API 网关（Kong、Zuul）无法理解 MCP 协议的"工具"语义，无法实现按 tool × role 的细粒度权限。Gumloop 的 MCP 原生权限控制是竞争对手最难复制的差异化能力。

3. **Proxied 模式降低了 Gumloop 的采用门槛**：企业已有的 MCP 基础设施无需改造，通过代理即可接入 Gumloop 生态——这消除了"必须迁移到 Gumloop 托管"的心理阻力，同时为后续升级到 Hosted 模式铺路。

---

## 6. 未来演进方向

| 优先级 | 方向 | 描述 | 预期影响 |
|--------|------|------|---------|
| P1 | **Custom MCP Templates** | 除 Python 样板外，增加 TypeScript/Go/Rust 模板，支持预置框架集成（FastAPI、Express） | 扩大 Hosted MCP 的开发者受众 |
| P1 | **Auto-scaling Pods** | 基于 QPS 和延迟指标自动扩缩 Pod 数量 | 从"手动运维"升级到"自适应弹性" |
| P2 | **MCP Marketplace** | Enterprise workspace 内发布/发现团队级 MCP 服务，一键安装 | 形成企业内部 MCP 的网络效应 |
| P2 | **Multi-region Deployment** | Hosted MCP 支持多地域部署，Agent 就近路由 | 服务跨国企业的延迟敏感场景 |
| P3 | **Proxied MCP Health Check Dashboard** | 统一仪表盘展示所有 Proxied MCP 的健康状态和 SLA | 降低运维认知负荷 |
| P3 | **Rate Limiting per Tool** | 在 custom-role 矩阵中增加每个工具每角色的速率限制 | 防止 Agent 误操作导致外部 API 限流 |

---

## 源文档参考

- [Hosted MCPs — Gumloop 官方帮助文档](https://docs.gumloop.com/enterprise-features/hosted_mcps.md)（存档于 `/Users/apple/Desktop/Claude-workspace/gumloop/spec/spec_resource/gumloop-docs_mcp-hosting-proxying.md`）
- [Proxied MCPs — Gumloop 官方帮助文档](https://docs.gumloop.com/enterprise-features/proxied_mcps.md)（同上存档）
- Gumloop v9.1.0 "Ucluelet" Changelog（2026-04-29）
- Gumstack Enterprise Infrastructure Strategy（App Policies / Audit Logs / Data Drains 的并列文档）