modelcontextprotocol · halter73 · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026 · Mar 26, 2026
diff --git a/docs/concepts/cancellation/cancellation.md b/docs/concepts/cancellation/cancellation.md
@@ -12,6 +12,9 @@ MCP supports [cancellation] of in-flight requests. Either side can cancel a prev
 [cancellation]: https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/cancellation
 [task cancellation]: https://learn.microsoft.com/dotnet/standard/parallel-programming/task-cancellation
 
+> [!NOTE]
+> The source and lifetime of the `CancellationToken` provided to server handlers depends on the transport and session mode. In [stateless mode](xref:sessions#stateless-mode-recommended), the token is tied to the HTTP request — if the client disconnects, the handler is cancelled. In [stateful mode](xref:sessions#stateful-mode-sessions), the token is tied to the session lifetime. See [Cancellation and disposal](xref:sessions#cancellation-and-disposal) for details.
+
 ### How cancellation maps to MCP notifications
 
 When a `CancellationToken` passed to a client method (such as <xref:ModelContextProtocol.Client.McpClient.CallToolAsync*>) is cancelled, a `notifications/cancelled` notification is sent to the server with the request ID. On the server side, the `CancellationToken` provided to the tool method is then triggered, allowing the handler to stop work gracefully. This same mechanism works in reverse for server-to-client requests.

diff --git a/docs/concepts/completions/completions.md b/docs/concepts/completions/completions.md
@@ -26,7 +26,7 @@ Register a completion handler when building the server. The handler receives a r
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithPrompts<MyPrompts>()
     .WithResources<MyResources>()
     .WithCompleteHandler(async (ctx, ct) =>

diff --git a/docs/concepts/elicitation/elicitation.md b/docs/concepts/elicitation/elicitation.md
@@ -172,7 +172,7 @@ Here's an example implementation of how a console application might handle elici
 
 ### URL Elicitation Required Error
 
-When a tool cannot proceed without first completing a URL-mode elicitation (for example, when third-party OAuth authorization is needed), and calling `ElicitAsync` is not practical (for example in <xref: ModelContextProtocol.AspNetCore.HttpServerTransportOptions.Stateless> is enabled disabling server-to-client requests), the server may throw a <xref:ModelContextProtocol.UrlElicitationRequiredException>. This is a specialized error (JSON-RPC error code `-32042`) that signals to the client that one or more URL-mode elicitations must be completed before the original request can be retried.
+When a tool cannot proceed without first completing a URL-mode elicitation (for example, when third-party OAuth authorization is needed), and calling `ElicitAsync` is not practical (for example in [stateless](xref:sessions) mode where server-to-client requests are disabled), the server may throw a <xref:ModelContextProtocol.UrlElicitationRequiredException>. This is a specialized error (JSON-RPC error code `-32042`) that signals to the client that one or more URL-mode elicitations must be completed before the original request can be retried.
 
 #### Throwing UrlElicitationRequiredException on the Server
 

diff --git a/docs/concepts/elicitation/samples/server/Program.cs b/docs/concepts/elicitation/samples/server/Program.cs
@@ -6,8 +6,11 @@
 
 builder.Services.AddMcpServer()
     .WithHttpTransport(options =>
-        options.IdleTimeout = Timeout.InfiniteTimeSpan // Never timeout
-    )
+    {
+        // Elicitation requires stateful mode because it sends server-to-client requests.
+        // Set Stateless = false explicitly for forward compatibility in case the default changes.
+        options.Stateless = false;
+    })
     .WithTools<InteractiveTools>();
 
 builder.Logging.AddConsole(options =>

diff --git a/docs/concepts/filters.md b/docs/concepts/filters.md
@@ -401,7 +401,7 @@ To enable authorization support, call `AddAuthorizationFilters()` when configuri
 
 ```csharp
 services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .AddAuthorizationFilters() // Enable authorization filter support
     .WithTools<WeatherTools>();
 ```
@@ -501,7 +501,7 @@ This allows you to implement logging, metrics, or other cross-cutting concerns t
 
 ```csharp
 services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithRequestFilters(requestFilters =>
     {
         requestFilters.AddListToolsFilter(next => async (context, cancellationToken) =>
@@ -544,7 +544,10 @@ builder.Services.AddAuthentication("Bearer")
 builder.Services.AddAuthorization();
 
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(options =>
+    {
+        options.Stateless = true;
+    })
     .AddAuthorizationFilters() // Required for authorization support
     .WithTools<WeatherTools>()
     .WithRequestFilters(requestFilters =>

diff --git a/docs/concepts/getting-started.md b/docs/concepts/getting-started.md
@@ -79,7 +79,13 @@ using System.ComponentModel;
 
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(options =>
+    {
+        // Stateless mode is recommended for servers that don't need
+        // server-to-client requests like sampling or elicitation.
+        // See the Sessions documentation for details.
+        options.Stateless = true;
+    })
     .WithToolsFromAssembly();
 var app = builder.Build();
 

diff --git a/docs/concepts/httpcontext/httpcontext.md b/docs/concepts/httpcontext/httpcontext.md
@@ -29,3 +29,16 @@ The following code snippet shows the `ContextTools` class accepting an [IHttpCon
 and the `GetHttpHeaders` method accessing the current [HttpContext] to retrieve the HTTP headers from the current request.
 
 [!code-csharp[](samples/Tools/ContextTools.cs?name=snippet_AccessHttpContext)]
+
+### SSE transport and stale HttpContext
+
+When using the legacy SSE transport, be aware that the `HttpContext` returned by `IHttpContextAccessor` references the long-lived SSE connection request — not the individual `POST` request that triggered the tool call. This means:
+
+- The `HttpContext.User` may contain stale claims if the client's token was refreshed after the SSE connection was established.
+- Request headers, query strings, and other per-request metadata will reflect the initial SSE connection, not the current operation.
+
+The Streamable HTTP transport does not have this issue because each tool call is its own HTTP request, so `IHttpContextAccessor.HttpContext` always reflects the current request. In [stateless](xref:sessions) mode, this is guaranteed since every request creates a fresh server context.
+
+<!-- mlc-disable-next-line -->
+> [!NOTE]
+> The server validates that the user identity has not changed between the session-initiating request and subsequent requests (using the `sub`, `NameIdentifier`, or `UPN` claim). If the user identity changes, the request is rejected with `403 Forbidden`. However, other claims (roles, permissions, custom claims) are not re-validated and may become stale over the lifetime of a session.
diff --git a/docs/concepts/httpcontext/samples/Program.cs b/docs/concepts/httpcontext/samples/Program.cs
@@ -5,7 +5,10 @@
 // Add services to the container.
 
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(options =>
+    {
+        options.Stateless = true;
+    })
     .WithTools<ContextTools>();
 
 // <snippet_AddHttpContextAccessor>

diff --git a/docs/concepts/index.md b/docs/concepts/index.md
@@ -36,5 +36,6 @@ Install the SDK and build your first MCP client and server.
 | [Prompts](prompts/prompts.md) | Learn how to implement and consume reusable prompt templates with rich content types. |
 | [Completions](completions/completions.md) | Learn how to implement argument auto-completion for prompts and resource templates. |
 | [Logging](logging/logging.md) | Learn how to implement logging in MCP servers and how clients can consume log messages. |
+| [Sessions](sessions/sessions.md) | Learn when to use stateless vs. stateful mode for HTTP servers and how to configure sessions. |
 | [HTTP Context](httpcontext/httpcontext.md) | Learn how to access the underlying `HttpContext` for a request. |
 | [MCP Server Handler Filters](filters.md) | Learn how to add filters to the handler pipeline. Filters let you wrap the original handler with additional functionality. |
diff --git a/docs/concepts/logging/logging.md b/docs/concepts/logging/logging.md
@@ -46,7 +46,7 @@ MCP servers that implement the Logging utility must declare this in the capabili
 [Initialization]: https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#initialization
 
 Servers built with the C# SDK always declare the logging capability. Doing so does not obligate the server
-to send log messages&mdash;only allows it. Note that stateless MCP servers might not be capable of sending log
+to send log messages&mdash;only allows it. Note that [stateless](xref:sessions) MCP servers might not be capable of sending log
 messages as there might not be an open connection to the client on which the log messages could be sent.
 
 The C# SDK provides an extension method <xref:Microsoft.Extensions.DependencyInjection.McpServerBuilderExtensions.WithSetLoggingLevelHandler*> on <xref:Microsoft.Extensions.DependencyInjection.IMcpServerBuilder> to allow the

diff --git a/docs/concepts/logging/samples/server/Program.cs b/docs/concepts/logging/samples/server/Program.cs
@@ -6,8 +6,11 @@
 
 builder.Services.AddMcpServer()
     .WithHttpTransport(options =>
-        options.IdleTimeout = Timeout.InfiniteTimeSpan // Never timeout
-    )
+    {
+        // Log streaming requires stateful mode because the server pushes log notifications
+        // to clients. Set Stateless = false explicitly for forward compatibility.
+        options.Stateless = false;
+    })
     .WithTools<LoggingTools>();
     // .WithSetLoggingLevelHandler(async (ctx, ct) => new EmptyResult());
 

diff --git a/docs/concepts/pagination/pagination.md b/docs/concepts/pagination/pagination.md
@@ -70,7 +70,7 @@ When implementing custom list handlers on the server, pagination is supported by
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithListResourcesHandler(async (ctx, ct) =>
     {
         const int pageSize = 10;

diff --git a/docs/concepts/progress/progress.md b/docs/concepts/progress/progress.md
@@ -15,6 +15,9 @@ Typically progress tracking is supported by server tools that perform operations
 However, progress tracking is defined in the MCP specification as a general feature that can be implemented for any request that's handled by either a server or a client.
 This project illustrates the common case of a server tool that performs a long-running operation and sends progress updates to the client.
 
+> [!NOTE]
+> Progress notifications are sent inline as part of the response to a request — they are not unsolicited. Progress tracking works in both [stateless and stateful](xref:sessions) modes as well as stdio.
+
 ### Server Implementation
 
 When processing a request, the server can use the <xref:ModelContextProtocol.McpSession.SendNotificationAsync*> extension method of <xref:ModelContextProtocol.Server.McpServer> to send progress updates,

diff --git a/docs/concepts/progress/samples/server/Program.cs b/docs/concepts/progress/samples/server/Program.cs
@@ -5,7 +5,10 @@
 // Add services to the container.
 
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(options =>
+    {
+        options.Stateless = true;
+    })
     .WithTools<LongRunningTools>();
 
 builder.Logging.AddConsole(options =>

diff --git a/docs/concepts/prompts/prompts.md b/docs/concepts/prompts/prompts.md
@@ -63,7 +63,7 @@ Register prompt types when building the server:
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithPrompts<MyPrompts>()
     .WithPrompts<CodePrompts>();
 ```
@@ -197,7 +197,7 @@ foreach (var message in result.Messages)
 
 ### Prompt list change notifications
 
-Servers can dynamically add, remove, or modify prompts at runtime and notify connected clients.
+Servers can dynamically add, remove, or modify prompts at runtime and notify connected clients. These are unsolicited notifications, so they require [stateful mode or stdio](xref:sessions) — [stateless](xref:sessions#stateless-mode-recommended) servers cannot send unsolicited notifications.
 
 #### Sending notifications from the server
 

diff --git a/docs/concepts/resources/resources.md b/docs/concepts/resources/resources.md
@@ -74,7 +74,7 @@ Register resource types when building the server:
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    .WithHttpTransport(o => o.Stateless = true)
     .WithResources<MyResources>()
     .WithResources<DocumentResources>();
 ```
@@ -208,7 +208,9 @@ Register subscription handlers when building the server:
 
 ```csharp
 builder.Services.AddMcpServer()
-    .WithHttpTransport()
+    // Subscriptions require stateful mode because the server pushes change notifications
+    // to clients. Set Stateless = false explicitly for forward compatibility.
+    .WithHttpTransport(o => o.Stateless = false)
     .WithResources<MyResources>()
     .WithSubscribeToResourcesHandler(async (ctx, ct) =>
     {

diff --git a/docs/concepts/roots/roots.md b/docs/concepts/roots/roots.md
@@ -57,7 +57,7 @@ await using var client = await McpClient.CreateAsync(transport, options);
 
 ### Requesting roots from the server
 
-Servers can request the client's root list using <xref:ModelContextProtocol.Server.McpServer.RequestRootsAsync*>:
+Servers can request the client's root list using <xref:ModelContextProtocol.Server.McpServer.RequestRootsAsync*>. This is a server-to-client request, so it requires [stateful mode or stdio](xref:sessions) — it is not available in [stateless mode](xref:sessions#stateless-mode-recommended).
 
 ```csharp
 [McpServerTool, Description("Lists the user's project roots")]

diff --git a/docs/concepts/sampling/sampling.md b/docs/concepts/sampling/sampling.md
@@ -11,6 +11,9 @@ MCP [sampling] allows servers to request LLM completions from the client. This e
 
 [sampling]: https://modelcontextprotocol.io/specification/2025-11-25/client/sampling
 
+> [!NOTE]
+> Sampling is a **server-to-client request** — the server sends a request back to the client over an open connection. This requires [stateful mode or stdio](xref:sessions). Sampling is not available in [stateless mode](xref:sessions#stateless-mode-recommended) because stateless servers cannot send requests to clients.
+
 ### How sampling works
 
 1. The server calls <xref:ModelContextProtocol.Server.McpServer.SampleAsync*> (or uses the <xref:ModelContextProtocol.Server.McpServer.AsSamplingChatClient*> adapter) during tool execution.