Add stateless doc, prefer stateless mode and disable legacy SSE by default

[halter73]

Recommend stateless mode as the default for HTTP-based MCP servers across documentation, samples, and error messages.

Docs:

• Add comprehensive sessions conceptual doc covering stateless (recommended), stateful, and stdio session behaviors
• Update getting-started, transports, filters, and other conceptual docs to use stateless mode in examples
• Add Sampling to docs table of contents
• Clarify ConfigureSessionOptions runs per-request in stateless mode

Samples:

• Convert ProtectedMcpServer to stateless mode
• Add comments to AspNetCoreMcpServer and EverythingServer explaining why they require sessions

Error messages:

• Improve missing Mcp-Session-Id errors to suggest stateless mode and link to session documentation

Tests:

• Add tests for progress notifications and ConfigureSessionOptions in stateless mode
• Verify error messages reference stateless mode guidance

[Copilot]

Pull request overview

This PR updates the SDK’s guidance around HTTP server sessions by adding a dedicated “Sessions” conceptual doc, shifting most docs/samples to recommend stateless mode by default, and improving HTTP error messages to point users at stateless mode when Mcp-Session-Id is missing.

Changes:

• Added a comprehensive Sessions conceptual doc (stateless vs. stateful vs. stdio) and updated docs TOC.
• Updated multiple docs and samples to prefer HttpServerTransportOptions.Stateless = true by default, with notes on when stateful sessions are required.
• Improved Streamable HTTP missing-session error messages and added/updated tests to validate the guidance appears.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/ModelContextProtocol.AspNetCore.Tests/StreamableHttpServerConformanceTests.cs	Adds assertions that missing-session 400s include stateless guidance.
tests/ModelContextProtocol.AspNetCore.Tests/StatelessServerTests.cs	Adds stateless-mode tests for progress notifications and ConfigureSessionOptions behavior.
src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs	Enhances 400 error messages to recommend stateless mode and link to sessions docs.
src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs	Clarifies ConfigureSessionOptions invocation semantics in stateless mode.
samples/ProtectedMcpServer/Program.cs	Switches sample to stateless mode with explanatory comments.
samples/EverythingServer/Program.cs	Adds explanation why the sample must remain stateful.
samples/AspNetCoreMcpServer/Program.cs	Adds explanation why the sample must remain stateful.
docs/concepts/transports/transports.md	Updates examples to stateless mode and adds stateless guidance in narrative/table.
docs/concepts/toc.yml	Adds Sessions and Sampling entries to conceptual TOC.
docs/concepts/sessions/sessions.md	New comprehensive sessions documentation page.
docs/concepts/progress/samples/server/Program.cs	Updates example to stateless mode.
docs/concepts/logging/logging.md	Links stateless behavior to sessions doc.
docs/concepts/index.md	Adds Sessions to concepts index table.
docs/concepts/httpcontext/samples/Program.cs	Updates example to stateless mode.
docs/concepts/getting-started.md	Updates getting-started HTTP server snippet to stateless mode.
docs/concepts/filters.md	Updates auth/filters example to stateless mode.
docs/concepts/elicitation/elicitation.md	Links stateless limitation note to sessions doc.

[stephentoub]

Any way we could add an analyzer to help mitigate the breaks? eg detect that Stateless = false isn't being used anywhere and then warn on any use of the problematic methods?

[halter73]

Regarding the analyzer, I just opened #1471 to look into that. I currently have that as a PR based on this one (halter73/stateless-docs), because I don't want the complexities around that to hold up the doc and SSE default change. I think the analyzer can be done as a quick follow in a pretty nonbreaking way in a follow up patch. At least, certainly compared to just going ahead and making the break immediately!

[halter73]

I added an additional section on forward and backward compatibility:

Forward and backward compatibility

The Stateless property is the single most important setting for forward-proofing your MCP server. The current C# SDK default is Stateless = false (sessions enabled), but we expect this default to change once mechanisms like MRTR bring server-to-client interactions (sampling, elicitation, roots) to stateless mode. We recommend every server set Stateless explicitly rather than relying on the default:

• Stateless = true — the best forward-compatible choice. Your server opts out of sessions entirely. No matter how the SDK default changes in the future, your behavior stays the same. If you don't need unsolicited notifications, server-to-client requests, or session-scoped state, this is the setting to use today.

• Stateless = false — the right choice when your server depends on sessions for features like sampling, elicitation, roots, unsolicited notifications, or per-client isolation. Setting this explicitly protects your server from a future default change. The MCP specification requires that clients use sessions when a server's initialize response includes an Mcp-Session-Id header, so compliant clients will always honor your server's session. Once MRTR or a similar mechanism is available, you may be able to migrate server-to-client interactions to stateless mode and drop sessions entirely — but until then, explicit Stateless = false is the safe choice. See Stateless alternatives for server-to-client interactions for more on MRTR.

[!TIP]
If you're not sure which to pick, start with Stateless = true. You can switch to Stateless = false later if you discover you need server-to-client requests or unsolicited notifications. Either way, setting the property explicitly means your server's behavior won't silently change when the SDK default is updated.

[halter73]

I also added this comment about how to deal with the legacy SSE breaking change:

Migrating from legacy SSE

If your clients connect to a /sse endpoint (e.g., https://my-server.example.com/sse), they are using the legacy SSE transport — regardless of any Stateless or session settings on the server. The /sse and /message endpoints are now disabled by default (xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.EnableLegacySse is false and marked [Obsolete] with diagnostic MCP9003). Upgrading the server SDK without updating clients will break SSE connections.

Client-side migration. Change the client Endpoint from the /sse path to the root MCP endpoint — the same URL your server passes to MapMcp(). For example:

// Before (legacy SSE):
Endpoint = new Uri("https://my-server.example.com/sse")

// After (Streamable HTTP):
Endpoint = new Uri("https://my-server.example.com/")

With the default xref:ModelContextProtocol.Client.HttpTransportMode.AutoDetect transport mode, the client automatically tries Streamable HTTP first. You can also set TransportMode = HttpTransportMode.StreamableHttp explicitly if you know the server supports it.

Server-side migration. If you previously relied on /sse being mapped automatically, you now need EnableLegacySse = true (suppressing the MCP9003 warning) to keep serving those endpoints. The recommended path is to migrate all clients to Streamable HTTP and then remove EnableLegacySse.

Transition period. If some clients still need SSE while others have already migrated to Streamable HTTP, set EnableLegacySse = true with Stateless = false. Both transports are served simultaneously by MapMcp() — Streamable HTTP on the root endpoint and SSE on /sse and /message. Once all clients have migrated, remove EnableLegacySse and optionally switch to Stateless = true.

[mikekistler]

Looks good. 👍

There may still be some minor points of clarification but we can handle those in follow-up PRs.

[jeffhandley]

I haven't reviewed all of the docs changes/additions, but I sign off on the behavioral changes being made here along with the new (obsolete-out-of-the-gate) property.

This makes me realize we should be more reluctant to pick any server behavioral defaults going forward.

I was very tempted to recommend we stage this even more granularly by:

1. Introduce the EnableLegacySse property in 1 release
2. Change the behavior in the next release

But that'd be overkill, and we're giving a call-to-action anyway.

I also asked @halter73 about marking WithHttpTransport as [Obsolete] and introducing a (worse) API that forces the specification of stateful vs. stateless. We decided against it, at least for now. Presumably that would've needed to be WithStatelessHttpTransport and WithStatefulHttpTransport or something else awkward.

[jeffhandley]

This PR has been labeled breaking-change during the release audit. Legacy SSE endpoints (/sse and /message) are no longer mapped by default — this is a behavioral breaking change for servers whose clients connect via SSE. Migration: set HttpServerTransportOptions.EnableLegacySse = true.