# Gumloop 官方文档 — Custom MCP Servers

> 来源：https://docs.gumloop.com/nodes/mcp/custom_mcp_servers.md
> 抓取日期：2026-05-30
> 关联 Spec：`spec_mcp-artifacts.md`

---

## 概述

Gumloop 支持连接任何遵循 Model Context Protocol 的服务器。平台已内置"50+ 预构建 MCP 服务器"（GitHub、Slack、Notion、HubSpot 等），自定义服务器覆盖不在此列的任何 MCP 兼容 API。

---

## 添加自定义 MCP 服务器

四步流程：

1. 导航到 Settings > Credentials，找到 "MCP Server"
2. 点击 "Add credential"，输入服务器 URL（**必须使用 HTTPS**）
3. 配置认证：
   - **Label**（必填）
   - **Access Token/API Key**（服务器需要时提供）
   - **Additional Header**（可选，"Header-Name: value" 格式）
4. 点击 Connect 保存

提示：选择适当的范围（个人 vs 团队级凭据）。

---

## 技术要求

- **协议**：仅 HTTPS（HTTP 不支持）
- **可访问性**：必须公网可访问
- **传输**：Streamable HTTP 或 Server-Sent Events (SSE)
- **本地服务器**：不支持（无 STDIO 或 localhost 连接）

警告："本地 MCP 服务器无法工作。" 建议使用 Cloudflare Tunnels 或 ngrok 暴露本地服务器。

---

## 认证选项

- **Bearer Token**：发送为 `Authorization: Bearer <token>`
- **自定义 Header**：Additional Header 字段支持非标准认证格式的单个头部
- **OAuth 发现**："兼容服务器的自动 OAuth 流程发现（RFC 8414）"

---

## 使用场景

### Agent 中使用 MCP
Agent 提供最灵活的方式：
- 自动工具发现——AI 识别所有暴露的工具并根据对话上下文选择
- 对话式多轮——Agent 保持历史记录，可跨多次交换调用工具
- 多服务器编排——同时连接多个 MCP 服务器，Agent 决定使用哪个
- **无需工作流**——工具在聊天、Slack 或嵌入式界面中立即可用

配置：打开 Agent 配置 → "Add tools" → 在 Custom 标签页下选择 "MCP Server"

### Ask AI 节点中使用 MCP
用于确定性、可重复的工作流：
- 拖拽 Ask AI 节点到画布
- 点击 "Show more options"
- 切换 "Connect MCP Server?" 为 ON
- 选择一个或多个已配置服务器
- 节点执行单次提示词，自动工具发现

### Agent vs Ask AI 节点

| 维度 | Agent | Ask AI 节点 |
|------|-------|-----------|
| 灵活性 | 高：对话式，多轮 | 中：单次提示词执行 |
| 工具发现 | 自动 | 自动 |
| 多服务器 | ✅ | ✅ |
| 审批提示 | 无 | 无 |
| 适用场景 | 交互式使用、复杂推理 | 工作流、批处理 |

---

## 模型特定差异

自定义 MCP 服务器在所有模型中工作，但执行方式不同：

- **GPT-5、GPT-4.1、Claude 4 Sonnet、Claude 3.7 Sonnet** → **Native MCP**：提供商（OpenAI/Anthropic）直接连接到你的 MCP 服务器并执行工具
- **Gemini、Groq** → **Backend connector**：Gumloop 连接到你的服务器，以常规函数调用形式呈现工具，执行后返回结果

### 头部处理差异

| 模型 | Bearer Token | 自定义 Header |
|------|-------------|--------------|
| OpenAI (Native MCP) | 作为 Authorization header 发送 | 原样转发 |
| Anthropic (Native MCP) | 作为 authorization token 发送 | **不转发** ⚠️ |
| Gemini/Groq (Backend) | 原样发送 | 原样发送 |

警告："Anthropic 模型不转发自定义头部。" 建议使用 Bearer Token 字段或切换到 OpenAI/Gemini/Groq。

---

## 安全考虑

- **数据共享**：提示词中的信息可能传输到 MCP 服务器。注意敏感数据，查看服务器政策
- **直接工具访问**：所有服务器工具立即可用——"工具执行前无审批提示"——建议使用适当的授权范围
- **多服务器影响**：一个服务器的数据可能传递给另一个。提示词设计应考虑这一点

---

## 故障排查

| 问题 | 解决方案 |
|------|---------|
| 连接失败 | 验证 HTTPS 和公网可访问性 |
| 认证问题 | 检查 Token 有效性和过期时间 |
| 工具缺失 | 确保服务器支持 MCP 工具发现 |
| AI 忽略工具 | 使用更明确的提示词 |
| 超时错误 | 调查服务器状态 |

建议在构建复杂工作流前，要求 Agent 或 Ask AI 节点 "list available tools" 进行工具发现测试。