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

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

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

本章内容：本章面向租户管理员、系统管理员、工作空间管理员和普通成员，说明如何把企业已有的远程 MCP 服务与 HTTP 接口纳入 Zenova 统一治理，再交给两类使用方：Zenova 内的智能体与员工对话，以及成员本地的 MCP 客户端和业务系统。完整过程是：管理员接入服务并核对工具清单，配置上游鉴权，发布并分发给成员，用流量规则控制可调用的工具与方法；成员把服务连接到自己的智能体，或获取连接配置写入外部客户端；管理员在「调用情况」「令牌管理」与「操作审计」中追溯每一次调用。

平台提供两类服务：

两类服务共同的规则：

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

22.1 接入 MCP 服务的六种方式

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

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

操作步骤

1. 进入「管理后台 › 能力 › MCP 服务」，在「MCP 列表」页签右上角选择「添加应用」，填写「MCP 名称」「描述信息 (可选)」「分类」「实例请求头」，并在 Markdown 区域写明供成员阅读的用途、数据边界与使用示例。
2. 在顶部三个页签中按资产形态选择：「MCP」「由接口文档生成」「手动添加」，再选具体方式：

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

你会看到

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

注意

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

22.2 查看工具、资源与提示词

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

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

你会看到

• 每个工具带一个副作用徽标：只读接口标「读取」，会改动数据的标「写入」，写入类以橙色区分。由文档生成的工具按 HTTP 方法推断，远程 MCP 工具以上游声明为准。
• 不符合协议规范或参数定义过于复杂的工具标「已排除」，并说明原因（如「该工具的参数定义过于复杂，超出平台上限，已排除」），这类工具不会提供给成员与智能体。
• 页面上方提示：「如需禁用部分工具，或只允许调用指定工具，请新建流量规则：条件已预填本服务与「MCP 方法 等于 调用工具」，再选择「工具名」属于或不属于所列工具，动作选择拒绝。」选择「新建流量规则」直接打开规则编辑弹窗，条件已按提示预填。
• 「资源」「提示词」页签列出上游声明的内容；上游未提供时显示「对方未提供任何资源。」或「对方未提供任何提示词。」。

注意

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

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

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

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

操作步骤

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

你会看到

• 页面提示「分发已保存」，「企业内成员」下列出已分发的成员。
• 范围内成员在工作台顶部「MCP」中看到该服务卡片并可获取连接配置，也能在「应用市场」中把它连接到自己的智能体（见第 22.13 节）；范围外成员的卡片标注「需要管理员分发」。成员被移出范围并保存后，其此前拿到的连接配置立即不可用。

注意

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

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

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

操作步骤

1. 打开服务详情「基本信息」，在「鉴权」一栏选择「编辑」，打开「MCP 鉴权」。
2. 选择「凭据来源」：

1. 平台统一配置时选择「鉴权方式」（「Bearer 令牌」「API 密钥」「基础认证」「Cookie」「自定义请求头」）并填写凭据；选「自定义请求头」时填写名称与值。选「调用方透传」时声明「调用方请求头名称」与「上游请求头名称」的对应关系。然后选择「确认」。

你会看到

• 页面提示「配置已保存」，「基本信息」显示统一凭据的配置状态与所选鉴权方式。凭据加密保存、不回显明文，编辑时留空表示保留原值；上游回显的凭据内容返回客户端时替换为 [REDACTED]。
• 「调用方透传」选 Bearer 时，调用方在 X-Upstream-Authorization 请求头中携带完整的 Bearer 令牌（例如 Bearer xxx），网关转发为上游的 Authorization。

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

注意

• 两层请求头都会送达上游，配置时避免同名；截图、培训材料、邮件和工单中不要出现真实凭据。
• 改为「使用用户个人凭据」后，未提供个人凭据的成员即使持有旧令牌也会被拒绝，上游不会收到无凭据请求。
• 「调用方透传」的服务只能由外部客户端或业务系统调用，不能安装到 Zenova 智能体——应用市场中会提示「该 MCP 使用调用方透传凭据，不能安装到智能体」。

成员完成个人授权

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

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

授权完成后提示消失、服务可正常调用；上游撤销过授权后，「完成授权」按钮会再次出现。成员在「应用市场」把服务连接到智能体时，也会被要求先完成 OAuth 授权（见第 22.13 节）。

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

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

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

操作步骤

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

你会看到

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

注意

• 令牌缺失或无效这类鉴权失败在客户端表现为 401、不进入调用记录，排查以客户端错误码为准（见第 22.8 节）。
• 查看完整载荷需要部署时开启报文归档，每次查看都写入审计记录。
• 「操作审计」页签记录该服务的创建、发布、鉴权、可用范围与令牌变更。

22.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 调用」。

注意

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

22.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. 在客户端中确认已连接并列出工具，各选一个只读工具调用一次。

你会看到

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

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

22.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；排障按「是否由本服务签发、是否仍在范围内、是否已被删除」核对。
• 长耗时工具超出网关超时上限才返回超时错误，接入前先确认该上限。

22.9 平台作为 MCP 授权服务器

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

前提：租户在安全策略中允许 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 令牌与手工签发的令牌受同样的可用范围、有效期与撤销规则约束。
• 租户用企业单点登录时，需在身份源一侧登记并允许平台的授权回调；未登记时客户端会停在企业登录页、拿不到授权码，此时先用连接配置接入。

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

适用场景：可用范围决定「谁能用这个服务」，流量规则进一步决定「能调用哪个工具、哪类方法」。规则对外部客户端与 Zenova 智能体的调用同样生效。

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

操作步骤

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

你会看到

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

注意

• 「资源」「提示词」两档按方法族整体匹配，不能细分到单个资源或提示词；需要更细的工具级授权时，把工具拆到不同服务分别分发。
• 规则按顺序评估，一条「结束匹配」的规则排在前面时，后面条件更窄的规则可能永远不命中，保存前在确认对话框中核对顺序；用「调用方」条件时还需把「调用类型」收窄为一种。
• 工具入参与返回内容中的敏感数据检测、危险操作防护也在流量规则中配置，见第 24.8 节与第 25 章。

22.11 配置 API 服务（HTTP 直传）

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

操作步骤（管理员）

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

操作步骤（成员）

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

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

你会看到

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

注意

• 上游地址按「上游端点 URL 的路径 + 调用路径」拼接。删除不可恢复；仅需临时停用时用「取消发布」，该服务不再能被调用，已签发的令牌随之失效。
• API 服务在流量规则中是独立的调用类型，可按「具体能力」「请求头」配置拒绝与限额。「应用市场」只列出 MCP 连接器；智能体需要调用某个 HTTP 接口时，把接口以第 22.1 节的方式接入为 MCP 服务。

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

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

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

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

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

注意

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

22.13 在智能体与员工对话中使用 MCP 服务

适用场景：让 Zenova 内的智能体在对话中调用企业系统，例如查询工单、读取 CRM 客户、写入文档。员工在对话中使用的工具，来自对话所选智能体已连接的应用。

前提：服务已发布并分发给操作人；操作人是目标工作空间的成员，且能管理目标智能体；工作空间策略允许使用该应用。

操作步骤

1. 在工作台顶部选择「智能体」，左侧进入「应用市场」（页面标题为「应用连接」）。页面列出当前工作空间可用的应用（MCP 连接器），可按分类筛选或搜索。
2. 打开应用卡片，在「安装到智能体」页签的「选择安装到的智能体」中勾选一个或多个智能体，或选「全部智能体」。
3. 应用需要凭据时，在「授权凭据来源」中选择：「个人授权凭据」（智能体以你的身份使用该应用）、「工作区共享授权凭据」或「平台共享授权凭据」（管理员已配置统一凭据时可用）。鉴权方式为 OAuth 时，先选择「授权」跳转到服务商完成授权，页面提示「OAuth 授权已完成，现在可以连接此应用。」后再继续。
4. 选择「安装到 N 个智能体」，等待进度显示「全部完成」。
5. 进入对话，选择已连接该应用的智能体，直接描述任务。智能体按需调用应用中的工具，调用过程显示在对话中；涉及写入或高风险操作时按智能体的审批设置处理（见第 14 章）。

你会看到

• 安装成功后提示「已将 <应用名> 安装到 <智能体名>」，可选择「查看智能体」；卡片显示「已连接」。
• 应用卡片的其他状态：「工作空间策略限制」表示该应用被工作空间策略禁用；「授权凭据待补完」「授权凭据异常」表示需要补充或重新配置凭据；「已安装，等待绑定到智能体」表示凭据已保存但尚未绑定成功，可在对话框中「重试绑定」。
• 智能体详情的技能与 MCP 列表中出现该服务；凭据缺失时提示「需连接账号」，配置变更后可能显示「待同步」或「待重启」，按提示操作后生效。
• 应用详情的「外部智能体接入」页签与第 22.6 节相同，可「生成令牌」并复制「MCP 配置 JSON」，供平台之外的智能体工具使用。

注意

• 应用要先在当前工作空间启用，才能绑定到智能体；未启用时提示「请先在当前工作空间启用该能力，再将其绑定到智能体。」工作空间不允许自助启用未纳入基线的应用时，联系工作空间管理员。
• 「调用方透传」凭据的服务不能安装到智能体（见第 22.4 节）。
• 智能体对 MCP 工具的调用同样经过可用范围、流量规则与敏感数据检测，并记入服务的「调用情况」。只为任务确实需要的智能体连接应用，避免把写入类工具交给面向大量成员的通用智能体。
• 成员看不到或连不上应用时，依次核对：服务是否已发布、本人是否在可用范围内且未过期、工作空间策略是否允许、凭据是否已配置、智能体是否已绑定该应用。

能力说明

---

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