DSX Agent Gateway Architecture

DSX Agent Gateway provides a policy enforcement and routing layer between Model Context Protocol (MCP) clients and MCP servers. Without bridge routing, the gateway sends requests to targets that it can reach. The optional bridge extends selected requests to remote gateway shards through the DSX Event Bus. (Refer to Sessions and State for more details on the differences between direct and bridged requests.)

Components

The Helm chart coordinates the following components:

Component	Responsibility
Operator-owned edge	Terminates external TLS and routes HTTP traffic to the gateway Service.
Agent Gateway controller	Programs Agent Gateway resources from Kubernetes Gateway API and Agent Gateway custom resources.
Agent Gateway dataplane	Accepts `/mcp` traffic and applies authentication, authorization, rate limiting, and target routing.
Rate-limit service	Evaluates request limits with counters keyed by the verified tenant ID.
Valkey	Stores counters for the bundled rate-limit service.
MCP target	Serves MCP through a discovered Kubernetes Service or a configured static endpoint.
Bridge hub	Exposes reachable shards and routes selected MCP requests through NATS.
Bridge leaf	Receives work for one shard and forwards it through that shard’s local gateway.
DSX Event Bus	Provides NATS request-reply transport for the optional bridge.

The bridge components and DSX Event Bus are optional. Direct target routing does not use NATS.

Direct Request Flow

The following diagram shows the policy and routing stages for a direct request:

The gateway processes a direct request as follows:

The operator-owned edge sends an HTTP request to the gateway’s /mcp route.
The dataplane verifies the JWT issuer, audience, signature, and token validity against a configured provider.
A Common Expression Language (CEL) expression derives a nonempty tenant ID from the verified JWT claims.
The rate-limit service uses the tenant ID to select the tenant’s request budget.
MCP authorization permits the operator tenant to use all targets.
MCP authorization limits every other tenant to configured target names.
The Agent Gateway dataplane selects the target and forwards the caller’s original bearer token.
The MCP server applies any server-specific authorization and processes the request.

The chart rejects a tenant expression that reads request headers or does not reference verified jwt.* claims. Caller-supplied identity headers therefore do not define the tenant used for authorization or rate limiting.

At least one JWT provider is required. Each provider has a unique issuer, one or more allowed audiences, a JSON Web Key Set (JWKS) URL, and its own tenant expression. A token can contain additional audiences when at least one audience matches the provider configuration.

The rate-limit service keeps counters separate by derived tenant ID. Operators can configure one shared request rate, tenant-specific rates, or unlimited tenants. The configuration reference documents the chart defaults and failure modes.

Target Discovery and Routing

Agent Gateway combines the catalogs from the targets that a tenant can access. It uses target-qualified names to route a tool, prompt, or resource request to the selected server. An unavailable target does not prevent healthy targets from remaining available in a catalog response.

Selector targets match Kubernetes Services by namespace and labels. Each selected Service exposes an MCP port with appProtocol: agentgateway.dev/mcp. Agent Gateway discovers the Service endpoints and maintains session affinity to the selected endpoint when a client uses an MCP session.

Static targets specify an HTTP or HTTPS address and an optional MCP transport protocol. They are useful when Kubernetes Service discovery cannot represent the target.

The server publishing guide explains both target types.

Optional Bridge Routing

Use the bridge when one entry gateway must reach MCP servers through gateways in other shards. Deploy the bridge hub as a target behind the entry gateway. Deploy one or more bridge leaves with each remote shard gateway.

The hub maintains a cache of reachable shard IDs. Clients can call the bridge-provided dsx_bridge_list_shards tool before selecting a shard.

For bridge-provided tool and prompt entries, the hub adds a required shard_id input. The hub removes that value before it publishes the invocation to the selected shard subject. One leaf replica in that shard receives the request and forwards it through the local gateway.

The Agent Gateway deployment in the selected shard repeats JWT verification, tenant derivation, authorization, and rate limiting for the forwarded request. The bridge preserves the caller’s Authorization header across this path.

The bridge supports JSON responses and streamed Server-Sent Events (SSE) for routed invocations. The supported capabilities page identifies methods that the stateless bridge does not support.

Sessions and State

Direct and bridged requests have different state boundaries.

The following table compares session and state behavior for each request path:

State Concern	Direct Routing	Bridge Routing
MCP session	A client can initialize a Streamable HTTP session and reuse its `Mcp-Session-Id`.	The bridge does not extend the caller’s session into a remote shard. The hub and leaves remove `Mcp-Session-Id` before the leaf calls its local gateway.
Upstream association	Selector routing associates the session with one discovered endpoint. The dataplane preserves the association across gateway replicas.	Each remote request is an independent, stateless MCP request.
Protocol handling	The selected target handles methods within the negotiated client session.	The hub handles `initialize` and `ping` locally. It accepts supported JSON-RPC notifications without forwarding session state.
Stateful methods	The selected target can use server-side MCP session state.	Methods that require server-side MCP session state, client state, or resource-path routing are unavailable.

For an active SSE response, one bridge leaf owns temporary stream state without creating an MCP session in the remote shard.

Network and Security Boundary

The chart creates a Kubernetes Gateway listener on plaintext HTTP port 80. Its Service type is ClusterIP by default, and NodePort is the only other supported chart value.

The chart does not create external listener certificates, cert-manager resources, or a LoadBalancer Service. The platform operator owns the external edge, TLS termination, public address, and routing to the gateway Service.

The chart-owned HTTPRoute accepts /mcp traffic and attaches only to its gateway in the same namespace. Operational endpoints and metrics are not exposed through this route.

For HTTPS static targets, Agent Gateway initiates TLS to the upstream. For selector targets and bridge leaf-to-gateway traffic, the documented in-cluster path uses HTTP.

The deployment guide describes the supported edge and cluster prerequisites.