Improve session docs, client behavior, and observability guidance

halter73 · Copilot · halter73 · commit b7e68dc29025 · 2026-03-27T01:40:00.000-07:00
Add client-side session behavior documentation covering session lifecycle,
expiry detection, reconnection patterns, and transport options. Move Sessions
to Base Protocol in toc.yml. Add session cross-references to sampling, roots,
tools, prompts, progress, and cancellation docs.

Restructure sessions.md: merge redundant stateless sections, promote Tasks,
Request backpressure, and Observability to top-level sections, move client
section before Advanced features, and fold stream reconnection into lifecycle.

Add reconnection integration test (Client_CanReconnect_AfterSessionExpiry)
using MapMcp with middleware to simulate 404 session expiry.

Clarify the two session ID concepts: transport session ID (McpSession.SessionId,
shared between client and server) vs telemetry session ID (mcp.session.id tag,
per-instance). Document that middleware should read Mcp-Session-Id from the
response header after await next() to capture it on the initialize request.

Initialize EnableLegacySse from AppContext switch in property initializer.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
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/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/prompts/prompts.md b/docs/concepts/prompts/prompts.md
@@ -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/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.
diff --git a/docs/concepts/sessions/sessions.md b/docs/concepts/sessions/sessions.md
diff --git a/docs/concepts/toc.yml b/docs/concepts/toc.yml
@@ -9,6 +9,8 @@ items:
     uid: capabilities
   - name: Transports
     uid: transports
+  - name: Sessions
+    uid: sessions
   - name: Ping
     uid: ping
   - name: Progress
@@ -39,8 +41,6 @@ items:
     uid: completions
   - name: Logging
     uid: logging
-  - name: Sessions
-    uid: sessions
   - name: HTTP Context
     uid: httpcontext
   - name: Filters
diff --git a/docs/concepts/tools/tools.md b/docs/concepts/tools/tools.md
@@ -262,7 +262,7 @@ if (result.IsError is true)
 
 ### Tool list change notifications
 
-Servers can dynamically add, remove, or modify tools at runtime. When the tool list changes, the server notifies connected clients so they can refresh their tool list.
+Servers can dynamically add, remove, or modify tools at runtime. When the tool list changes, the server notifies connected clients so they can refresh their tool list. 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/transports/transports.md b/docs/concepts/transports/transports.md
@@ -178,7 +178,7 @@ SSE-specific configuration options:
 
 #### SSE server (ASP.NET Core)
 
-The ASP.NET Core integration supports SSE transport alongside Streamable HTTP. Legacy SSE endpoints (`/sse` and `/message`) are **disabled by default** due to [backpressure concerns](xref:sessions#sse-legacy-1). To enable them, set <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.EnableLegacySse> to `true`. SSE always requires stateful mode; legacy SSE endpoints are never mapped when `Stateless = true`.
+The ASP.NET Core integration supports SSE transport alongside Streamable HTTP. Legacy SSE endpoints (`/sse` and `/message`) are **disabled by default** due to [backpressure concerns](xref:sessions#request-backpressure). To enable them, set <xref:ModelContextProtocol.AspNetCore.HttpServerTransportOptions.EnableLegacySse> to `true`. SSE always requires stateful mode; legacy SSE endpoints are never mapped when `Stateless = true`.
 
 ```csharp
 var builder = WebApplication.CreateBuilder(args);
@@ -255,3 +255,5 @@ var tools = await client.ListToolsAsync();
 var echo = tools.First(t => t.Name == "echo");
 Console.WriteLine(await echo.InvokeAsync(new() { ["arg"] = "Hello World" }));
 ```
+
+Like [stdio](#stdio-transport), the in-memory transport is inherently single-session — there is no `Mcp-Session-Id` header, and server-to-client requests (sampling, elicitation, roots) work naturally over the bidirectional pipe. This makes it ideal for testing servers that depend on these features. See [Sessions](xref:sessions) for how session behavior varies across transports.
diff --git a/src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs b/src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs
@@ -92,7 +92,8 @@ public class HttpServerTransportOptions
     /// </para>
     /// </remarks>
     [Obsolete(Obsoletions.EnableLegacySse_Message, DiagnosticId = Obsoletions.EnableLegacySse_DiagnosticId, UrlFormat = Obsoletions.EnableLegacySse_Url)]
-    public bool EnableLegacySse { get; set; }
+    public bool EnableLegacySse { get; set; } =
+        AppContext.TryGetSwitch("ModelContextProtocol.AspNetCore.EnableLegacySse", out var enabled) && enabled;
 
     /// <summary>
     /// Gets or sets the event store for resumability support.
diff --git a/src/ModelContextProtocol.AspNetCore/McpEndpointRouteBuilderExtensions.cs b/src/ModelContextProtocol.AspNetCore/McpEndpointRouteBuilderExtensions.cs
@@ -13,9 +13,6 @@ namespace Microsoft.AspNetCore.Builder;
 /// </summary>
 public static class McpEndpointRouteBuilderExtensions
 {
-    private static bool EnableLegacySseSwitch { get; } =
-        AppContext.TryGetSwitch("ModelContextProtocol.AspNetCore.EnableLegacySse", out var enabled) && enabled;
-
     /// <summary>
     /// Sets up endpoints for handling MCP Streamable HTTP transport.
     /// </summary>
@@ -35,7 +32,7 @@ public static IEndpointConventionBuilder MapMcp(this IEndpointRouteBuilder endpo
         var options = streamableHttpHandler.HttpServerTransportOptions;
 
 #pragma warning disable MCP9003 // EnableLegacySse - reading the obsolete property to check if SSE is enabled
-        if (options.Stateless && (options.EnableLegacySse || EnableLegacySseSwitch))
+        if (options.Stateless && options.EnableLegacySse)
         {
             throw new InvalidOperationException(
                 "Legacy SSE endpoints cannot be enabled in stateless mode because SSE requires in-memory session state " +
@@ -64,7 +61,7 @@ public static IEndpointConventionBuilder MapMcp(this IEndpointRouteBuilder endpo
             streamableHttpGroup.MapDelete("", streamableHttpHandler.HandleDeleteRequestAsync);
 
 #pragma warning disable MCP9003 // EnableLegacySse - reading the obsolete property to check if SSE is enabled
-            if (options.EnableLegacySse || EnableLegacySseSwitch)
+            if (options.EnableLegacySse)
 #pragma warning restore MCP9003
             {
                 // Map legacy HTTP with SSE endpoints. These are disabled by default because the SSE transport
diff --git a/tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs b/tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs
@@ -588,4 +588,124 @@ public async Task DisposeAsync_DoesNotHang_WhenOwnsSessionIsFalse_WithUnsolicite
         // Dispose should still not hang
         await client.DisposeAsync().AsTask().WaitAsync(TimeSpan.FromSeconds(10), TestContext.Current.CancellationToken);
     }
+
+    [Fact]
+    public async Task Client_CanReconnect_AfterSessionExpiry()
+    {
+        Assert.SkipWhen(Stateless, "Sessions don't exist in stateless mode.");
+
+        string? expiredSessionId = null;
+
+        Builder.Services.AddMcpServer().WithHttpTransport(ConfigureStateless).WithTools<ClaimsPrincipalTools>();
+
+        await using var app = Builder.Build();
+
+        // Middleware that returns 404 for the expired session, simulating server-side session expiry.
+        app.Use(next =>
+        {
+            return async context =>
+            {
+                if (expiredSessionId is not null &&
+                    context.Request.Headers["Mcp-Session-Id"].ToString() == expiredSessionId)
+                {
+                    context.Response.StatusCode = StatusCodes.Status404NotFound;
+                    return;
+                }
+                await next(context);
+            };
+        });
+
+        app.MapMcp();
+        await app.StartAsync(TestContext.Current.CancellationToken);
+
+        // Connect the first client and verify it works.
+        var client1 = await ConnectAsync();
+        var originalSessionId = client1.SessionId;
+        Assert.NotNull(originalSessionId);
+
+        var tools = await client1.ListToolsAsync(cancellationToken: TestContext.Current.CancellationToken);
+        Assert.NotEmpty(tools);
+
+        // Simulate session expiry by having the middleware reject the original session.
+        expiredSessionId = originalSessionId;
+
+        // The next request should fail.
+        await Assert.ThrowsAnyAsync<Exception>(async () =>
+            await client1.ListToolsAsync(cancellationToken: TestContext.Current.CancellationToken));
+
+        // Completion should resolve with a 404 status code.
+        var details = await client1.Completion.WaitAsync(TestContext.Current.CancellationToken);
+        var httpDetails = Assert.IsType<HttpClientCompletionDetails>(details);
+        Assert.Equal(HttpStatusCode.NotFound, httpDetails.HttpStatusCode);
+
+        await client1.DisposeAsync();
+
+        // Reconnect with a brand-new session.
+        await using var client2 = await ConnectAsync();
+        Assert.NotNull(client2.SessionId);
+        Assert.NotEqual(originalSessionId, client2.SessionId);
+
+        // The new session works normally.
+        tools = await client2.ListToolsAsync(cancellationToken: TestContext.Current.CancellationToken);
+        Assert.NotEmpty(tools);
+    }
+
+    [Fact]
+    public async Task EndpointFilter_CanReadSessionId_BeforeAndAfterHandler()
+    {
+        var capturedSessionIds = new ConcurrentBag<(string? BeforeNext, string? AfterNext, string Method)>();
+
+        Builder.Services.AddMcpServer().WithHttpTransport(ConfigureStateless).WithTools<EchoHttpContextUserTools>();
+
+        await using var app = Builder.Build();
+
+        // This is the pattern documented in sessions.md — verify it actually works.
+        app.MapMcp().AddEndpointFilter(async (context, next) =>
+        {
+            var httpContext = context.HttpContext;
+
+            // Read from request headers — available on all non-initialize requests in stateful mode.
+            var beforeSessionId = httpContext.Request.Headers["Mcp-Session-Id"].FirstOrDefault();
+
+            var result = await next(context);
+
+            // After the handler, check response headers.
+            var afterSessionId = httpContext.Response.Headers["Mcp-Session-Id"].FirstOrDefault();
+
+            capturedSessionIds.Add((beforeSessionId, afterSessionId, httpContext.Request.Method));
+            return result;
+        });
+
+        await app.StartAsync(TestContext.Current.CancellationToken);
+
+        await using var client = await ConnectAsync();
+
+        await client.ListToolsAsync(cancellationToken: TestContext.Current.CancellationToken);
+
+        // The filter ran for at least the initialize, initialized notification, and list_tools POSTs.
+        Assert.True(capturedSessionIds.Count >= 3);
+
+        if (Stateless)
+        {
+            // Stateless mode: no session IDs anywhere.
+            Assert.All(capturedSessionIds, c =>
+            {
+                Assert.Null(c.BeforeNext);
+                Assert.Null(c.AfterNext);
+            });
+        }
+        else
+        {
+            // Stateful mode: response header is set on every POST and GET response.
+            var postAndGetCaptures = capturedSessionIds.Where(c => c.Method is "POST" or "GET");
+            Assert.All(postAndGetCaptures, c =>
+            {
+                Assert.Equal(client.SessionId, c.AfterNext);
+            });
+
+            // At least one POST should have the session ID in the request header too
+            // (the initialized notification or list_tools — but not the initial initialize request).
+            Assert.Contains(capturedSessionIds, c => c.BeforeNext == client.SessionId);
+        }
+    }
 }
diff --git a/tests/ModelContextProtocol.Tests/DiagnosticTests.cs b/tests/ModelContextProtocol.Tests/DiagnosticTests.cs
@@ -87,6 +87,17 @@ await WaitForAsync(() => activities.Any(a =>
         using var listToolsJson = JsonDocument.Parse(clientToServerLog.First(s => s.Contains("\"method\":\"tools/list\"")));
         var metaJson = listToolsJson.RootElement.GetProperty("params").GetProperty("_meta").GetRawText();
         Assert.Equal($$"""{"traceparent":"00-{{clientListToolsCall.TraceId}}-{{clientListToolsCall.SpanId}}-01"}""", metaJson);
+
+        // Validate that mcp.session.id is set on both client and server activities and that
+        // all client activities share one session ID while all server activities share another.
+        var clientSessionId = Assert.Single(clientToolCall.Tags, t => t.Key == "mcp.session.id").Value;
+        var serverSessionId = Assert.Single(serverToolCall.Tags, t => t.Key == "mcp.session.id").Value;
+        Assert.NotNull(clientSessionId);
+        Assert.NotNull(serverSessionId);
+        Assert.NotEqual(clientSessionId, serverSessionId);
+
+        Assert.Equal(clientSessionId, clientListToolsCall.Tags.Single(t => t.Key == "mcp.session.id").Value);
+        Assert.Equal(serverSessionId, serverListToolsCall.Tags.Single(t => t.Key == "mcp.session.id").Value);
     }
 
     [Fact]
