From d9ca997cc023371ea55c66625675118388f541dc Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Mon, 26 Oct 2026 12:10:25 +0000 Subject: [PATCH 1/3] [Automated] Draft docs (agentgateway): mcp: rebind re-used session to current settings Signed-off-by: GitHub Action --- content/docs/kubernetes/main/release-notes/release-notes.md | 1 + content/docs/standalone/main/integrations/mcp/servers/http.md | 4 ++-- content/docs/standalone/main/release-notes/release-notes.md | 1 + 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/content/docs/kubernetes/main/release-notes/release-notes.md b/content/docs/kubernetes/main/release-notes/release-notes.md index 6d728e710..c51d99c3a 100644 --- a/content/docs/kubernetes/main/release-notes/release-notes.md +++ b/content/docs/kubernetes/main/release-notes/release-notes.md @@ -91,6 +91,7 @@ Review the release notes for agentgateway on Kubernetes. **MCP** - Backend authorization rules for MCP requests evaluate transformed tool names after route-level body transformations run. +- Stateful MCP requests that reuse a session ID on another route to the same backend now use that route's policy settings. - The controller creates the session key Secret of each Gateway only when the Secret is missing, and no longer overwrites the key on reconcile, which could invalidate stateful MCP sessions. If the Secret cannot be created, the Gateway reports `Programmed: False` with the reason `DeploymentFailed`. - 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 streamable HTTP `POST` requests can list `application/json` and `text/event-stream` in separate `Accept` header lines instead of one comma-separated value. diff --git a/content/docs/standalone/main/integrations/mcp/servers/http.md b/content/docs/standalone/main/integrations/mcp/servers/http.md index 11ddd1cc6..5448d8b47 100644 --- a/content/docs/standalone/main/integrations/mcp/servers/http.md +++ b/content/docs/standalone/main/integrations/mcp/servers/http.md @@ -14,7 +14,7 @@ Connect to an MCP server via streamable HTTP. ## About streamable HTTP -Agentgateway automatically manages stateful MCP sessions when using HTTP-based transports. The session state (including backend pinning) is encoded in the session ID and persisted across requests, ensuring that subsequent tool calls in the same session are routed to the same backend server. +Agentgateway automatically manages stateful MCP sessions when using HTTP-based transports. The session state (including backend pinning) is encoded in the session ID and persisted across requests, ensuring that subsequent tool calls in the same session are routed to the same backend server. If a client reuses a session ID on a different route to the same backend, the request uses the MCP policy settings from the new route. ```mermaid sequenceDiagram @@ -38,7 +38,7 @@ sequenceDiagram 1. **Session initialization**: When a client sends an `initialize` request, agentgateway creates a session and returns a session ID 2. **Backend pinning**: The session is pinned to a specific backend server (important when using multiple targets) 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 +4. **Session resumption**: Subsequent requests with the same session ID are automatically routed to the same backend. If the route changes, the MCP policy settings from the new route still apply. 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. diff --git a/content/docs/standalone/main/release-notes/release-notes.md b/content/docs/standalone/main/release-notes/release-notes.md index 4924aaaa1..0aaf0362a 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. +- Stateful MCP requests that reuse a session ID on another route to the same backend now use that route's policy settings. - 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 4a2c7f537993ff280bb60ec76de4131a6136404e Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 26 Oct 2026 10:22:47 -0400 Subject: [PATCH 2/3] move release notes to #1351 Signed-off-by: Art Berger --- content/docs/kubernetes/main/release-notes/release-notes.md | 1 - content/docs/standalone/main/release-notes/release-notes.md | 1 - 2 files changed, 2 deletions(-) diff --git a/content/docs/kubernetes/main/release-notes/release-notes.md b/content/docs/kubernetes/main/release-notes/release-notes.md index c51d99c3a..6d728e710 100644 --- a/content/docs/kubernetes/main/release-notes/release-notes.md +++ b/content/docs/kubernetes/main/release-notes/release-notes.md @@ -91,7 +91,6 @@ Review the release notes for agentgateway on Kubernetes. **MCP** - Backend authorization rules for MCP requests evaluate transformed tool names after route-level body transformations run. -- Stateful MCP requests that reuse a session ID on another route to the same backend now use that route's policy settings. - The controller creates the session key Secret of each Gateway only when the Secret is missing, and no longer overwrites the key on reconcile, which could invalidate stateful MCP sessions. If the Secret cannot be created, the Gateway reports `Programmed: False` with the reason `DeploymentFailed`. - 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 streamable HTTP `POST` requests can list `application/json` and `text/event-stream` in separate `Accept` header lines instead of one comma-separated value. diff --git a/content/docs/standalone/main/release-notes/release-notes.md b/content/docs/standalone/main/release-notes/release-notes.md index 0aaf0362a..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. -- Stateful MCP requests that reuse a session ID on another route to the same backend now use that route's policy settings. - 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 d1cbef5abc0958d5cab06dbadd48fc20bf941116 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 26 Oct 2026 12:33:37 -0400 Subject: [PATCH 3/3] docs: K8s MCP session reuse follows the current route's policies A reused session now rebinds MCP authorization and MCP guardrails to the route it arrives on (#4057, Relay::with_inputs). Add the K8s sentence to the shared session asset inside the existing 1.7 gate. Signed-off-by: Art Berger --- assets/agw-docs/pages/agentgateway/mcp/session.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/assets/agw-docs/pages/agentgateway/mcp/session.md b/assets/agw-docs/pages/agentgateway/mcp/session.md index 8d31e8fc5..7a0477944 100644 --- a/assets/agw-docs/pages/agentgateway/mcp/session.md +++ b/assets/agw-docs/pages/agentgateway/mcp/session.md @@ -12,6 +12,8 @@ To ensure that subsequent requests are routed to the same agentgateway proxy ins 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. 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`. + +A client can reuse a session ID on a different route to the same MCP backend. The request then uses the MCP authorization and MCP guardrail policies of the route that it arrives on, not the route that created the session. {{< /version >}}