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


# MCP 配置

MCP（Model Context Protocol）网关把外部工具服务器聚合成统一入口，调用方用一把网关访问密钥就能调多个工具，且支持按密钥组做工具 ACL 与上下文预算。

接入外部 MCP 服务器的操作步骤见 [接入外部 MCP 服务器](/zh-CN/howto/onboard-external-mcp.md)，快速上手跑通示例见 [MCP 代理外部工具](/zh-CN/quickstart/mcp-proxy.md)。本章是配置参考。

## 客户端调用 MCP

调用方把 MCP 客户端指向网关：

- **Streamable HTTP**：`POST http://<host>:7890/mcp`（JSON-RPC 2.0）
- **SSE 传输**：`GET http://<host>:7890/mcp/sse`
- **认证**：`Authorization: Bearer <你的访问密钥>`

### JSON-RPC 方法

| 方法 | 说明 |
|------|------|
| `initialize` | 握手，交换能力 |
| `tools/list` | 列出可用工具（按该密钥组的 MCP ACL 过滤），含内置 `search_tools` 元工具 |
| `tools/call` | 调用工具，命名格式 `{server_name}.{tool_name}` |
| `tools/search` | BM25 关键词检索工具（工具多时用于定位） |

工具名是 `{服务器名}.{工具名}` 两段式。例如 `github.list_repos`、`slack.send-message`。

## 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[]}`） |
| 启用 | |

> 传输（transport）仅 `streamable_http` / `sse` 两种；REST 接入是通过连接类型 `connection_type = rest_bridge` 实现的（它是连接类型，不是传输）。**不支持** stdio / command / args / env / OAuth 形式的 MCP 服务器。

## 连接类型选择

| 类型 | 适用场景 |
|------|---------|
| `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
  }
}
```

`path` 可配，**必须是上游真实提供的端点**（上游没有 `/health` 却填了它，探测会一直失败、服务器被判死、工具不可见）；`interval_secs` 默认 60，`timeout_secs` 默认 5。

> ⚠️ `health_check`（及 `max_concurrency` / `rate_limit`）当前不在控制台「新建 MCP 服务器」表单里，属 Console API（PUT `/console/api/mcp-servers/{name}`）字段，UI 表单未渲染这几项；需要时通过 Console API 设置。

不健康的服务器的工具会从 `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 服务器 → 新建，依次填：**名称**=`weather-api`、**连接类型**=`REST Bridge`（选中后展开「OpenAPI 规范（JSON）」编辑器）、**端点地址**=`https://api.weather.example.com`；在「OpenAPI 规范（JSON）」编辑器里贴入 spec——它是简化的 `{title, version, operations[]}` 结构（每个 operation 含 `operation_id` / `description` / `method` / `path` / `parameters_schema`），不是标准 OpenAPI 3.x 的 `paths` 形态，例如：

```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 请求。

## 工具 ACL

工具权限配在**密钥组**的 `mcp_tool_acl`（不是配在 MCP 服务器）。控制台 → 访问密钥 → 密钥组 → 编辑 → MCP 子页签（仅当至少存在一个 MCP 服务器时显示）：

| 字段 | 说明 |
|------|------|
| `allowed_tools` | 允许调用的工具，支持通配符 `server.*` / `*.tool` |
| `denied_tools` | 拒绝调用的工具（最高优先） |
| `allowed_tags` | 允许的服务器标签 |

### 评估顺序

`denied`（最高）→ `allowed_tools` → `allowed_tags` → 默认

即先看是否被拒，再看是否被允许。

### ACL 示例

**允许全部 github 工具 + slack 发消息，拒绝删频道**：
在密钥组的 **MCP** 子页签：**允许的 MCP 工具**勾 `github.*`（整服务放行）。原例还希望「只放行 `slack.send-message`、只拒绝 `slack.delete-channel`」——这种**单工具级** ACL 在控制台界面里做不了（允许/拒绝选择器只提供整服务 `server.*` 开关，允许另多一个 `*` 全工具），须用 Console API 的 `allowed_tools` / `denied_tools` 精确填到工具名。

**只允许特定标签的服务器**：
在密钥组的 **MCP** 子页签，**允许的 MCP 标签**填 `internal, read-only`（逗号分隔的自由文本）。

**拒绝所有 MCP 工具**：
`allowed_tools` 和 `allowed_tags` 都留空。

## 上下文预算与优先级

当工具数量很多、上下文窗口紧张时，网关按 `priority` 裁剪工具描述：

- `priority` 小的服务器优先保留（0 = 最高优先级）
- 低优先级的工具描述可能被省略，但 `tools/search` 仍可检索到

适合工具数量多（100+）但上下文窗口有限的场景。

## 完整案例

按组授权聚合两个 MCP 服务器（github + slack）的完整走法见 [接入外部 MCP 服务器](/zh-CN/howto/onboard-external-mcp.md) 的完整案例。本页只讲 MCP 配置字段。

::: tip 单工具级 ACL
控制台界面的允许/拒绝选择器只提供整服务 `server.*` 开关；单工具级 ACL（如放行 `slack.send-message` 但拒绝 `slack.delete-channel`）须用 Console API 的 `allowed_tools` / `denied_tools` 精确填到工具名。
:::

## 常见问题

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

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

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

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

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

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

**下一步**：[接入外部 MCP 服务器](/zh-CN/howto/onboard-external-mcp.md) 看操作步骤；[MCP 代理外部工具 quickstart](/zh-CN/quickstart/mcp-proxy.md) 看快速跑通示例；[访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md) 看密钥组的 MCP 维度；[环境变量配置参考](/zh-CN/reference/configuration.md) 看全部环境变量。