MCP 配置

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

接入外部 MCP 服务器的操作步骤见接入外部 MCP 服务器，快速上手跑通示例见 MCP 代理外部工具。本章是配置参考。

客户端调用 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[]}`）
启用

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

连接类型选择

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

延迟加载

设 defer_loading = true 时，服务器在首次 tools/list 或 tools/call 时才加载工具 schema。适用于：

工具服务器数量多但大部分不常用
减少启动时间

健康检查

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

即路径 /health、探测间隔 60s、超时 5s（间隔默认 60s、超时默认 5s）。

⚠️ 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 服务器的完整案例。本页只讲 MCP 配置字段。

单工具级 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 服务器有独立熔断保护（连续失败会临时 Open）。

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

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

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

下一步：接入外部 MCP 服务器看操作步骤；MCP 代理外部工具 quickstart 看快速跑通示例；访问密钥与密钥组字段看密钥组的 MCP 维度；环境变量配置参考看全部环境变量。

MCP 配置 ​

客户端调用 MCP ​

JSON-RPC 方法 ​

MCP 服务器字段 ​

连接类型选择 ​

延迟加载 ​

健康检查 ​

REST bridge ​

工具 ACL ​

评估顺序 ​

ACL 示例 ​

上下文预算与优先级 ​

完整案例 ​

常见问题 ​