通过 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,providers,models,mcp,skills,a2a_agents,distribution,callers,quota",
      "headers": {
        "Authorization": "Bearer zg_mcp_..."
      }
    }
  }
}

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

2.2 访问密钥签名直连

SecretAccessKey 只在创建时显示一次，请立即保存。访问密钥的权限与创建人本人相同；账号被停用、平台管理员身份被撤销或密钥被撤销后，下一次调用立即失效。

需要按工具集收窄时，在地址上加 ?toolsets=（例如 /api/v1/mcp?toolsets=tenants），查询串同样参与签名。

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

3. 工具集说明

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

分发工具（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，服务端才会真正执行删除、停用或轮换。对于删除租户（tenant_delete），工具内部在 confirm: true 时会自动完成待办动作创建、确认与携带 X-Pending-Action-Id 删除的完整受控流程。

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

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

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