> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/howto/onboard-external-mcp · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 接入外部 MCP 服务器

入口：控制台 → **MCP 服务器**（仅 admin，仅数据库）。

本章讲怎么在控制台添加、列表、查看详情、编辑、删除外部 MCP 服务器。快速上手跑通一个示例见 [MCP 代理外部工具](/zh-CN/quickstart/mcp-proxy.md)，配置参考（工具 ACL、上下文预算、REST bridge）见 [MCP 配置](/zh-CN/reference/mcp-config.md)。

## 添加 MCP 服务器

控制台 → **MCP 服务器** → **新建**：

| 字段 | 说明 |
|------|------|
| 名称 | 唯一，作工具前缀，正则 `^[a-z0-9][a-z0-9_-]*$` |
| 描述 | UI 展示用 |
| 传输 transport | `streamable_http`（默认）/ `sse` |
| 连接类型 connection_type | `stateful`（有状态）/ `stateless`（无状态）/ `rest_bridge`（REST 桥接） |
| 端点 endpoint | 上游工具服务器 URL |
| 认证头 auth_header | 上游 Authorization 头（如 `Bearer ...`） |
| 额外头 extra_headers | 额外请求头 |
| 标签 tags | 粗粒度 ACL 过滤 |
| 优先级 priority | 0–999，小=高优先；上下文预算裁剪时按此 |
| 空闲超时 idle_timeout_secs | 默认 300 |
| 延迟加载 defer_loading | 首次调用才加载工具 schema |
| 健康检查 health_check | path / interval（默认 60s）/ timeout（默认 5s） |
| 并发上限 max_concurrency | 每访问密钥对该服务器的并发上限 |
| 限流 rate_limit | `requests_per_second` / `tokens_per_minute` |
| extra_config | REST bridge 需在此提供简化的 REST 规范 JSON（`{title, version, operations[]}`） |
| 启用 | |

> 仅 HTTP / SSE / REST-bridge 三种传输，**不支持** stdio / command / args / env / OAuth。

## 连接类型选择

| 类型 | 适用场景 |
|------|---------|
| `stateless`（默认） | 无状态工具服务器，每次请求独立 |
| `stateful` | 有状态工具服务器，维护会话 |
| `rest_bridge` | 把普通 REST API 包装成 MCP 工具 |

## 延迟加载

设 `defer_loading = true` 时，服务器在首次 `tools/list` 或 `tools/call` 时才加载工具 schema。适用于：
- 工具服务器数量多但大部分不常用
- 减少启动时间

## 健康检查

配置后，网关定期探测工具服务器是否存活：

```json
{
  "health_check": {
    "path": "/health",
    "interval_secs": 60,
    "timeout_secs": 5
  }
}
```

不健康的服务器的工具会从 `tools/list` 中排除，连续调用失败时触发临时熔断保护。

## REST bridge

把普通 REST API 包装成 MCP 工具：`connection_type = rest_bridge`，在 `extra_config` 提供简化的 REST 规范 JSON（`{title, version, operations[]}`），网关按 spec 自动生成工具定义。

**注意**：规范是简化的操作列表（`{title, version, operations[]}`），不是标准 OpenAPI 3.x 的 `paths` 形态，也不支持 Swagger 2.0。

控制台 → MCP 服务器 → 新建，**连接类型**选 `REST Bridge`，在 spec 编辑器贴入简化规范（每个 operation 含 `operation_id` / `description` / `method` / `path` / `parameters_schema`），例如：

```json
{
  "title": "Weather API",
  "version": "1.0.0",
  "operations": [
    {
      "operation_id": "getForecast",
      "description": "Get weather forecast",
      "method": "GET",
      "path": "/forecast",
      "parameters_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  ]
}
```

配置后，客户端可通过 `tools/call` 调用 `weather-api.getForecast`，网关自动把 MCP 调用翻译为 REST 请求。字段细节见 [MCP 配置](/zh-CN/reference/mcp-config.md)。

## 列表与详情

- **列表**：显示所有 MCP 服务器，含名称、传输、连接类型、端点、启用状态、健康状态
- **详情**：点某行展开详情，看完整配置、健康检查结果、最近调用统计

## 编辑与删除

- **编辑**：列表 → 编辑。所有字段可改。改 endpoint 后下次调用生效。
- **删除**：列表 → 删除。彻底移除。若某密钥组的 `mcp_tool_acl` 引用该服务器的工具，需先改 ACL 再删。

## 完整案例：聚合两个工具服务器并按组授权

下面各步给的是 **Console API 的 JSON 载荷**（便于脚本化/复制）。若在控制台 UI 里做，对应表单是：**MCP 服务器 → 新建**、**访问密钥 → 密钥组 → 新建**、**访问密钥 → 新建**，字段与 JSON 一一对应（见上文「添加 MCP 服务器」字段表）。

### 1. 添加 MCP 服务器

```json
{
  "name": "github",
  "transport": "streamable_http",
  "endpoint": "http://github-mcp:3001",
  "tags": ["dev-tools"]
}
```

```json
{
  "name": "slack",
  "transport": "streamable_http",
  "endpoint": "http://slack-mcp:3002",
  "tags": ["communication"]
}
```

### 2. 配密钥组

```json
{
  "name": "dev-team",
  "models": ["*"],
  "mcp_tool_acl": {
    "allowed_tools": ["github.*", "slack.send-message", "slack.list-channels"],
    "denied_tools": ["slack.delete-channel", "slack.kick-user"]
  }
}
```

### 3. 配访问密钥

```json
{
  "api_key": "sk-dev-team-key",
  "name": "dev-alice",
  "group": "dev-team"
}
```

### 4. 客户端调用

```json
POST http://localhost:7890/mcp
Authorization: Bearer sk-dev-team-key

{"jsonrpc": "2.0", "method": "tools/call", "params": {
  "name": "github.list_repos",
  "arguments": {"owner": "octocat"}
}}
```

## 常见问题

**Q：工具列表里看不到刚加的服务器的工具？**
检查：① 服务器是否启用；② `defer_loading` 是否开了（首次调用才加载 schema）；③ 密钥组的 `mcp_tool_acl` 是否把它过滤掉了。

**Q：REST bridge 报 spec 不支持？**
规范是简化的 `{title, version, operations[]}` 结构，不是标准 OpenAPI 3.x 的 `paths` 形态，也不支持 Swagger 2.0。按 `operations[]` 重写 spec。

**Q：工具调用经常超时？**
调该服务器的 `max_concurrency`（并发上限）和 `rate_limit`，或检查上游工具服务器本身的响应速度。每个 MCP 服务器有独立熔断保护——连续失败会**触发熔断、暂停向该服务器转发**（不是「临时开放」），恢复健康后自动放行。

**Q：怎么让某个密钥组完全不能用 MCP？**
密钥组 MCP 子页签里 `allowed_tools` 留空、`allowed_tags` 留空，或不勾选任何工具。

**Q：MCP 服务器挂了会影响其他工具吗？**
不会。每个服务器有独立的连接管理和熔断保护。一个服务器不可用时，其工具从列表中排除，其他服务器正常工作。

**Q：tools/search 是什么？**
内置的元工具，用 BM25 关键词在所有可用工具中搜索。工具数量多（50+）时用于快速定位目标工具。

**下一步**：[MCP 代理外部工具 quickstart](/zh-CN/quickstart/mcp-proxy.md) 看快速跑通示例；[MCP 配置](/zh-CN/reference/mcp-config.md) 看工具 ACL、上下文预算、REST bridge 字段细节；[端点 · 认证 · 协议互通](/zh-CN/reference/endpoints.md) 看完整端点清单。