HTTP Transport

Configure HTTP transport options for MCP ASP.NET Core servers

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

Basic Usage

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

Redis Cache

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.