From 672d161bad8ec651cd0f344eb8883d37ce2e686a Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 26 Oct 2026 12:10:27 +0000 Subject: [PATCH 1/2] [Automated] Draft docs (agentgateway): mcp: assert that resumed sessions are on the same backend Signed-off-by: GitHub Action --- assets/agw-docs/pages/agentgateway/mcp/session.md | 2 +- content/docs/standalone/main/integrations/mcp/servers/http.md | 2 +- content/docs/standalone/main/release-notes/release-notes.md | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/assets/agw-docs/pages/agentgateway/mcp/session.md b/assets/agw-docs/pages/agentgateway/mcp/session.md index 8d31e8fc5..6bce18900 100644 --- a/assets/agw-docs/pages/agentgateway/mcp/session.md +++ b/assets/agw-docs/pages/agentgateway/mcp/session.md @@ -9,7 +9,7 @@ If you run multiple agentgateway proxy instances without stateful sessions, the To ensure that subsequent requests are routed to the same agentgateway proxy instance, the proxy exposes streamable HTTP endpoints as stateful endpoints by default and sends back the session ID in the `Mcp-Session-Id` header. You can disable this setting and instead use stateless MCP servers by using the `sessionRouting: Stateless` setting in the {{< reuse "agw-docs/snippets/backend.md" >}} resource. {{< version exclude-if="1.0.x,1.1.x,1.2.x,1.3.x,1.4.x,1.5.x,1.6.x,2.2.x" >}} -If a client sends a session ID that the proxy cannot decode, the proxy returns `HTTP 404`, and the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) requires the client to start a new session. A session ID cannot be decoded after the session key changes. +If a client sends a session ID that the proxy cannot decode, the proxy returns `HTTP 404`, and the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) requires the client to start a new session. A session ID cannot be decoded after the session key changes. If an encrypted session ID belongs to a different MCP backend from the current request's backend, the proxy also returns `HTTP 404`. The client starts a new session on the current backend. The proxy encrypts each session ID with a session key. The controller stores the key in a Secret named `-session-key` in the namespace of the Gateway. The controller creates the Secret only if it does not exist, and never changes the key in it. The Gateway owns the Secret, so deleting the Gateway deletes the key. To use your own key, set the `SESSION_KEY` environment variable in the {{< reuse "agw-docs/snippets/gatewayparameters.md" >}} resource. The controller then does not manage a Secret. If the controller cannot create the Secret, or another resource controls it, the Gateway reports `Programmed: False` with the reason `DeploymentFailed`. {{< /version >}} diff --git a/content/docs/standalone/main/integrations/mcp/servers/http.md b/content/docs/standalone/main/integrations/mcp/servers/http.md index 11ddd1cc6..a5a5f4fd9 100644 --- a/content/docs/standalone/main/integrations/mcp/servers/http.md +++ b/content/docs/standalone/main/integrations/mcp/servers/http.md @@ -40,7 +40,7 @@ sequenceDiagram 3. **State encoding**: The session state is encoded into the session ID and encrypted with AES-256-GCM. For the key that agentgateway uses, see [Session key](#session-key). 4. **Session resumption**: Subsequent requests with the same session ID are automatically routed to the same backend -If a client sends a session ID that the proxy cannot decode, the proxy returns `HTTP 404`, and the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) requires the client to start a new session. A session ID cannot be decoded after the session key changes. For example, a session ID fails to decode after you restart the proxy with a different key, or when proxy instances behind one load balancer use different keys. +If a client sends a session ID that the proxy cannot decode, the proxy returns `HTTP 404`, and the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management) requires the client to start a new session. A session ID cannot be decoded after the session key changes. For example, a session ID fails to decode after you restart the proxy with a different key, or when proxy instances behind one load balancer use different keys. If an encrypted session ID belongs to a different MCP backend from the current request's backend, the proxy also returns `HTTP 404`. The client starts a new session on the current backend. When a client closes a stateful session with `DELETE /mcp`, the proxy decodes the session ID before it sends close requests to upstream targets. Any replica with the same session key can close the upstream sessions. Deletion is best effort. Upstream close failures still return `HTTP 202`, and those upstream sessions stay open until the target's idle timeout. If the proxy cannot rebuild a target connection from the session ID, the client receives the rebuild error. diff --git a/content/docs/standalone/main/release-notes/release-notes.md b/content/docs/standalone/main/release-notes/release-notes.md index 4924aaaa1..62e6c034e 100644 --- a/content/docs/standalone/main/release-notes/release-notes.md +++ b/content/docs/standalone/main/release-notes/release-notes.md @@ -115,6 +115,7 @@ For more information, see [Session key]({{< link-hextra path="/integrations/mcp/ **MCP** - Backend authorization rules for MCP requests evaluate transformed tool names after route-level body transformations run. +- Encrypted MCP session IDs that belong to a different backend return `404`, so clients start a new session on the current backend. - Stateful MCP requests with a session ID that the proxy cannot decode, such as after the session key changes, now return `404` instead of `400`, so clients start a new session. - MCP authentication derives JWKS URLs without a double slash when an issuer value ends with `/`. - MCP streamable HTTP `POST` requests can list `application/json` and `text/event-stream` in separate `Accept` header lines instead of one comma-separated value. From 52ebc60dc7204681dd5f1f6212899cde91205674 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 26 Oct 2026 10:22:50 -0400 Subject: [PATCH 2/2] move release notes to #1351 Signed-off-by: Art Berger --- content/docs/standalone/main/release-notes/release-notes.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/docs/standalone/main/release-notes/release-notes.md b/content/docs/standalone/main/release-notes/release-notes.md index 62e6c034e..4924aaaa1 100644 --- a/content/docs/standalone/main/release-notes/release-notes.md +++ b/content/docs/standalone/main/release-notes/release-notes.md @@ -115,7 +115,6 @@ For more information, see [Session key]({{< link-hextra path="/integrations/mcp/ **MCP** - Backend authorization rules for MCP requests evaluate transformed tool names after route-level body transformations run. -- Encrypted MCP session IDs that belong to a different backend return `404`, so clients start a new session on the current backend. - Stateful MCP requests with a session ID that the proxy cannot decode, such as after the session key changes, now return `404` instead of `400`, so clients start a new session. - MCP authentication derives JWKS URLs without a double slash when an issuer value ends with `/`. - MCP streamable HTTP `POST` requests can list `application/json` and `text/event-stream` in separate `Accept` header lines instead of one comma-separated value.