Mark RunSessionHandler experimental (MCPEXP002) (#1383)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: halter73 <54385+halter73@users.noreply.github.com>
Co-authored-by: jeffhandley <1031940+jeffhandley@users.noreply.github.com>

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

@@ -24,7 +24,20 @@ public class HttpServerTransportOptions
     /// </summary>
     /// <remarks>
     /// This callback is useful for running logic before a session starts and after it completes.
+    /// <para>
+    /// The <see cref="HttpContext"/> parameter comes from the request that initiated the session (e.g., the
+    /// initialize request) and may not be usable after <see cref="McpServer.RunAsync"/> starts, since that
+    /// request will have already completed.
+    /// </para>
+    /// <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 @@ internal sealed class SseHandler(
                 await using var mcpServer = McpServer.Create(transport, mcpServerOptions, loggerFactory, context.RequestServices);
                 context.Features.Set(mcpServer);
 
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
                 var runSessionAsync = httpMcpServerOptions.Value.RunSessionHandler ?? StreamableHttpHandler.RunSessionAsync;
+#pragma warning restore MCPEXP002
                 await runSessionAsync(context, mcpServer, cancellationToken);
             }
             finally

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

@@ -390,7 +390,9 @@ internal sealed class StreamableHttpHandler(
         var userIdClaim = GetUserIdClaim(context.User);
         var session = new StreamableHttpSession(sessionId, transport, server, userIdClaim, sessionManager);
 
+#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
         var runSessionAsync = HttpServerTransportOptions.RunSessionHandler ?? RunSessionAsync;
+#pragma warning restore MCPEXP002
         session.ServerRunTask = runSessionAsync(context, server, session.SessionClosed);
 
         return session;