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

完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。

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

本章内容：本章面向租户管理员、系统管理员和普通成员，说明如何把企业已有的远程 MCP 服务与 HTTP 接口，通过网关统一提供给成员和业务系统。完整过程是：管理员接入服务并核对工具清单，配置上游鉴权，发布并分发给成员，用流量规则控制可调用的工具与方法；成员在工作台获取连接配置写入客户端；管理员在「调用情况」「令牌管理」与「操作审计」中追溯每一次调用。

网关提供两类服务：

两类服务共同的规则：

• 保存不等于发布，发布不等于分发。新服务默认「未发布」「未分发」，需打开「发布」并配置「可用范围」，成员才能使用。
• 调用方只持有网关签发的令牌；上游地址与凭据由网关保管并在转发时注入，不交给调用方。
• 每次调用都记录调用人、来源、工具、状态与耗时，可在服务详情「调用情况」查看。

11.1 接入 MCP 服务的六种方式

适用场景：企业已有资产形态各不相同——远程 MCP 服务、OpenAPI 文档、cURL 命令、Postman 集合，或只有一个 HTTP 接口地址。网关按形态提供导入方式，导入后统一变成 MCP 工具。

前提：租户管理员权限；上游地址可从网关所在网络访问。

操作步骤

1. 进入「管理后台 › 能力 › MCP 服务」，在「MCP 列表」页签右上角选择「添加应用」，填写「MCP 名称」「描述信息（可选）」「分类」「实例请求头」及供成员阅读的说明。
2. 按资产形态选择导入方式：

1. 核对工具预览，选择「保存 MCP 服务」。

你会看到

• 远程 MCP URL 方式会探测到可用工具数，展开可看每个工具的描述与入参；由文档导入的方式在右上角显示「工具: N」。
• 保存后回到列表，新服务状态为「未发布」，可见范围为「未分发」。

注意

• 名称按输入原样保存展示，连字符与大小写都不改写；客户端里的服务键名由它生成，命名不要带空格。
• 导入提示会说明被跳过的接口与原因：网关无法承载的鉴权方式（如 OAuth）、同名参数同时出现在路径与查询或请求体中、接口未声明 2xx 的 JSON 返回结构（这类工具不附带返回字段说明）等，其余接口照常导入。
• 远程 MCP 支持「流式 HTTP」与旧版「HTTP 与 SSE」两种传输，不支持本地命令启动的 stdio 型服务。服务详情会显示探测到的「协议版本」与「传输」；上游仍使用旧版 HTTP 与 SSE 时，页面提示该传输方式已弃用、建议服务方升级，但不影响使用。
• 增删接口时用「编辑 MCP」重新粘贴文档，保存前会显示「预览检测到的 N 个工具」。

11.2 查看工具清单与副作用标记

适用场景：上线前确认服务有哪些工具、哪些会改动数据，据此判断分发给谁、是否需要额外限制。

操作步骤：打开服务详情「工具」页签，展开工具查看描述与入参结构，并查看工具旁的副作用徽标。上游还提供资源或提示词时，详情页会多出「资源」「提示词」页签。

你会看到

• 每个工具带一个副作用徽标：只读接口标「读取」，会改动数据的标「写入」，写入类以橙色区分。由文档生成的工具按 HTTP 方法推断，远程 MCP 工具以上游声明为准。
• 页面上方提示：「如需禁用部分工具，或只允许调用指定工具，请新建流量规则：条件已预填本服务与「MCP 方法 等于 调用工具」，再选择「工具名」属于或不属于所列工具，动作选择拒绝。」选择「新建流量规则」直接打开规则编辑弹窗，条件已按提示预填。
• 「资源」「提示词」页签列出上游声明的内容；上游未提供时显示「对方未提供任何资源。」或「对方未提供任何提示词。」。成员通过网关调用时，上游的资源与提示词同样经网关代理。

注意

• 工具页签只做展示，不提供逐个禁用或描述编辑。禁止某个工具请在流量规则中按「具体能力 + 工具名」配置（见第 11.10 节）。
• 上游工具变化（只读改成会写、新增会写工具）重新解析即生效，不进入审批。安全敏感的服务建议用流量规则只放行指定工具，使新增工具默认被拒。

11.3 发布并配置可用范围与有效期

适用场景：决定谁可以使用某个服务、用到什么时候。可用范围只做「允许」：勾选的对象可用，未勾选的不可用。

前提：服务已在「基本信息」中打开「发布」。

操作步骤

1. 打开服务详情的「可用范围」页签，选择「编辑可用范围」，搜索并勾选成员，右侧显示已选成员，选择「下一步」。
2. 在「配置目标有效期」中确认默认有效期（默认「长期有效」）。需要为个别成员单独设置时，勾选「为选中角色分配单独有效期」，选中该成员并取消「跟随默认」，选择「自定义」后设置起止时间。
3. 选择「保存」。

你会看到

• 页面提示「分发已保存」，「企业内成员」下列出已分发的成员。
• 范围内成员在工作台 › MCP 中看到该服务卡片并可获取连接配置；范围外成员的卡片标注「需要管理员分发」。成员被移出范围并保存后，其此前拿到的连接配置立即不可用。

注意

• 可用范围只做授权，不提供黑名单。需要「某类成员可用、个别人不可用」时，在流量规则里写拒绝规则：条件为「具体能力」属于该服务且「调用方」属于这些人。
• 使用「自定义」有效期时日期与时间需逐项选择；若面板意外关闭、设置丢失，重新打开「编辑可用范围」重设即可。新服务先分发给试点成员，临时项目用带结束时间的授权。

11.4 配置上游鉴权与两层请求头

适用场景：上游需要凭据才能调用。网关保管凭据并在转发时注入，调用方看不到上游密钥。

操作步骤

1. 打开服务详情「基本信息」，在「鉴权」一栏选择「编辑」。
2. 选择凭据来源：「平台统一配置」由管理员保存一份企业凭据、所有调用共用；「使用用户个人凭据」由成员使用自己的账号（见本节「成员完成个人授权」）。
3. 平台统一配置时选择鉴权方式（「Bearer 令牌」「API 密钥」「Basic Auth」「Cookie」「自定义请求头」）并按所选方式填写凭据；选「自定义请求头」时填写名称与值，然后选择「确认」。

你会看到

• 页面提示「配置已保存」，「基本信息」显示「统一凭据：已配置」与所选鉴权方式。凭据加密保存、不回显明文，编辑时留空表示保留原值；上游回显的凭据内容返回客户端时替换为 [REDACTED]。

请求头分三层，都会随调用送达上游：

注意

• 两层请求头都会送达上游，配置时避免同名；工单与截图中不要出现真实凭据。
• 改为「使用用户个人凭据」后，未提供个人凭据的成员即使持有旧令牌也会被拒绝，上游不会收到无凭据请求。

成员完成个人授权

服务以「使用用户个人凭据」接入时，成员需要各自完成授权：

1. 在工作台 › MCP 中打开服务，右侧「服务配置」显示鉴权类型。
2. 鉴权方式为 OAuth 时，页面提示「需要先完成你的个人授权才能使用」，选择「完成授权」，在打开的页面中登录上游账号并确认授权，完成后返回工作台。

授权完成后提示消失、服务可正常调用；上游撤销过授权后，「完成授权」按钮会再次出现。

注意：个人凭据由成员自己维护，管理员看不到明文；授权按成员分别生效，成员之间无法共享。

11.5 查看调用情况与可用性探查

适用场景：确认服务被谁、用什么客户端、调用了哪些工具，失败原因是什么，上游是否在线。

操作步骤

1. 打开已发布服务的「调用情况」页签，查看「调用量」「成功率」「平均耗时」「P95 耗时」「近 60 秒调用数」，在「最近调用」中核对时间、来源、用户、工具、状态与耗时。
2. 打开「可用性探查」页签，选择「检查连接」探活。

你会看到

• 最近调用按时间倒序列出，来源区分「自定义客户端」「外部智能体」等，用户为真实调用人；「近 60 秒调用数」空闲时为 0。
• 远程 MCP 服务探活后显示「MCP 服务连接可用」，并保留「基础连通性」「系统检查／手动检查」的记录与延迟。
• 由文档导入的 HTTP 转换型服务探活后显示「该服务没有可探查的远程端点」：这类服务由网关直接代理上游接口，无远程 MCP 连接可探测，属正常结论。

注意

• 令牌缺失或无效这类鉴权失败在客户端表现为 401、不进入调用记录，排查以客户端错误码为准（见第 11.8 节）。
• 查看完整载荷需要部署时开启报文归档，每次查看都写入审计记录。

11.6 签发 MCP 令牌并导出连接配置

适用场景：成员把服务接入自己的 MCP 客户端，管理员集中查看与回收令牌。

操作步骤（成员）

在工作台 › MCP 中打开已分发给自己的服务，选择令牌有效期（如 8 小时），选择「获取连接配置」。页面提示配置仅本次显示，选择「复制 JSON」或「下载 JSON」。

导出的配置如下（令牌以 zg_mcp_ 开头，示例已省略）：

{
  "mcpServers": {
    "service_name": {
      "type": "streamable-http",
      "url": "https://<网关地址>/api/v1/agent-gateway/mcp-servers/<服务 ID>/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_TOKEN>",
        "x-zenova-auth-mode": "token"
      }
    }
  }
}

你会看到

• 面板显示到期时间，并提供「复制 JSON」「下载 JSON」「撤销令牌」；配置地址是网关统一入口，不含上游地址、上游凭据与内部地址。
• 「管理后台 › 审计与合规 › 操作审计」中出现「MCP 连接令牌 · 签发」记录，含操作人与时间；复制与下载不单独留痕。

操作步骤（管理员）：进入「MCP 服务 › 令牌管理」，按名称、用户或服务搜索，打开令牌核对签发与到期时间、最近活动、来源、审计状态与事件类型；需要回收时删除该令牌。

你会看到

• 列表显示令牌状态、所属服务、用户与签发、到期时间；详情的来源、最近活动、审计状态、事件类型均为可读中文，如「未使用凭据」「MCP 调用」。

注意

• 令牌代表签发人本人，仅限个人使用；明文只在签发时显示一次，未保存的需要重新签发。删除服务或把成员移出范围后，相关令牌立即不能再调用。

11.7 在外部客户端中接入与多服务聚合

适用场景：把导出的连接配置写入常用客户端，并在一个客户端里同时使用多个 MCP 服务。

操作步骤

1. 按客户端要求写入配置：支持 mcpServers 的客户端（Claude Code、Codex 等）把导出的条目合并进其 MCP 配置，不要覆盖已有条目。
2. 需要同时使用多个服务时，分别获取各服务的连接配置，把各自的 mcpServers 条目合并到同一个配置文件：

{
  "mcpServers": {
    "service_a": { "type": "streamable-http", "url": "https://<网关地址>/api/v1/agent-gateway/mcp-servers/<服务 A ID>/mcp", "headers": { "Authorization": "Bearer <令牌 A>" } },
    "service_b": { "type": "streamable-http", "url": "https://<网关地址>/api/v1/agent-gateway/mcp-servers/<服务 B ID>/mcp", "headers": { "Authorization": "Bearer <令牌 B>" } }
  }
}

1. 在客户端中确认已连接并列出工具，各选一个只读工具调用一次。

你会看到

• 一个任务里可连续调用不同服务的工具，结果分别返回；两个服务各自的「调用情况」中出现对应调用并归属真实调用人；一个服务的调用被拒绝不影响另一个。

注意：服务键名由服务名生成，互不冲突，合并不需要改动地址或令牌。合并只在客户端侧完成；令牌各自独立有效期，某个过期只影响该服务的调用。

11.8 网关端点行为与错误语义

适用场景：接入客户端时的行为确认与失败排查。

协议与会话

• 网关入口支持 MCP 的五个协议版本：2024-11-05、2025-03-26、2025-06-18、2025-11-25 在握手时回显客户端请求的版本；2026-07-28 不需要握手，客户端在 MCP-Protocol-Version 请求头中声明版本即可。接入时无需在网关侧指定版本。
• 主入口 …/mcp-servers/<服务 ID>/mcp 使用流式 HTTP，不先握手直接调用工具也能正常返回，不依赖会话标识；握手响应带 Mcp-Session-Id 时，客户端照常在后续请求中回传即可；与上游之间的会话由网关内部维持。不带会话的 GET 返回 405，不带会话的 DELETE 返回 400；部分客户端退出时会话删除请求失败，不影响调用结果。
• 只支持旧版 HTTP 与 SSE 传输的客户端，改用同一服务下的 …/sse（建立事件流）与 …/messages（投递请求）两个地址，令牌与可用范围规则相同。

客户端收到的错误

错误响应不含内部堆栈、内部地址与上游密钥；上游错误正文以不受信内容包裹，便于与记录对账。

注意

• 工具类错误以 HTTP 200 加 isError: true 返回，这是 MCP 协议的要求，客户端应把它当作工具失败而非网络错误。
• 令牌被伪造、被撤销、对象被移出范围三种情况，客户端看到的都是 token_invalid；排障按「是否由本服务签发、是否仍在范围内、是否已被删除」核对。
• 长耗时工具超出网关超时上限才返回超时错误，接入前先确认该上限。

11.9 平台作为 MCP 授权服务器

适用场景：支持 OAuth 的 MCP 客户端不必手工复制令牌，首次连接时自动跳到网关登录授权，由网关签发令牌。

前提：租户在安全策略中允许 OAuth 接入方式，成员在服务的可用范围内。

工作过程

1. 客户端不带令牌访问 MCP 地址，网关返回 401，WWW-Authenticate 中给出受保护资源元数据地址，客户端据此自动发现授权服务器。
2. 客户端读取受保护资源元数据（authorization_servers 指向网关，scopes_supported 含 mcp），再读取授权服务器元数据，得到授权、令牌与注册三个端点；网关声明支持 refresh_token，令牌端点不要求客户端密钥。
3. 客户端通过动态客户端注册（POST /api/v1/mcp/oauth/register）取得客户端标识，按授权码 + PKCE S256 发起授权；成员登录并确认授权后，客户端换取以 zg_mcp_ 开头的令牌，随后正常调用。

你会看到

• 注册成功返回 201，回显客户端名称、回调地址、授权范围与 PKCE 能力。
• 授权链接不完整、已过期或不再绑定当前浏览器时，页面显示「授权请求已失效」，提示返回客户端重新发起（HTTP 400，invalid_request）。

注意

• OAuth 令牌与手工签发的令牌受同样的可用范围、有效期与撤销规则约束。
• 租户用企业单点登录时，需在身份源一侧登记并允许网关的授权回调；未登记时客户端会停在企业登录页、拿不到授权码，此时先用连接配置接入。

11.10 用流量规则按工具与方法管控 MCP 调用

适用场景：可用范围决定「谁能用这个服务」，流量规则进一步决定「能调用哪个工具、哪类方法」。

前提：调用方已在服务的可用范围内；需要「动态路由」许可模块。

操作步骤

1. 在「管理后台 › 流量 › 流量规则」中选择「新建规则」。
2. 添加条件（条件之间为「且」）：「调用类型」选「MCP 调用」，「具体能力」选目标服务；需要按工具限制时加「工具名」，需要按方法限制时加「MCP 方法」。
3. 选择「添加处置动作 › 拒绝本次调用」并填写原因代码，再选择「保存规则」，在确认对话框中核对匹配条件、执行动作与命中顺序，选择「确认并应用」。

你会看到

• 被拒绝的 tools/list 返回 JSON-RPC 错误 execution denied: tenant_route_policy，HTTP 仍为 200；同一入口的 tools/call 不受影响——只拦「列出工具」的规则不拦「调用工具」。
• 「MCP 方法」的可选项为「调用工具」「列出工具」「资源」「提示词」。上游不提供资源与提示词时，网关透传空集。

注意

• 「资源」「提示词」两档按方法族整体匹配，不能细分到单个资源或提示词；需要更细的工具级授权时，把工具拆到不同服务分别分发。
• 规则按顺序评估，一条「结束匹配」的规则排在前面时，后面条件更窄的规则可能永远不命中，保存前在确认对话框中核对顺序；用「调用方」条件时还需把「调用类型」收窄为一种。

11.11 配置 API 服务（HTTP 直传）

适用场景：业务系统按上游原接口访问，不转成 MCP 工具。网关负责鉴权、分发、凭据注入与记录，请求与响应原样转发。

操作步骤（管理员）

1. 进入「管理后台 › 能力 › API 服务」，选择「新建服务」，填写「名称」「上游端点 URL」，按需添加实例请求头与分类，选择「保存」。
2. 需要向上游注入凭据时，在「基本信息」的「鉴权」一栏配置；然后打开「发布」，在「可用范围」页签分发（方法同第 11.3 节）。

操作步骤（成员）

1. 在工作台 › API 中打开服务，查看「调用方式」说明。
2. 选择令牌有效期，选择「生成令牌」，复制「代理地址」与令牌，把上游路径拼在代理地址之后发起请求：

curl "<代理地址>/get?q=hello" \
  -H "Authorization: Bearer <API_SERVICE_TOKEN>"

你会看到

• 经网关的返回与直连上游一致，查询参数与请求体原样到达上游；上游看到的请求头只有标准项，不含网关内部使用的头，调用方的 Authorization 也不转发。
• 删除服务时确认框写明「这会从目录中移除此 API 服务，并撤销它的凭据」，删除后提示「API 服务已删除」。

注意

• 上游地址按「上游端点 URL 的路径 + 调用路径」拼接。删除不可恢复；仅需临时停用时用「取消发布」，该服务不再能被调用，已签发的令牌随之失效。
• API 服务在流量规则中是独立的调用类型，可按「具体能力」「请求头」配置拒绝与限额。

11.12 管理分类并在工作台浏览目录

适用场景：用分类组织工作台目录，便于成员查找已分发给自己的能力。

操作步骤（管理员）：进入「MCP 服务 › 分类管理」，新建分类并命名，在右侧选择「添加应用」，搜索并加入服务；不需要时从分类中移除。「应用数量」随加入与移除更新，成员工作台 › MCP 左侧的分类筛选同步更新。

操作步骤（成员）：在工作台顶部导航的「MCP」「API」等页签里，于页内搜索框输入关键词或在左侧按分类筛选，选择卡片的「查看详情」。

你会看到：已分发的服务可获取配置，未分发的标注「需要管理员分发」；详情页的「工具」页签只读，列出工具名、副作用徽标与入参。

注意

• 分类只影响展示与筛选，不影响可用范围，调整分类不会撤销分发。一次「添加应用」只做一条归属变更，数量随即正确，不必重复点击。
• 目录只展示已发布的能力，需要完全隐藏的服务保持「未发布」。跨类型查找用右上角全局搜索，未命中时改用页签内的搜索与分类筛选。

能力说明

---

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