Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/modelcontextprotocol/csharp-sdk/llms.txt

Use this file to discover all available pages before exploring further.

The HttpServerTransportOptions class configures the Streamable HTTP transport implementation for Model Context Protocol servers in ASP.NET Core.

​
HttpServerTransportOptions

Configure HTTP transport behavior when calling WithHttpTransport().

​
Properties

​
ConfigureSessionOptions
Func<HttpContext, McpServerOptions, CancellationToken, Task>?
Optional callback to configure per-session McpServerOptions with access to the HttpContext of the request that initiated the session.Use this to customize server options based on the incoming request, such as filtering tools by route parameters or user claims.
​
RunSessionHandler
Func<HttpContext, McpServer, CancellationToken, Task>?
Optional callback for running new MCP sessions manually.
This is an experimental API. The HttpContext parameter comes from the request that initiated the session and may not be usable after McpServer.RunAsync() starts. Consider using ConfigureSessionOptions instead.
Useful for running logic before a session starts and after it completes.
​
Stateless
bool
default:"false"
Indicates whether the server runs in stateless mode without tracking state between requests, allowing for load balancing without session affinity.When true:
  • McpSession.SessionId will be null
  • “MCP-Session-Id” header is not used
  • RunSessionHandler is called once per request
  • “/sse” endpoint is disabled
  • Unsolicited server-to-client messages are unsupported
  • Server-to-client requests are unsupported
  • Client sampling, elicitation, and roots capabilities are disabled
​
EventStreamStore
ISseEventStreamStore?
Event store for resumability support. When set, events are stored and can be replayed when clients reconnect with a Last-Event-ID header.The server will:
  • Generate unique event IDs for each SSE message
  • Store events for later replay
  • Replay missed events when a client reconnects with a Last-Event-ID header
  • Send priming events to establish resumability before actual messages
Can be set directly or resolved from DI. See WithDistributedCacheEventStreamStore for automatic configuration.
​
SessionMigrationHandler
ISessionMigrationHandler?
Session migration handler for cross-instance session migration.When configured, the server supports session migration between instances. If a request arrives with a session ID not found locally, the handler is consulted to determine if the session can be migrated from another instance.Can be set directly or resolved from DI.
​
PerSessionExecutionContext
bool
default:"false"
Indicates whether the server uses a single execution context for the entire session.When false, handlers get called with the ExecutionContext belonging to the corresponding HTTP request.When true, handlers get called with the same ExecutionContext used for ConfigureSessionOptions and RunSessionHandler. Useful for setting AsyncLocal<T> variables that persist for the entire session, but prevents using IHttpContextAccessor in handlers.
​
IdleTimeout
TimeSpan
default:"2 hours"
Duration the server waits between any active requests before timing out an MCP session.Checked in the background every 5 seconds. Clients trying to resume a timed-out session receive a 404 status code and should restart. Clients can keep sessions open by maintaining a GET request.
​
MaxIdleSessionCount
int
default:"10000"
Maximum number of idle sessions to track in memory.When exceeded, the server logs a critical error and terminates the oldest idle sessions until the count is below this limit. Active sessions with open GET requests don’t count towards this limit.
​
TimeProvider
TimeProvider
default:"TimeProvider.System"
Time provider used for testing the IdleTimeout. Primarily for testing scenarios.

​
WithHttpTransport

Extension method to add HTTP transport services to an MCP server. 
public static IMcpServerBuilder WithHttpTransport(
    this IMcpServerBuilder builder,
    Action<HttpServerTransportOptions>? configureOptions = null)

​
Parameters

​
builder
IMcpServerBuilder
required
The MCP server builder instance.
​
configureOptions
Action<HttpServerTransportOptions>?
Optional callback to configure HTTP transport options.

​
Returns

​
IMcpServerBuilder
The builder instance for method chaining.

​
Example

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMcpServer()
    .WithHttpTransport()
    .WithTools<MyTools>();

var app = builder.Build();
app.MapMcp();
app.Run();

​
WithDistributedCacheEventStreamStore

Registers a DistributedCacheEventStreamStore as the ISseEventStreamStore for SSE resumability. 
public static IMcpServerBuilder WithDistributedCacheEventStreamStore(
    this IMcpServerBuilder builder,
    Action<DistributedCacheEventStreamStoreOptions>? configureOptions = null)
An IDistributedCache implementation must be registered in the service collection before calling this method.

​
Parameters

​
builder
IMcpServerBuilder
required
The MCP server builder instance.
​
configureOptions
Action<DistributedCacheEventStreamStoreOptions>?
Optional callback to configure event stream store options.

​
DistributedCacheEventStreamStoreOptions

​
Cache
IDistributedCache?
The distributed cache instance to use for event storage. Automatically populated from DI if not set.
​
EventSlidingExpiration
TimeSpan?
default:"30 minutes"
Sliding expiration for individual events. Events are refreshed on each access.
​
EventAbsoluteExpiration
TimeSpan?
default:"2 hours"
Absolute expiration for individual events. Events are evicted after this period regardless of access.
​
MetadataSlidingExpiration
TimeSpan?
default:"1 hour"
Sliding expiration for stream metadata (mode and completion status).
​
MetadataAbsoluteExpiration
TimeSpan?
default:"4 hours"
Absolute expiration for stream metadata.
​
StreamReaderPollingInterval
TimeSpan
default:"1 second"
Interval between polling attempts when a stream reader is waiting for new events. Shorter intervals provide lower latency but increase cache access frequency.

​
Example

builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = "localhost:6379";
});

builder.Services.AddMcpServer()
    .WithHttpTransport()
    .WithDistributedCacheEventStreamStore(options =>
    {
        options.EventSlidingExpiration = TimeSpan.FromMinutes(60);
        options.EventAbsoluteExpiration = TimeSpan.FromHours(4);
    });

​
Protocol Specification

For details on the Streamable HTTP transport, see the MCP Streamable HTTP specification. The ASP.NET Core package also supports legacy HTTP with SSE endpoints at “/sse” and “/message” for backward compatibility. See the HTTP with SSE specification.

Build docs developers (and LLMs) love

Get started for freeTalk to us