Merge branch 'main' into adb-fixes

Author: artberger

.docs-test.toml

@@ -48,6 +48,12 @@ versions        = ["main", "latest", "2.2.x", "1.0.x"]
 hugoWarnings = [
   "\\.Site\\.Data was deprecated",
   "'items' parameter of the 'tabs' shortcode is deprecated",
+  # FlexSearch bundle couldn't be fetched from the CDN at build time, so the
+  # theme fell back to a runtime CDN <script> tag instead of failing the build.
+  # This is a transient, network-only CI failure we don't control; the fallback
+  # keeps the site working. The warnf is allowlisted so a blip doesn't turn CI
+  # red, but it stays in the build log as a trace.
+  "FlexSearch: could not fetch .* at build time",
 ]
 
 # NOTE: agw-oss previously allowlisted two Hextra main.min.js null-dereferences

.github/workflows/framework-tests.yml

@@ -122,6 +122,11 @@ jobs:
         env:
           DOCS_TEST_CONFIG: ${{ github.workspace }}/.docs-test.toml
         run: |
+          # pipefail required: bare `run:` steps run as `bash -e {0}` without
+          # pipefail here, so `tee`'s exit (0) would mask a failing test suite and
+          # the step would go green. The `if: always()` summary/upload steps below
+          # already assume this step can fail.
+          set -o pipefail
           # One invocation runs both projects against the single build above.
           npx playwright test --project=static --project=content --reporter=list,html 2>&1 | tee playwright-output.txt
 

assets/agw-docs/pages/agentgateway/agent/agentcore.md

@@ -16,7 +16,7 @@ IAM (SigV4) is the default. {{< reuse "agw-docs/snippets/agentgateway.md" >}} si
 {{% tab name="JWT authorization" %}}
 Amazon Cognito is an example tool to use for JWT authorization. The AgentCore runtime validates an OIDC bearer token on each request. To use this mode, attach a backend authentication policy that sends the token in the `Authorization` header. This overrides the default SigV4 signing. Unlike SigV4 credentials, a JWT expires, so you must refresh the token in the backing Kubernetes Secret before it expires.
 
-This mode works only if the AgentCore runtime was deployed with **Inbound Auth** configured to accept JSON Web Tokens (a `customJWTAuthorizer`). The authorizer's `discoveryUrl` and `allowedClients` list must match the token you send: the token's issuer (`iss`) must match the discovery URL's user pool, and the token's client ID must be in `allowedClients`. If the runtime uses the default IAM authorization instead, it rejects bearer tokens with an authorization-method mismatch. You configure Inbound Auth when you deploy the runtime in AWS, not on the gateway. For more information, see the [AgentCore Identity documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-inbound-auth.html).
+This mode works only if the AgentCore runtime was deployed with **Inbound Auth** configured to accept JSON Web Tokens (a `customJWTAuthorizer`). The authorizer's `discoveryUrl` and `allowedClients` list must match the token you send: the token's issuer (`iss`) must match the discovery URL's user pool, and the token's client ID must be in `allowedClients`. If the runtime uses the default IAM authorization instead, it rejects bearer tokens with an authorization-method mismatch. You configure Inbound Auth when you deploy the runtime in AWS, not on the gateway. For more information, see the [AgentCore Identity documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/what-is-bedrock-agentcore.html).
 {{% /tab %}}
 {{< /tabs >}}
 

assets/agw-docs/pages/agentgateway/integrations/llm-clients-k8s/continue.md

@@ -1,4 +1,4 @@
-Configure [Continue](https://www.continue.dev/), the open-source AI code assistant for VS Code, to use agentgateway deployed in Kubernetes.
+Configure [Continue](https://continue.dev/), the open-source AI code assistant for VS Code, to use agentgateway deployed in Kubernetes.
 
 ## Before you begin
 

assets/agw-docs/pages/agentgateway/integrations/llm-clients/continue.md

@@ -1,4 +1,4 @@
-Configure [Continue](https://www.continue.dev/), the open-source AI code assistant for VS Code, to route requests through agentgateway.
+Configure [Continue](https://continue.dev/), the open-source AI code assistant for VS Code, to route requests through agentgateway.
 
 ## Before you begin
 

assets/agw-docs/pages/agentgateway/llm/virtual-keys.md

@@ -58,6 +58,8 @@ Store your virtual keys in a Kubernetes ConfigMap, with one entry per user. Beca
 
 > [!IMPORTANT]
 > ConfigMaps with hashed keys (as opposed to Secrets) are the recommended way to store virtual keys. If you need to use Kubernetes Secrets, refer to the [API key authentication guide]({{< link-hextra path="/security/apikey/" >}}) for an example.
+>
+> Already storing virtual keys in a Secret? Instead of recreating them by hand, use the [`agctl migrate`]({{< link-hextra path="/reference/agctl/agctl-migrate/" >}}) command to convert your existing Secrets into the recommended ConfigMap format.
 
 1. Generate a `sha256:<hex>` hash for each user's API key. The hash is computed over the exact key bytes, so do not include a trailing newline.
 
@@ -95,6 +97,9 @@ Store your virtual keys in a Kubernetes ConfigMap, with one entry per user. Beca
    EOF
    ```
 
+   > [!TIP]
+   > If you already store virtual keys in a Kubernetes Secret, you do not have to build this ConfigMap by hand. Use the [`agctl migrate`]({{< link-hextra path="/reference/agctl/agctl-migrate/" >}}) command to generate an equivalent ConfigMap (with hashed keys) from your existing Secrets, for example `agctl migrate --apply virtualkeys-to-configmap -n {{< reuse "agw-docs/snippets/namespace.md" >}} | kubectl apply -f -`.
+
    {{% reuse "agw-docs/snippets/review-table.md" %}}
 
    | Setting     | Description |
@@ -777,10 +782,8 @@ For more information on cost tracking, see the [cost tracking guide]({{< link-he
 
 Provide different budget tiers for free, standard, and premium users.
 
-1. Add tier metadata to each API key.
-
-   {{< version exclude-if="1.3.x,1.2.x,1.1.x,1.0.x,2.2.x" >}}
-   Store the keys in a ConfigMap, using the `keyHash` of each key. Generate each hash with `printf '%s' '<key>' | sha256sum | awk '{print "sha256:"$1}'`.
+{{< version exclude-if="1.3.x,1.2.x,1.1.x,1.0.x,2.2.x" >}}
+1. Add tier metadata to each API key. Store the keys in a ConfigMap, using the `keyHash` of each key. Generate each hash with `printf '%s' '<key>' | sha256sum | awk '{print "sha256:"$1}'`.
 
    ```yaml
    apiVersion: v1
@@ -808,9 +811,10 @@ Provide different budget tiers for free, standard, and premium users.
          }
        }
    ```
-   {{< /version >}}
+{{< /version >}}
+{{< version include-if="1.3.x,1.2.x,1.1.x,1.0.x,2.2.x" >}}
+1. Add tier metadata to each API key. Store the keys in a Secret, with one entry per user.
 
-   {{< version include-if="1.3.x,1.2.x,1.1.x,1.0.x,2.2.x" >}}
    ```yaml
    apiVersion: v1
    kind: Secret
@@ -836,7 +840,7 @@ Provide different budget tiers for free, standard, and premium users.
          }
        }
    ```
-   {{< /version >}}
+{{< /version >}}
 
 2. Configure rate limiting to use the tier and user_id from API key metadata.
 

assets/agw-docs/pages/agentgateway/mcp/apps.md

@@ -0,0 +1,12 @@
+**MCP Apps** (the `io.modelcontextprotocol/ui` extension) let MCP tools return interactive user-interface (UI) resources that an MCP host can render, rather than plain text. A tool can return a UI resource identified by a `ui://` URI, and the host displays it to the user. Agentgateway supports MCP Apps automatically, including when you federate multiple MCP servers.
+
+## How agentgateway handles MCP Apps
+
+You do not need to configure anything to use MCP Apps through agentgateway. UI resources pass through the gateway like any other MCP resource, with two behaviors worth knowing about:
+
+- **Multiplexing**: When you federate multiple MCP servers into one endpoint, agentgateway rewrites the `ui://` resource URIs so that they still route to the correct upstream target while remaining valid `ui://` URIs that hosts can render. For more information, see the {{< conditional-text include-if="standalone" >}}[Virtual MCP]({{< link-hextra path="/mcp/connect/virtual" >}}){{< /conditional-text >}}{{< conditional-text include-if="kubernetes" >}}[Virtual MCP]({{< link-hextra path="/mcp/virtual" >}}){{< /conditional-text >}} guide.
+- **Authorization**: Any authorization rules that you configure also apply to UI resources. If a rule denies access to a UI resource, agentgateway does not advertise it to the client. For more information, see {{< conditional-text include-if="standalone" >}}[MCP authorization]({{< link-hextra path="/mcp/mcp-authz" >}}){{< /conditional-text >}}{{< conditional-text include-if="kubernetes" >}}[Tool access]({{< link-hextra path="/mcp/tool-access" >}}){{< /conditional-text >}}.
+
+## MCP Apps and tool name prefixing
+
+MCP Apps can call tools from within the rendered UI. By default, agentgateway prefixes tool names with the target name when you federate multiple MCP servers, which can interfere with app-originated tool calls that use the tool's plain name. To expose unprefixed tool names, adjust the tool name prefixing behavior on the MCP backend. For more information, see the {{< conditional-text include-if="standalone" >}}[Virtual MCP]({{< link-hextra path="/mcp/connect/virtual#tool-name-prefixing" >}}){{< /conditional-text >}}{{< conditional-text include-if="kubernetes" >}}[Virtual MCP]({{< link-hextra path="/mcp/virtual" >}}){{< /conditional-text >}} guide.

assets/agw-docs/pages/agentgateway/mcp/multiplex.md

@@ -155,20 +155,34 @@ EOF
    EOF
    ```
 
-   {{< callout type="info" >}}
-   **Failure mode**: By default, agentgateway uses `FailClosed` behavior, which means that if any MCP target fails to initialize or becomes unavailable during a fanout, the entire session fails. To allow the gateway to skip failed targets and continue serving from the healthy ones, set the `failureMode` field to `FailOpen` on the {{< reuse "agw-docs/snippets/backend.md" >}}:
-
-   ```yaml
-   
-   spec:
-     mcp:
-       failureMode: FailOpen
-       targets:
-         ...
-   ```
-
-   With `FailOpen`, if one MCP server is down, the gateway still serves tools from the remaining healthy servers. If all targets fail, the gateway returns an error.
-   {{< /callout >}}
+   > [!NOTE]
+   > **Failure mode**: By default, agentgateway uses `FailClosed` behavior, which means that if any MCP target fails to initialize or becomes unavailable during a fanout, the entire session fails. To allow the gateway to skip failed targets and continue serving from the healthy ones, set the `failureMode` field to `FailOpen` on the {{< reuse "agw-docs/snippets/backend.md" >}}:
+   > 
+   > ```yaml
+   > 
+   > spec:
+   >   mcp:
+   >     failureMode: FailOpen
+   >     targets:
+   >       ...
+   > ```
+   >
+   > With `FailOpen`, if one MCP server is down, the gateway still serves tools from the remaining healthy servers. If all targets fail, the gateway returns an error.
+
+   > [!NOTE]
+   > **Tool name prefixing**: When multiplexing, agentgateway namespaces tool and prompt names with the target name so that identical names from different servers do not collide. Resource URIs always retain target routing information and are unaffected. Control this behavior with the `prefixMode` field on the {{< reuse "agw-docs/snippets/backend.md" >}}:
+   > 
+   > * `Conditional` (default): Prefix names only when the backend has more than one target.
+   > * `Always`: Always prefix names, even with a single target.
+   > * `Never`: Never prefix names. Calls are routed by looking up which target serves the name, so names must be unique across all targets. Use this mode when clients need plain tool names, such as for [MCP Apps]({{< link-hextra path="/mcp/apps" >}}).
+   >
+   > ```yaml
+   > spec:
+   >   mcp:
+   >     prefixMode: Never
+   >     targets:
+   >       ...
+   > ```
 
 ## Step 2: Route with agentgateway {#agentgateway}
 

assets/agw-docs/pages/agentgateway/mcp/spec-compatibility.md

@@ -0,0 +1,37 @@
+Agentgateway supports MCP servers and clients across MCP specification versions and translates between them automatically. In most cases, you do not need to change your existing MCP servers or clients immediately to adopt the newer specification.
+
+## Supported specification versions
+
+Agentgateway supports MCP protocol versions as described in [Version support]({{< link-hextra path="/reference/versions/" >}}). Earlier versions are automatically negotiated as described later and typically work, but are not guaranteed.
+
+### 2026-07-28 support
+
+The `2026-07-28` revision changes how MCP works at its core. MCP becomes stateless and sessionless. Instead of a stateful `initialize` handshake and an `Mcp-Session-Id` for the lifetime of a session, a modern client discovers server capabilities with a `server/discover` request and carries the required context in each request's `_meta`.
+
+The sessionless protocol is the recommended direction for MCP going forward, and agentgateway supports it by default. Older, session-based clients and servers remain supported, so a mix of older and newer clients and servers can coexist behind the same gateway.
+
+## Automatic version negotiation
+
+Agentgateway sits between a downstream client and one or more upstream MCP servers, and negotiates the protocol version for you.
+
+- **Newer client to newer server**: The `server/discover` request is forwarded and answered directly. This is the optimal path, with no fallback requests.
+- **Newer client to older server**: The older server rejects the modern request, and the client falls back to the older `initialize` flow. Agentgateway handles the fallback transparently. Make sure that your client can handle the older flow gracefully.
+- **Older client to newer server**: The client uses the older `initialize` flow, which agentgateway continues to support.
+
+When you federate multiple MCP servers into one endpoint, agentgateway takes the **intersection** of the protocol versions that the targets support, so the client only negotiates a version that every target can serve. For more information, see the {{< conditional-text include-if="standalone" >}}[Virtual MCP]({{< link-hextra path="/mcp/connect/virtual" >}}){{< /conditional-text >}}{{< conditional-text include-if="kubernetes" >}}[Virtual MCP]({{< link-hextra path="/mcp/virtual" >}}){{< /conditional-text >}} guide.
+
+> [!NOTE]
+> Because most environments run a mix of MCP versions for the foreseeable future, this compatibility handling is on by default and requires no configuration. You do not need to upgrade all of your MCP servers to the newer specification at once.
+
+## Response caching
+
+The `2026-07-28` revision adds caching controls to responses such as `server/discover` and `tools/list`. Because agentgateway can apply policies (such as authorization, external authentication, or external processing) that make a response specific to an individual request, it cannot safely tell clients that a proxied response is cacheable. To guarantee correct behavior, agentgateway disables caching on the responses that it proxies.
+
+## What you can still configure
+
+Version negotiation, sessionless protocol support, and [MCP Apps]({{< link-hextra path="/mcp/apps" >}}) all work automatically. 
+
+The MCP behavior that you can tune includes:
+
+- {{< conditional-text include-if="standalone" >}}[Session handling]({{< link-hextra path="/mcp/connect/http#stateless-sessions" >}}) (`statefulMode`) for how agentgateway proxies session-based servers.{{< /conditional-text >}}{{< conditional-text include-if="kubernetes" >}}[Session routing]({{< link-hextra path="/mcp/session" >}}) (`sessionRouting`) for how agentgateway proxies session-based servers.{{< /conditional-text >}}
+- Tool name prefixing when federating multiple MCP servers: {{< conditional-text include-if="standalone" >}}[Virtual MCP]({{< link-hextra path="/mcp/connect/virtual" >}}).{{< /conditional-text >}}{{< conditional-text include-if="kubernetes" >}}[Virtual MCP]({{< link-hextra path="/mcp/virtual" >}}).{{< /conditional-text >}}

assets/agw-docs/pages/landing.md

@@ -4,7 +4,7 @@
 **New to agentgateway?** Get started in minutes with the [Quickstart guide]({{< link-hextra path="/quickstart/" >}})!
 {{< /callout >}}
 
-{{< reuse-image src="img/architecture.svg" caption="Figure: agentgateway works across compute environments to provide connectivity to various agentic tools, including MCP servers, agents, and OpenAPI endpoints." >}}
+{{< reuse-image src="img/architecture.svg" srcDark="img/architecture-dark.svg" caption="Figure: agentgateway works across compute environments to provide connectivity to various agentic tools, including MCP servers, agents, and OpenAPI endpoints." >}}
 
 ## Why agentgateway?