Variants

Field reference for Surface Variants: named surface snapshots selectable at request time via $alias.

A Surface Variant is a named, switchable snapshot of an Agent Surface. A variant can override the surface’s Access Point, Managed Agent, Transit Point, identity, networking, and payment settings. A variant’s Transit Points always use the MCP tool gating, policy, and response policy of the base surface’s Transit Point with the same alias; see Transit Points on a variant. Variants are selected at request time by appending $alias to the surface route. Use variants to route test traffic through a staging configuration, offer partners a customised view of the same agent, or run A/B experiments without duplicating the base surface.

https://<GATEWAY_HOST>/<route>$<alias>/<optional-path>

When no $alias is present, the gateway routes to the default variant. The base is the default unless a named variant has the Default toggle on.

Variant fields

FieldTypeRequiredDefaultDescription
Variant IDstring (UUID)Auto-generated—Stable internal identifier. Auto-assigned on creation. Survives renames of alias and name. Never editable in the panel.
NamestringYes—Human-readable name shown in the dashboard and in the variants widget on the canvas.
AliasstringYes—URL-safe alias used in the route path. Must match ^[a-z0-9-]{1,32}$ (lowercase letters, digits, dashes; max 32 characters). Must be unique within the surface.
DescriptionstringNo""Free-text description.
EnabledtoggleNoOnWhether this variant accepts traffic. A request to a disabled variant gets HTTP 404, the same as an alias the surface doesn’t have. The default variant cannot be disabled; promote another variant to default first.
DefaulttoggleNoOffWhen on, alias-less requests route to this variant instead of the base. One variant can be default at a time.

Alias grammar

The alias must satisfy ^[a-z0-9-]{1,32}$:

  • Lowercase ASCII letters, digits, and dashes.
  • No underscores, dots, or uppercase.
  • Between 1 and 32 characters.
  • Must be unique across all variants on the same surface.

Validation is enforced server-side. Malformed aliases are rejected on create and update.

Lifecycle states

StatusRequest behaviour
ActiveVariant is active and serves traffic.
DisabledVariant exists but answers HTTP 404. Use this to pause a variant without deleting it. The default variant cannot be disabled.

The base variant

The base row is always present in the Variants panel. It represents the unmodified surface with no variant overlay applied. The base:

  • Has no alias and cannot be given one.
  • Cannot be renamed or disabled.
  • Is the implicit default when no named variant has the Default toggle on.

Requests with no $alias token route to whichever variant has the Default toggle on. If no named variant is set as default, requests route to the base.

Requests that no variant serves

The gateway serves the variant a request names, or the default when it names none. When that variant can’t serve the request, the gateway refuses it rather than serving another variant or the base:

RequestAnswer
$alias names a variant the surface doesn’t have, including any alias on a surface with no variantsHTTP 404, “No surface variant is served at this URL”.
$alias names a disabled variantHTTP 404, “No surface variant is served at this URL”.
No $alias, and the surface’s default variant setting names a variant that no longer existsHTTP 500, “Surface variant configuration error”.

On an MCP surface, a request that uses the 2026-07-28 protocol revision gets the same answer as a JSON-RPC error with code -32603. Other requests get a plain error. Each refusal is recorded in the audit log as Request Rejected.

Requests from a connected gateway

A connected gateway reaches this surface through a Managed Agent or Transit Point set to via Gateway Connection. Such a request is served by this surface’s default variant, or by the base when no variant is the default. The $alias that a caller used on the sending gateway selects a variant of the sending surface only, and never reaches this gateway.

Configuring a variant

Variant configuration is managed on the canvas, not inside the Variants panel. The panel only manages the variant list (name, alias, enabled/default status).

To configure what a variant does:

  1. Open the Variants panel and add the variant if it does not exist yet.
  2. Switch to the variant using the variants widget in the surface builder.
  3. Edit elements on the canvas: Access Point settings, Managed Agent settings, Transit Points, Policy, Networking, Payment, and Identity elements, exactly as you would for the base surface.
  4. Switch back to base or another variant to restore that state.

Each variant maintains its own independent canvas state. Surface-level identifiers and settings are always inherited from the base, so every variant shares the base surface’s Entry point URL. These settings stay the same across every variant:

  • Listen address
  • Surface prefix and custom path
  • Protocol
  • A2A supported versions and message validation
  • Outbound listen address

Transit Points on a variant

A variant’s Transit Point always runs with the MCP tool gating, policy and response policy of the surface’s Transit Point with the same alias. Set these on the base surface’s Transit Point. Saving a variant whose Transit Point sets a different value for any of them, or sets one where the base surface has no Transit Point with that alias, is refused with 400. A variant Transit Point that leaves them out uses the base surface’s values.

Authorization server discovery on a variant

On an MCP surface whose Caller Context uses JWT Bearer with Authorization server discovery on, each enabled variant advertises a protected resource of its own: the Resource URL with $<alias> appended, for example https://gateway.example/mcp/alpha$staging. The gateway publishes that variant’s metadata document at /.well-known/oauth-protected-resource followed by <route>$<alias>, and accepts on the variant only tokens whose aud is the variant’s resource. A token issued for the base resource or for another variant is refused.

When you edit a variant, the Caller Context fullscreen editor shows this value under Resource of this variant. Each variant’s discovery setting is its own, so set it in that variant’s Caller Context. The default variant also answers on the surface route without an alias, where it advertises the Resource URL as written and accepts tokens issued for it.