modelcontextprotocol/csharp-sdk
Watch
1
0
Fork
You've already forked csharp-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Mark RunSessionHandler experimental (MCPEXP002) (#1383)

Browse source 
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>
This commit is contained in:
Copilot 2026-02-24 15:02:34 -08:00 • committed by GitHub
commit 84cd6917bb
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
12 changed files with 82 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

4
docs/list-of-diagnostics.md
View file

@ -23,8 +23,8 @@ If you use experimental APIs, you will get one of the diagnostics shown below. T
| Diagnostic ID | Description |
| :------------ | :---------- |
| `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)). |
| `MCPEXP001` | Experimental APIs for features in the MCP specification itself, 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` | Experimental SDK APIs unrelated to the MCP specification itself, including subclassing `McpClient`/`McpServer` (see [#1363](https://github.com/modelcontextprotocol/csharp-sdk/pull/1363)) and `RunSessionHandler`, which may be removed or change signatures in a future release (consider using `ConfigureSessionOptions` instead). |
## Obsolete APIs

2
samples/EverythingServer/Program.cs
View file

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

43
src/Common/Experimentals.cs
View file

@ -6,10 +6,24 @@ namespace ModelContextProtocol;
/// Defines diagnostic IDs, messages, and URLs for APIs annotated with <see cref="ExperimentalAttribute"/>.
/// </summary>
/// <remarks>
/// Experimental diagnostic IDs are grouped by category:
/// <list type="bullet">
/// <item><description>
/// <c>MCPEXP001</c> covers APIs related to experimental features in the MCP specification itself,
/// such as Tasks and Extensions. These APIs may change as the specification evolves.
/// </description></item>
/// <item><description>
/// <c>MCPEXP002</c> covers experimental SDK APIs that are unrelated to the MCP specification,
/// such as subclassing internal types or SDK-specific extensibility hooks. These APIs may
/// change or be removed based on SDK design feedback.
/// </description></item>
/// </list>
/// <para>
/// When an experimental API is associated with an experimental specification, the message
/// should refer to the specification version that introduces the feature and the SEP
/// when available. If there is a SEP associated with the experimental API, the Url should
/// point to the SEP issue.
/// </para>
/// <para>
/// Experimental diagnostic IDs are in the format MCPEXP###.
/// </para>
@ -58,8 +72,14 @@ internal static class Experimentals
public const string Extensions_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp001";
/// <summary>
/// Diagnostic ID for experimental subclassing of McpClient and McpServer.
/// Diagnostic ID for experimental SDK APIs unrelated to the MCP specification,
/// such as subclassing <c>McpClient</c>/<c>McpServer</c> or referencing <c>RunSessionHandler</c>.
/// </summary>
/// <remarks>
/// This diagnostic ID covers experimental SDK-level extensibility APIs. All constants
/// in this group share the same diagnostic ID so users need only one suppression point
/// for SDK design preview features.
/// </remarks>
public const string Subclassing_DiagnosticId = "MCPEXP002";
/// <summary>
@ -70,5 +90,24 @@ internal static class Experimentals
/// <summary>
/// URL for experimental subclassing of McpClient and McpServer.
/// </summary>
public const string Subclassing_Url = "https://github.com/modelcontextprotocol/csharp-sdk/pull/1363";
public const string Subclassing_Url = "https://github.com/modelcontextprotocol/csharp-sdk/blob/main/docs/list-of-diagnostics.md#mcpexp002";
/// <summary>
/// Diagnostic ID for the experimental <c>RunSessionHandler</c> API.
/// </summary>
/// <remarks>
/// This uses the same diagnostic ID as <see cref="Subclassing_DiagnosticId"/> because
/// both are experimental SDK APIs unrelated to the MCP specification.
/// </remarks>
public const string RunSessionHandler_DiagnosticId = "MCPEXP002";
/// <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#mcpexp002";
}

13
src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs
View file

@ -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>

4
src/ModelContextProtocol.AspNetCore/ModelContextProtocol.AspNetCore.csproj
View file

@ -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>

2
src/ModelContextProtocol.AspNetCore/SseHandler.cs
View file

@ -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

2
src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs
View file

@ -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;

4
tests/ModelContextProtocol.AspNetCore.Tests/MapMcpStreamableHttpTests.cs
View file

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

2
tests/ModelContextProtocol.AspNetCore.Tests/ResumabilityIntegrationTestsBase.cs
View file

@ -253,11 +253,13 @@ public abstract class ResumabilityIntegrationTestsBase(ITestOutputHelper testOut
await using var app = await CreateServerAsync(configureTransport: options =>
{
#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
options.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
{
serverTcs.TrySetResult(mcpServer);
return mcpServer.RunAsync(cancellationToken);
};
#pragma warning restore MCPEXP002
});
await using var client = await ConnectClientAsync();

2
tests/ModelContextProtocol.AspNetCore.Tests/SseIntegrationTests.cs
View file

@ -83,6 +83,7 @@ public partial class SseIntegrationTests(ITestOutputHelper outputHelper) : Kestr
Builder.Services.AddMcpServer()
.WithHttpTransport(httpTransportOptions =>
{
#pragma warning disable MCPEXP002 // 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 partial class SseIntegrationTests(ITestOutputHelper outputHelper) : Kestr
});
return mcpServer.RunAsync(cancellationToken);
};
#pragma warning restore MCPEXP002
});
await using var app = Builder.Build();

2
tests/ModelContextProtocol.AspNetCore.Tests/StatelessServerTests.cs
View file

@ -158,6 +158,7 @@ public class StatelessServerTests(ITestOutputHelper outputHelper) : KestrelInMem
Builder.Services.AddMcpServer()
.WithHttpTransport(options =>
{
#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
options.RunSessionHandler = async (context, server, cancellationToken) =>
{
unsolicitedNotificationException = await Assert.ThrowsAsync<InvalidOperationException>(
@ -165,6 +166,7 @@ public class StatelessServerTests(ITestOutputHelper outputHelper) : KestrelInMem
await server.RunAsync(cancellationToken);
};
#pragma warning restore MCPEXP002
});
await StartAsync();

6
tests/ModelContextProtocol.AspNetCore.Tests/StreamableHttpServerConformanceTests.cs
View file

@ -325,11 +325,13 @@ public class StreamableHttpServerConformanceTests(ITestOutputHelper outputHelper
Builder.Services.AddMcpServer()
.WithHttpTransport(options =>
{
#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
options.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
{
server = mcpServer;
return mcpServer.RunAsync(cancellationToken);
};
#pragma warning restore MCPEXP002
});
await StartAsync();
@ -365,11 +367,13 @@ public class StreamableHttpServerConformanceTests(ITestOutputHelper outputHelper
Builder.Services.AddMcpServer()
.WithHttpTransport(options =>
{
#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
options.RunSessionHandler = (httpContext, mcpServer, cancellationToken) =>
{
server = mcpServer;
return mcpServer.RunAsync(cancellationToken);
};
#pragma warning restore MCPEXP002
});
await StartAsync();
@ -502,11 +506,13 @@ public class StreamableHttpServerConformanceTests(ITestOutputHelper outputHelper
.WithHttpTransport(options =>
{
options.PerSessionExecutionContext = true;
#pragma warning disable MCPEXP002 // RunSessionHandler is experimental
options.RunSessionHandler = async (httpContext, mcpServer, cancellationToken) =>
{
asyncLocal.Value = $"RunSessionHandler ({totalSessionCount++})";
await mcpServer.RunAsync(cancellationToken);
};
#pragma warning restore MCPEXP002
});
Builder.Services.AddSingleton(McpServerTool.Create([McpServerTool(Name = "async-local-session")] () => asyncLocal.Value));