11. 配置并分发 MCP 服务与 API 服务

返回概览 · 完整版目录 · 下载完整 PDF

网关通过两类服务向成员和业务系统提供外部工具与接口：

两类服务都属于「基础功能」，由租户管理员或「系统管理员」维护。完整配置包括连接、鉴权、发布状态和可用范围。仅保存服务不代表成员或业务系统已经获得使用权限。

11.1 创建 MCP 服务

在「MCP 服务」页面的「MCP 列表」标签选择「添加应用」，进入「添加 MCP 服务」。先填写公共信息：「MCP 名称」、「MCP 图标」（JPG、PNG、WebP、GIF，最大 2 MB）、「分类」、「描述信息 (可选)」，以及右侧「Markdown」中供成员阅读的用途、数据边界和使用示例。

再选择接入方式。页面顶层分为「MCP」「由 HTTP 接口生成」和「手动添加」三组，共六种方式：

由 HTTP 接口生成的工具由网关承担 MCP 协议，上游保持普通 HTTP 接口，凭据由网关注入。导入 OpenAPI 时，页面在「导入提示」中列出需要处理的问题，例如文档声明了多个服务地址、API 密钥位于查询参数、接口数量超过导入上限或缺少 operation ID。

远程 MCP 的传输协议限制如下：

• 支持 Streamable HTTP。通过「远程 MCP URL」接入的上游仅支持旧版 HTTP + SSE 时，平台仍可连接，详情页显示弃用提示。
• 「MCP Json」中的传输类型只接受 Streamable HTTP 的各种写法，声明为 sse 的条目不能导入。
• 不支持 stdio 方式（以 command 启动）的本地 MCP。

保存前发现工具：

1. 填写连接信息后，离开连接配置区或选择「解析 Tools」。页面提示「正在连接 MCP 服务并解析 Tools…」，完成后显示发现的工具数量。
2. 在工具预览中核对工具名称、描述和参数。预览会标出每个工具的副作用：「读取」「写入」或「破坏性」。
3. 选择「保存 MCP 服务」。工具探测失败时仍可先保存，之后再重试。

上游在列出工具时也要求鉴权，而平台尚未保存凭据时，可在 MCP 详情的「工具」标签选择「临时凭据」，在「使用临时凭据获取工具」中填写「Bearer 令牌」或「附加 Header」，然后选择「获取工具列表」。该凭据只用于本次请求，不保存在平台上，也不能用于后续调用；平台只保存发现的工具。

已保存服务的「工具」标签列出「已发现工具」及其「输入参数」，并显示可调用、漂移和过期的工具数量。上游工具变化后，使用该标签右上角的刷新按钮重新发现工具。

MCP 地址的出站访问受平台级「SSRF 出站防护」约束。该防护默认关闭，关闭时只校验地址格式与协议，MCP 地址可以指向内网、回环等任意地址；开启后，指向私网、回环、链路本地或云元数据的地址一律被拒绝。接入不受信的 MCP 前，应由平台管理员开启该防护，或通过出口代理、网络策略限制可访问的目标。

11.2 配置鉴权与请求头

在 MCP 详情「基本信息」的「鉴权」区域选择「编辑」，打开「MCP 鉴权」。

「凭据来源」有三种：

「鉴权方式」可选「设备码」「OAuth」「扫码授权」「Bearer 令牌」「API 密钥」「Basic Auth」「Cookie」「自定义 Header」和「统一连接」。OAuth 类方式需要上游支持相应授权流程。

请求头分两层配置：

• 「实例 Header」：在创建或编辑连接时配置，随连接固定携带，适合租户实例级的固定参数。
• 「凭据 Header」：鉴权方式选择「自定义 Header」时在鉴权表单中配置，按凭据保存，适合真正用于认证的信息。

同名 Header 以鉴权方式中的配置为准。Header 值和企业凭据按密文字段加密保存，保存后不会明文回显，编辑时留空表示保留原值。截图、培训材料、邮件和工单不得包含真实值。

11.3 发布与分发

「发布」开关位于 MCP 详情的「基本信息」中，列表中的状态显示为「已发布」或「未发布」。发布与分发的职责不同：

服务未发布时，「可用范围」标签提示先在「基本信息」中发布。分发步骤如下：

1. 打开 MCP 详情的「可用范围」标签，选择「编辑可用范围」。
2. 在「可用范围」中按目标类型（「所有用户」「部门」「职能组」）筛选，或搜索成员，把需要授权的目标加入已选列表。部门行上的「下级」用于展开子部门；授权给部门时，其下级部门的成员同样获得授权。
3. 在「配置目标有效期」中设置「默认有效期」：「长期有效」「7 天」「30 天」或「自定义」。需要时勾选「为选中角色分配单独有效期」，为个别目标单独设置有效期，或选择「跟随默认」。
4. 核对已选目标与有效期后确认。

每个目标显示「生效中」「待生效」或「已失效」状态。有效期到期后授权自动失效，平台约每 30 秒扫描一次到期授权。

新服务应从试点部门或专用职能组开始分发。临时项目使用有截止日期的授权，避免项目结束后授权继续保留。成员的实际可见性和使用权限以平台权限校验结果为准，不要假定某类角色天然绕过可用范围。

11.4 MCP 连接验证与排查

发布到目标范围前，至少完成以下验证：

• 「工具」标签中的工具数量和名称符合预期，没有大量漂移或过期工具。
• 使用无效参数时，工具返回明确错误而不是静默失败。
• 试点成员能够在「MCP 广场」获取连接配置并完成调用，非授权成员无法签发 Token。
• 需要限制的工具已在「路由策略」中设置调用规则（见第 11.5 节），范围外的调用被拒绝。
• 可用范围到期后，目标成员不再能够调用该服务。
• 「调用情况」中出现真实调用记录，「可用性探查」显示连接可用。

成员看不到或无法使用 MCP 时，依次核对发布状态、可用范围、授权有效期和成员组织归属。工具不可用时，核对服务端点、请求头、上游权限和发现结果，不得在排查材料中记录密钥。

11.5 设置工具调用权限

MCP 服务的工具调用权限在「路由策略」中配置。

1. 打开 MCP 详情的「基本信息」，在左侧信息栏的「路由策略」一行选择「查看适用的路由策略」。页面跳转到「路由策略 → 流量规则」的规则清单，并预填「调用类型」和「能力」两个筛选，列出显式命中该服务的规则和未限定能力的规则。
2. 选择「新建规则」，添加条件（条件之间为“且”关系）：
   • 「调用类型」选择「MCP 调用」，「具体能力」选择该 MCP 服务；
   • 「工具名」：比较方式为「属于」或「不属于」。已选择该 MCP 服务时，可在「选择已登记的工具」中勾选工具，也可在「通配模式」中输入带 * 的模式，例如 delete_*；
   • 「MCP 方法」：可选「调用工具」「列出工具」「资源」「提示词」，新建时默认「调用工具」；
   • 「组织成员」：在「部门（含下级）」和「职能组」中选择，两类取并集，比较方式为「属于」或「不属于」；选择上级部门时同时覆盖其全部下级部门；
   • 调用方是具体成员时，再添加「调用方」条件，比较方式同样可选「属于」「不属于」。
3. 添加动作。不允许调用时选择「拒绝本次调用」，调用方收到 403 和所填的拒绝原因码；需要按匹配规则或判断模型检查调用参数与返回结果时，选择「内容检测（护栏）」的「工具调用防护」，见第 14.3 节。
4. 保存规则，在「确认变更」中核对后选择「确认并应用」，再用「验证规则」和范围内、范围外的账号分别验证（第 15.3 节）。

限定“只有某部门可以调用某个工具”时，写成一条拒绝规则：「调用类型」为「MCP 调用」，「工具名」属于该工具，「组织成员」不属于该部门；需要例外放行的成员，在同一条规则中增加「调用方」「不属于」条件。仅开放指定工具时，写一条拒绝规则，「工具名」不属于这些工具。含「组织成员」条件的拒绝规则，在平台无法解析调用者的部门成员关系时按条件满足处理，即拒绝调用，不会放行。

路由策略在服务的可用范围之上生效：调用方须先在 MCP 服务的可用范围内（第 11.3 节），再满足规则。「角色管理」中的管理角色只决定管理控制台各功能的查看与管理，不决定谁可以调用工具。

升级前在 MCP 详情「安全策略」中配置的工具权限、参数内容规则、默认处置和请求体上限，升级时转换为名称为「MCP 护栏迁移 · 服务名 · 项」的路由策略，排在租户原有策略之前。名称末项为「需人工改写」的策略按更严格的方式转换，拒绝该服务的相应调用，原配置全文写在策略说明中；请据此改写规则后停用或删除该策略。

11.6 查看调用情况与可用性

调用情况：MCP 详情的「调用情况」标签可按「最近 1 小时」「近 24 小时」「近 7 天」「近 30 天」查看「调用趋势」，以及「调用量」「成功率」「平均耗时」「P95耗时」「当前并发」和「限流」「熔断」状态。「最近调用」列出每次调用的「时间」「调用来源」「用户」「工具」「类型」「状态」「耗时」和「结果」，可打开「调用载荷」查看单次调用的请求与返回内容。

• 查看调用载荷需要部署时已配置报文归档存储；归档开启之前的调用没有留存报文。每次查看载荷都会写入一条审计记录。
• 限流、并发上限和熔断阈值在流量规则中配置（需要「动态路由」许可模块），MCP 作为一类调用与模型调用共用同一套规则，见第 15 章。

可用性探查：「可用性探查」标签记录服务端点的连通性。系统每 5 分钟自动检查一次，也可选择「检查连接」手动触发。记录列出「时间」「端点」「触发方式」（「系统检查」或「手动检查」）、「结果」和「延迟」，探查记录保留 30 天。

操作审计：「操作审计」标签记录对该服务的创建、修改、授权和凭据变更操作。

11.7 管理访问令牌 与分类

Token 管理：「MCP 服务」页面的「Token 管理」标签集中列出成员为各 MCP 服务签发的访问令牌，列包括「名称」「类型」「用户」「MCP 服务」「状态」「签发时间」「到期时间」「最后使用」。

1. 在「搜索名称 / 用户 / MCP 服务」中搜索，或按状态筛选「有效（未过期、未撤销）」「已过期」「已撤销」。
2. 打开某个 Token 查看状态原因、来源、成功率、使用记录和最近活动。
3. 需要回收时，单个选择「删除」，或勾选多个后选择「批量删除」。删除即撤销该 Token，此后不能再用于调用。

签发用户失去签发权限后，Token 会显示不可用原因。

分类管理：「分类管理」标签用于维护 MCP 服务在目录中的分类。选择「添加分类」新建分类，为分类选择图标、修改「分类名称」，在右侧通过「添加应用」「移除」调整分类下的服务。选择「删除分类」时，该分类下的服务回到原始目录分类或未分类状态，服务本身不会被删除。

11.8 成员在能力中心获取 MCP 接入配置

「MCP 广场」列出本租户已发布的 MCP 服务。成员不在可用范围内时，卡片显示「需要管理员分发」，无法签发连接配置。获取连接配置的步骤如下：

1. 打开 MCP 服务详情，在「服务配置」中选择「获取连接配置」。未登录时显示「登录后获取连接信息」。
2. 服务使用「使用用户个人凭据」时，先选择「新建应用凭据」填写个人凭据，或选择「完成授权」用个人外部账号完成 OAuth 授权。
3. 在「令牌有效期」中选择有效期，然后选择「确认签发 Token」。可选项包括租户默认有效期、24 小时、「48 小时」「7 天」和「自定义」，均不超过租户允许的最长有效期。
4. 按客户端要求复制 Streamable HTTP 地址或 JSON 配置。Token 仅显示一次，调用时使用当前成员身份，仅限个人使用。

租户可在「管理控制台 → 组织与权限 → 账号与会话安全」的「安全策略」中设置「允许类型」（「OAuth」「Token」）以及「默认 令牌有效期」「最长 令牌有效期」（1 至 168 小时）。开启 OAuth 后，成员可选择「显示 MCP 配置」，由 MCP 客户端按 Authorization Code + PKCE S256 完成登录授权；两种方式都关闭时，页面提示租户安全设置已关闭能力访问。

授权同意页：MCP 客户端发起 OAuth 授权时，网关作为授权方向成员展示「授权请求」页面，标题为「{客户端名称} 请求连接」，列出「回调目标」「完整回调 URI」「账号」和「访问范围」，并提示客户端名称由客户端自行提供、未经平台验证。成员核对回调地址和访问范围后选择「允许访问」或「拒绝」。请求超时后页面显示「授权请求已过期」，需回到客户端重新发起连接。

11.9 通过 MCP 管理网关

平台内置一个平台管理 MCP 服务，把管理控制台中的常用管理操作提供为 MCP 工具。管理员可在 Claude Code、Codex 等支持 Streamable HTTP 的 MCP 客户端中，通过对话或自动化任务完成日常配置。

该服务按调用者的真实身份执行：账号在页面上能执行的操作，在 MCP 中同样可以执行；页面上无权执行的操作，MCP 中返回同样的拒绝结果。每次调用经过与页面相同的认证、许可、变更控制和审计。

获取接入配置：

1. 在「MCP 广场」打开平台管理 MCP 服务的详情（描述以「平台管理 MCP」开头），选择「获取连接配置」。
2. 在「工具集」中勾选本次需要的功能分组。页面只列出当前账号和许可可用的工具集。
3. 选择「令牌有效期」后选择「确认签发 Token」，复制生成的配置写入 MCP 客户端。接入地址中的 ?toolsets= 参数表示已选工具集，访问令牌以 zg_mcp_ 开头。

当前开放的工具集如下：

使用限制如下：

• 调用未勾选工具集中的工具会被拒绝。
• 删除、停用和密钥轮换类工具采用两步确认：第一次调用不传 confirm 时只返回影响范围和确认提示，不执行写入；向用户展示影响并获得同意后，再以 confirm: true 调用同一工具才执行。
• 凭据只写不读：上游供应商密钥、外部 MCP 或 Agent 凭据、网关模型 Key 均无法通过 MCP 读回明文。创建或轮换模型 Key 时，明文只在该次响应中返回一次。

11.10 API 服务

API 服务以反向代理方式对外提供上游 HTTP 接口。网关统一完成调用方鉴权、授权分发、上游凭据注入和流量控制，请求和响应按原接口转发，不转换为 MCP 工具。需要供 MCP 客户端按工具调用时，应在「MCP 服务」中选择「由 HTTP 接口生成」。

页面包含「API 服务列表」「Token 管理」和「分类管理」三个标签。列表列包括「名称」「分类」「状态」「健康」「可见范围」和「添加时间」。

创建服务：

1. 选择「新建服务」，在「新建 API 服务」中填写「名称」「上游端点 URL」，按需添加「实例 Header」并选择「分类」，然后保存。
2. 需要向上游注入凭据时，在服务详情「基本信息」的「鉴权」区域选择「编辑」配置凭据。
3. 在「基本信息」中打开「发布」，再在「可用范围」标签按第 11.3 节的方法分发。

详情页标签包括「基本信息」「可用范围」「调用情况」「可用性探查」和「操作审计」，含义与 MCP 服务相同。可用性探查检查上游 HTTP 端点的连通性，每 5 分钟自动检查一次，记录保留 30 天。

调用方接入：成员在能力中心的「API 广场」页签打开服务详情，选择「生成 Token」签发短期访问令牌。面板给出「代理地址」「HTTP 方法」「请求路径」「请求体」「访问令牌」和「curl 示例」。调用地址格式为：

<网关地址>/api/v1/agent-gateway/proxy/<服务 ID>/<上游路径>

调用方在请求头中携带 Authorization: Bearer <访问令牌>。不再使用时选择「撤销 Token」。租户在安全策略中关闭 Token 访问时，成员无法获取 API 服务的连接配置。

流量控制：API 服务在流量规则中是独立的调用类型「API 服务」，可配置限流和熔断（需要「动态路由」许可模块），见第 15 章。

上一章：10. 调用接口 · 下一章：12. 外部智能体、技能、插件与外部注册中心