通过 MCP 管理网关

在外部智能体中接入平台 MCP，按真实身份完成租户、组织、用户、模型、MCP、Skill、外部智能体、分发、调用方与配额管理。

2026.10 · 操作范围以当前许可、账号权限和实际部署为准。

1. 适用场景与权限原则

平台 MCP 将网关管理控制台中的核心治理能力暴露为标准 Model Context Protocol（Streamable HTTP）任务级工具。Claude Code、Codex 或自建 Agent 接入后，可直接通过对话或自动化任务完成网关日常配置。

平台 MCP 遵循两条基本原则：

真实身份与同权执行：MCP 不设立特殊角色，也不放宽任何权限。同一个账号在页面上能执行什么操作，在 MCP 中就能执行什么操作；用户被停用、角色变更或租户停用后，已签发的 MCP 令牌在下一次调用时立即失效（返回 401），越权调用返回与页面一致的 403 结构化错误。
同一条处理链路：每个工具调用都经过与管理页面相同的认证、租户姿态校验、许可证闸门、控制面变更闸与合规审计，产生与页面操作完全同构的审计记录。

2. 获取接入配置（J0）

平台 MCP 有两个入口，都按调用者真实身份执行，区别只在凭据形态：

接入方式	适用对象	接入地址	凭据
外部智能体接入面板	租户管理员与成员；Claude Code、Codex 等只能配置固定请求头的标准 MCP 客户端	`https://<网关地址>/api/v1/agent-gateway/mcp-servers/10000000-0000-0000-0000-000000000010/mcp`	面板签发的 MCP 令牌（`Authorization: Bearer zg_mcp_…`）
访问密钥签名直连	平台管理员与租户账号；能为每次请求签名的自建 Agent、脚本或服务	`https://<控制台地址>/api/v1/mcp`	访问密钥（AccessKeyId / SecretAccessKey）签名

平台账号不属于任何租户，只能使用「租户」工具集（创建、修改、启停、删除租户，管理租户管理员与租户总配额）；租户账号看不到「租户」工具集。两种入口下，同一个账号能看到、能调用的工具完全一致。

2.1 外部智能体接入面板

登录控制台，在能力中心或 MCP 广场打开 Zenova Platform 卡片的“外部智能体接入”面板。
在 工具集 多选项中勾选本次接入需要使用的功能分组（系统仅展示当前账号与许可证有权使用的工具集；“租户”工具集只属于平台账号，租户账号的面板中不会出现）。
选择令牌 有效期（例如 7 天），点击 签发令牌。
复制生成的 JSON 配置（令牌明文仅在签发时展示一次），粘贴至外部智能体的 MCP 配置文件中：

{
  "mcpServers": {
    "zenova": {
      "type": "streamable-http",
      "url": "https://your-gateway.example.com/api/v1/agent-gateway/mcp-servers/10000000-0000-0000-0000-000000000010/mcp?toolsets=org,models,mcp,skills,a2a_agents,distribution,callers,quota",
      "headers": {
        "Authorization": "Bearer zg_mcp_..."
      }
    }
  }
}

接入地址中的 ?toolsets= 参数用于指定本次连接加载的工具集（多个工具集以英文逗号分隔）。若省略该参数，服务端默认返回当前身份可用的全部工具集。

2.2 访问密钥签名直连

创建访问密钥：
- 平台管理员：在平台管理台点击左下角账号菜单 › 设置 › 访问密钥 › 创建访问密钥。
- 租户账号：在能力中心 › API 密钥 页面的「访问密钥」区域创建。 SecretAccessKey 只在创建时显示一次，请立即保存。访问密钥的权限与创建人本人相同；账号被停用、平台管理员身份被撤销或密钥被撤销后，下一次调用立即失效。
每次调用都向 POST https://<控制台地址>/api/v1/mcp 发送一条 JSON-RPC 请求（如 {"jsonrpc":"2.0","id":1,"method":"tools/list"}），并对该请求签名：
- 请求头带 x-zenova-date（UTC 时间，格式 YYYYMMDDTHHMMSSZ，与服务端时间相差不超过 5 分钟）与 x-zenova-nonce（每次请求唯一）。
- 规范请求为以下六行，以换行符连接：请求方法、路径（/api/v1/mcp）、规范化查询串（按名称与值升序排列并做百分号编码，无查询串时为空行）、按名称排序的签名请求头（每行 小写名:值，该段自身以换行结尾）、签名请求头名称列表（以分号连接）、请求体的 SHA-256 十六进制摘要。
- 待签字符串为 ZENOVA-HMAC-SHA256、x-zenova-date 的值与规范请求 SHA-256 十六进制摘要三行；用 SecretAccessKey 做 HMAC-SHA256，结果取十六进制。
- 请求头 Authorization: ZENOVA-HMAC-SHA256 Credential=<AccessKeyId>, SignedHeaders=host;x-zenova-date;x-zenova-nonce, Signature=<签名>。
需要按工具集收窄时，在地址上加 ?toolsets=（例如 /api/v1/mcp?toolsets=tenants），查询串同样参与签名。

一次工具调用即使在服务端拆成多个内部步骤，也只需对入口这一次请求签名：服务端认证一次后，按同一身份执行全部步骤。

3. 工具集说明

工具集标识	名称	适用角色	涵盖能力
`tenants`	租户	平台管理员（平台账号）	创建、修改、启停和删除租户，管理租户管理员与租户总配额
`org`	组织与用户	租户管理员	部门与成员管理、职能组与成员管理、用户账号创建/改角色/重置密码/停用/删除
`models`	模型	租户管理员	模型供应商测试与管理、供应商账号/Key 管理与连通性测试、模型刷新、模型服务管理
`mcp`	MCP	租户管理员	MCP 服务探测、创建、导入、更新、删除、健康检查与工具列表同步
`skills`	Skill	租户管理员	Skill 来源分析、导入、元数据修改、从来源重新导入与删除
`a2a_agents`	外部智能体	租户管理员 / 成员	外部 A2A Agent 注册、探测、卡片刷新、审核、启停、凭据设置、可见性配置及对话任务调用
`distribution`	分发	租户管理员	模型服务、MCP、Skill、外部智能体等能力的上下架与分发范围设置
`callers`	调用方	租户管理员 / 成员	调用方应用管理、网关模型 Key 签发/启停/轮换/删除/转交/绑定应用、消费组成员与批量轮换
`quota`	配额	租户管理员	租户内各类对象配额读写、用量重置与模型 Key 路由及额度自检

分发工具（distribution_* 与 listing_set）的 kind 参数只接受规范枚举值：mcp、skill、connector、builtin、cli、plugin、a2a_agent、knowledge_base、knowledge_base_maintain、channel、persona、model_service。

4. 破坏性操作的二次确认机制

所有删除、停用与密钥轮换类工具均带有 destructiveHint: true 标注，并采用统一的两步确认流程：

第一步（预览影响面）：调用工具时不传 confirm（或传 confirm: false）。服务端不会执行任何写入，而是查询并返回结构化的影响面数据及中文确认提示。
第二步（确认执行）：向用户展示影响面并获得明确同意后，外部智能体再次调用同一工具并传入 confirm: true，服务端才会真正执行删除、停用或轮换。

5. 凭据安全边界（只写不读）

平台 MCP 严格遵守凭据只写不读原则：

不暴露任何凭据明文回读接口：无论是上游供应商 API 密钥、外部 MCP/Agent 认证凭据，还是网关签发的模型 Key，均无法通过 MCP 查询已有明文。
一次性返回：调用 model_key_create 或 model_key_rotate 时，响应体中的 Key 明文仅在该次创建或轮换响应中返回一次，请立即保存或交由调用方使用；后续通过 model_key_list、model_key_get 或 model_key_check 仅能查看前缀、状态、路由试算结果与剩余配额。