Make RunSessionHandler experimental (MCPEXP003)

Co-authored-by: halter73 <54385+halter73@users.noreply.github.com>

Author: Copilot

docs/list-of-diagnostics.md

@@ -25,6 +25,7 @@ If you use experimental APIs, you will get one of the diagnostics shown below. T
 | :------------ | :---------- |
 | `MCPEXP001` | MCP experimental APIs including Tasks and Extensions. Tasks provide a mechanism for asynchronous long-running operations that can be polled for status and results (see [MCP Tasks specification](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks)). Extensions provide a framework for extending the Model Context Protocol while maintaining interoperability (see [SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133)). |
 | `MCPEXP002` | Subclassing `McpClient` and `McpServer` is experimental and subject to change (see [#1363](https://github.com/modelcontextprotocol/csharp-sdk/pull/1363)). |
+| `MCPEXP003` | `RunSessionHandler` is experimental and may be removed or change signatures in a future release. Consider using `ConfigureSessionOptions` instead, which provides access to the `HttpContext` of the initializing request with fewer known issues. |
 
 ## Obsolete APIs
 

samples/EverythingServer/Program.cs

@@ -51,6 +51,7 @@
     .WithHttpTransport(options =>
     {
         // Add a RunSessionHandler to remove all subscriptions for the session when it ends
+#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
         options.RunSessionHandler = async (httpContext, mcpServer, token) =>
         {
             if (mcpServer.SessionId == null)
@@ -76,6 +77,7 @@
                 subscriptions.TryRemove(mcpServer.SessionId, out _);
             }
         };
+#pragma warning restore MCPEXP003
     })
     .WithTools<AddTool>()
     .WithTools<AnnotatedMessageTool>()

src/Common/Experimentals.cs

@@ -71,4 +71,19 @@ internal static class Experimentals
     /// URL for experimental subclassing of McpClient and McpServer.
     /// </summary>
     public const string Subclassing_Url = "https://github.com/modelcontextprotocol/csharp-sdk/pull/1363";
+
+    /// <summary>
+    /// Diagnostic ID for the experimental <c>RunSessionHandler</c> API.
+    /// </summary>
+    public const string RunSessionHandler_DiagnosticId = "MCPEXP003";
+
+    /// <summary>
+    /// Message for the experimental <c>RunSessionHandler</c> API.
+    /// </summary>
+    public const string RunSessionHandler_Message = "RunSessionHandler is experimental and may be removed or changed in a future release. Consider using ConfigureSessionOptions instead.";
+
+    /// <summary>
+    /// URL for the experimental <c>RunSessionHandler</c> API.
+    /// </summary>
+    public const string RunSessionHandler_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp003";
 }

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

@@ -24,7 +24,15 @@ public class HttpServerTransportOptions
     /// </summary>
     /// <remarks>
     /// This callback is useful for running logic before a session starts and after it completes.
+    /// <para>
+    /// Consider using <see cref="ConfigureSessionOptions"/> instead, which provides access to the
+    /// <see cref="HttpContext"/> of the initializing request with fewer known issues.
+    /// </para>
+    /// <para>
+    /// This API is experimental and may be removed or change signatures in a future release.
+    /// </para>
     /// </remarks>
+    [System.Diagnostics.CodeAnalysis.Experimental(Experimentals.RunSessionHandler_DiagnosticId, UrlFormat = Experimentals.RunSessionHandler_Url)]
     public Func<HttpContext, McpServer, CancellationToken, Task>? RunSessionHandler { get; set; }
 
     /// <summary>

src/ModelContextProtocol.AspNetCore/ModelContextProtocol.AspNetCore.csproj

@@ -20,6 +20,10 @@
     <None Include="README.md" pack="true" PackagePath="\" />
   </ItemGroup>
 
+  <ItemGroup>
+    <Compile Include="..\Common\Experimentals.cs" Link="Experimentals.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\ModelContextProtocol\ModelContextProtocol.csproj" />
   </ItemGroup>

src/ModelContextProtocol.AspNetCore/SseHandler.cs

@@ -56,7 +56,9 @@ public async Task HandleSseRequestAsync(HttpContext context)
                 await using var mcpServer = McpServer.Create(transport, mcpServerOptions, loggerFactory, context.RequestServices);
                 context.Features.Set(mcpServer);
 
+#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
                 var runSessionAsync = httpMcpServerOptions.Value.RunSessionHandler ?? StreamableHttpHandler.RunSessionAsync;
+#pragma warning restore MCPEXP003
                 await runSessionAsync(context, mcpServer, cancellationToken);
             }
             finally

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -390,7 +390,9 @@ private async ValueTask<StreamableHttpSession> CreateSessionAsync(
         var userIdClaim = GetUserIdClaim(context.User);
         var session = new StreamableHttpSession(sessionId, transport, server, userIdClaim, sessionManager);
 
+#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
         var runSessionAsync = HttpServerTransportOptions.RunSessionHandler ?? RunSessionAsync;
+#pragma warning restore MCPEXP003
         session.ServerRunTask = runSessionAsync(context, server, session.SessionClosed);
 
         return session;

tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs

@@ -213,12 +213,14 @@ public async Task CanResumeSessionWithMapMcpAndRunSessionHandler()
         }).WithHttpTransport(opts =>
         {
             ConfigureStateless(opts);
+#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
             opts.RunSessionHandler = async (context, server, cancellationToken) =>
             {
                 Interlocked.Increment(ref runSessionCount);
                 serverTcs.TrySetResult(server);
                 await server.RunAsync(cancellationToken);
             };
+#pragma warning restore MCPEXP003
         }).WithTools<EchoHttpContextUserTools>();
 
         await using var app = Builder.Build();
@@ -481,11 +483,13 @@ public async Task DisposeAsync_DoesNotHang_WhenOwnsSessionIsFalse_WithUnsolicite
         Builder.Services.AddMcpServer().WithHttpTransport(opts =>
         {
             ConfigureStateless(opts);
+#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
             opts.RunSessionHandler = async (context, server, cancellationToken) =>
             {
                 serverTcs.TrySetResult(server);
                 await server.RunAsync(cancellationToken);
             };
+#pragma warning restore MCPEXP003
         }).WithTools<ClaimsPrincipalTools>();
 
         await using var app = Builder.Build();

tests/ModelContextProtocol.AspNetCore.Tests/ResumabilityIntegrationTestsBase.cs

@@ -253,11 +253,13 @@ public virtual async Task Client_CanResumeUnsolicitedMessageStream_AfterDisconne
 
         await using var app = await CreateServerAsync(configureTransport: options =>
         {
+#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
             options.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
             {
                 serverTcs.TrySetResult(mcpServer);
                 return mcpServer.RunAsync(cancellationToken);
             };
+#pragma warning restore MCPEXP003
         });
 
         await using var client = await ConnectClientAsync();

tests/ModelContextProtocol.AspNetCore.Tests/SseIntegrationTests.cs

@@ -83,6 +83,7 @@ public async Task ConnectAndReceiveNotification_InMemoryServer()
         Builder.Services.AddMcpServer()
             .WithHttpTransport(httpTransportOptions =>
             {
+#pragma warning disable MCPEXP003 // RunSessionHandler is experimental
                 httpTransportOptions.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
                 {
                     // We could also use ServerCapabilities.NotificationHandlers, but it's good to have some test coverage of RunSessionHandler.
@@ -93,6 +94,7 @@ public async Task ConnectAndReceiveNotification_InMemoryServer()
                     });
                     return mcpServer.RunAsync(cancellationToken);
                 };
+#pragma warning restore MCPEXP003
             });
 
         await using var app = Builder.Build();