Enum HttpServerSessionMode

Namespace

ModelContextProtocol.AspNetCore

Assembly

ModelContextProtocol.AspNetCore.dll

Specifies how the Streamable HTTP transport tracks state between requests.

public enum HttpServerSessionMode

Fields

Stateful = 1

The server tracks a long-lived session for every client, which requires session affinity.

Requests using the 2026-07-28 or later protocol revision are refused with a -32022 UnsupportedProtocolVersion error so that a dual-path client downgrades to the initialize handshake and obtains the session the server was configured to provide. Use StatefulForInitializeClients to serve those clients natively instead of forcing a downgrade.

StatefulForInitializeClients = 2

The server tracks a long-lived session for clients that use the initialize handshake and serves clients using the 2026-07-28 or later protocol revision statelessly on the same endpoint.

This hybrid mode allows an application to adopt the latest protocol revision progressively rather than waiting for every client to migrate. Clients using the 2025-11-25 or earlier revisions get a full stateful session with an Mcp-Session-Id and continue to use the GET and DELETE endpoints, while clients using the 2026-07-28 or later revisions are served per request with no session ID minted or echoed, and receive 405 Method Not Allowed for GET and DELETE, exactly as in Stateless mode.

Because a 2026-07-28 request has no session, the session-only features listed on Stateless remain unavailable to those clients even though other clients on the same endpoint have sessions. ConfigureSessionOptions is invoked once per session for initialize-handshake clients and once per request for 2026-07-28 and later clients.

Stateless = 0

The server never tracks state between requests, allowing for load balancing without session affinity.

SessionId is null, the Mcp-Session-Id header is unused, RunSessionHandler and ConfigureSessionOptions are invoked once per request, and the GET, DELETE, and /sse endpoints are unavailable. Unsolicited server-to-client messages and all server-to-client requests are unsupported because any response might arrive at another ASP.NET Core application process. Client sampling, elicitation, and roots capabilities are disabled because the server cannot make requests; use Multi Round-Trip Requests (MRTR) instead.

Remarks

Starting with the 2026-07-28 protocol revision, Streamable HTTP no longer supports sessions (SEP-2567 removed Mcp-Session-Id, and SEP-2575 removed the initialize handshake), so requests using that revision or later can only ever be served statelessly. This enumeration allows specification for how the server reconciles that requirement with clients that still rely on the initialize handshake.