Manage the gateway through MCP

2026.10 · Scope follows the current license, account permissions, and actual deployment.

1. When to use it and the permission principle

Platform MCP exposes core governance capabilities of the gateway Admin Console as standard Model Context Protocol (Streamable HTTP) task-level tools. After Claude Code, Codex, or a custom agent connects, day-to-day gateway configuration can be done in conversation or by automation.

Platform MCP follows two principles:

• Real identity, same permissions: MCP does not add a special role and does not relax any permission. What an account can do on the page, it can do through MCP. After a user is disabled, a role changes, or a tenant is disabled, an already issued MCP token fails on the next call (returns 401). Unauthorized calls return the same structured 403 as the page.
• The same processing path: Every tool call goes through the same authentication, tenant-posture check, license gate, control-plane change gate, and compliance audit as the admin page, and produces an audit record of the same shape as a page action.

2. Get connection settings (J0)

Platform MCP has two entries. Both run as the caller's real identity. They differ only in credential shape:

A platform account belongs to no tenant and can use only the Tenants toolset (create, update, enable/disable, and delete tenants, and manage tenant admins and tenant-wide quotas). Tenant accounts do not see the Tenants toolset. Under either entry, the tools an account can see and call are the same.

2.1 External-agent connection panel

1. Sign in to the console. In Capability Center or MCP, open the Connect external agent panel on the Zenova Platform card.
2. In Toolsets, tick the function groups this connection needs. The system shows only toolsets the current account and license may use. The Tenants toolset belongs only to platform accounts and does not appear on a tenant-account panel.
3. Choose token Validity (for example 7 days) and click Issue token.
4. Copy the generated JSON configuration (the token plaintext is shown only at issuance) and paste it into the external agent's MCP configuration file:

{
  "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_..."
      }
    }
  }
}

The ?toolsets= parameter on the connection URL names the toolsets loaded for this connection (comma-separated). If the parameter is omitted, the server returns every toolset available to the current identity.

2.2 Access-key signed direct call

1. Create an access key:
   • Platform administrator: in the platform console, open the account menu at the lower left › Settings › Access keys › Create access key.
   • Tenant account: create it in the Access keys area of API keys in Capability Center. SecretAccessKey is shown only at creation. Save it immediately. An access key has the same permissions as its creator. After the account is disabled, platform-administrator identity is revoked, or the key is revoked, the next call fails immediately.
2. For every call, POST one JSON-RPC request to https://<console-url>/api/v1/mcp (for example {"jsonrpc":"2.0","id":1,"method":"tools/list"}) and sign that request:
   • Headers include x-zenova-date (UTC time, format YYYYMMDDTHHMMSSZ, within 5 minutes of server time) and x-zenova-nonce (unique per request).
   • The canonical request is these six lines, joined by newlines: HTTP method, path (/api/v1/mcp), canonical query string (names and values sorted ascending and percent-encoded; empty line when there is no query string), signed headers sorted by name (each line lowercase-name:value, and this block itself ends with a newline), the signed-header name list (semicolon-separated), and the SHA-256 hex digest of the body.
   • The string to sign is three lines: ZENOVA-HMAC-SHA256, the value of x-zenova-date, and the SHA-256 hex digest of the canonical request. HMAC-SHA256 with SecretAccessKey, result in hex.
   • Header Authorization: ZENOVA-HMAC-SHA256 Credential=<AccessKeyId>, SignedHeaders=host;x-zenova-date;x-zenova-nonce, Signature=<signature>.
3. To narrow by toolset, add ?toolsets= to the URL (for example /api/v1/mcp?toolsets=tenants). The query string is part of the signature.

Even when the server splits one tool call into several internal steps, sign only this entry request. After the server authenticates once, every step runs as that identity.

3. Toolsets

kind on distribution tools (distribution_* and listing_set) accepts only the canonical enum values: mcp, skill, connector, builtin, cli, plugin, a2a_agent, knowledge_base, knowledge_base_maintain, channel, persona, model_service.

4. Two-step confirmation for destructive operations

Every delete, disable, and key-rotation tool is marked destructiveHint: true and uses the same two-step confirmation:

1. Step 1 (preview impact): Call the tool without confirm (or with confirm: false). The server writes nothing. It queries and returns structured impact data and a confirmation prompt.
2. Step 2 (confirm execution): After showing the impact to the user and getting explicit consent, the external agent calls the same tool again with confirm: true. Only then does the server perform the delete, disable, or rotation.

5. Credential safety boundary (write-only)

Platform MCP strictly follows write-only credentials:

• No plaintext credential read-back: Upstream provider API keys, external MCP/agent auth credentials, and model keys issued by the gateway cannot be queried in plaintext through MCP.
• Returned once: When you call model_key_create or model_key_rotate, the key plaintext in the response is returned only in that create or rotate response. Save it immediately or hand it to the caller. Later model_key_list, model_key_get, or model_key_check show only prefix, status, routing trial result, and remaining quota.