diff --git a/assets/agw-docs/pages/agentgateway/mcp/session.md b/assets/agw-docs/pages/agentgateway/mcp/session.md index 6bce18900..d67124574 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. 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`. + +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 >}} diff --git a/content/docs/standalone/main/integrations/mcp/servers/http.md b/content/docs/standalone/main/integrations/mcp/servers/http.md index a5a5f4fd9..72c6f5c1e 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. 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.