Streamable HTTP resumability + redelivery + SSE polling via server-side disconnect #1077

MackinnonBuck · 2025-12-09T00:12:00Z

Overview

This PR implements the following features:

Client-side polling via the Last-Event-ID header
An ISseEventStreamStore abstraction to allow for storage and replay of SSE events
Server-side resumability of SSE streams via the Last-Event-ID header
Server-side disconnect (to enable client-side polling)

Each of these features has been split into its own commit for ease of review.

Description

There are two disconnection scenarios covered by this PR:

Network errors (unintentional disconnection)
Server-side programmatic disconnection

If a network error occurs, and an ISseEventStreamStore is configured, then the client may attempt to reconnect by making a GET request with a Last-Event-ID header. The server will then replay stored events before continuing to use the new GET response to stream remaining events. If further disconnections happen, the client may continue to make new GET requests to resume the stream. This applies for both client-initiated requests (POST) and the unsolicited message stream (GET).

However, the server can also initiate a disconnection and force the client to poll for updates. This is useful for avoiding long-running streams. This can be done via the new RequestContext<TParams>.EnablePollingAsync(TimeSpan retryInterval, CancellationToken cancellationToken = default) API. When the client reconnects via GET with a Last-Event-ID, the response will only contain events currently available in the ISseEventStreamStore before completing. The client must continue initiating new GET requests at the specified retryInterval until the final response is received.

Fixes #510
Fixes #1020

src/ModelContextProtocol.Core/Protocol/JsonRpcMessageContext.cs

src/ModelContextProtocol.Core/Server/RequestContext.cs

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

src/ModelContextProtocol.Core/McpSessionHandler.cs

tests/ModelContextProtocol.AspNetCore.Tests/Utils/InMemoryEventStore.cs

src/ModelContextProtocol.AspNetCore/HttpServerTransportOptions.cs

src/ModelContextProtocol.Core/Client/StreamableHttpClientSessionTransport.cs

src/ModelContextProtocol.Core/Server/IEventStore.cs

src/ModelContextProtocol.Core/Server/ISseEventStore.cs

src/ModelContextProtocol.Core/Server/IEventStore.cs

src/ModelContextProtocol.Core/Server/SseWriter.cs

mikekistler

I didn't get through all of this but want to share the comments I've made so far.

src/ModelContextProtocol.Core/Server/ISseEventStore.cs

src/ModelContextProtocol.Core/Server/SseReplayResult.cs

src/ModelContextProtocol.Core/Server/SseStreamEventStore.cs

src/ModelContextProtocol.Core/Server/SseWriter.cs

src/ModelContextProtocol.AspNetCore/McpEndpointRouteBuilderExtensions.cs

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

…delivery

src/ModelContextProtocol.AspNetCore/McpEndpointRouteBuilderExtensions.cs

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

tests/ModelContextProtocol.AspNetCore.Tests/Utils/KestrelInMemoryTest.cs

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

src/ModelContextProtocol.Core/McpSessionHandler.cs

src/ModelContextProtocol.Core/Client/HttpClientTransportOptions.cs

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

…s.cs Co-authored-by: Stephen Halter <halter73@gmail.com>

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

src/ModelContextProtocol.Core/McpSessionHandler.cs

halter73 · 2026-01-07T02:31:28Z

src/ModelContextProtocol.Core/Server/SseWriter.cs

+    public Task<bool> SendPrimingEventAsync(TimeSpan retryInterval, ISseEventStreamWriter eventStreamWriter, CancellationToken cancellationToken = default)
+    {
+        // Create a priming event: empty data with an event ID
+        var primingItem = new SseItem<JsonRpcMessage?>(null, "prime")


Do we really need to write "event: prime"? Do the other SDK's do that? I think the TS SDK just omits the event despite emiting a redundant "event: message" for normal messages.

@mikekistler said that the event should be "prime": #1077 (comment) , but the spec doesn't seem to require a specific event name. It's possible we could just use an empty event.

Given that clients broke without "event: message" previously, I know they can be very picky. I think we should align with the TS SDK as much as possible for the text/event-stream response format unless it's clearly wrong.

It looks like the .NET SseItem type always includes an event type. If you specify null, it defaults to "message".

So if we're forced to have an event type, maybe specifying "prime" is better.

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

tests/ModelContextProtocol.AspNetCore.Tests/SseEventStreamStoreTests.cs

src/ModelContextProtocol.Core/Server/ISseEventStreamStore.cs

src/ModelContextProtocol.Core/Server/ISseEventStreamWriter.cs

src/ModelContextProtocol.Core/Server/SseEventStreamMode.cs

MackinnonBuck · 2026-01-09T18:54:56Z

tests/ModelContextProtocol.AspNetCore.Tests/StreamableHttpServerConformanceTests.cs

        SetSessionId(sessionId);

        // Call the subscribe method to capture the McpServer instance.
+        using var getResponse = await HttpClient.GetAsync("", HttpCompletionOption.ResponseHeadersRead, TestContext.Current.CancellationToken);


I adjusted this test to initiate the GET request earlier, before the server attempts to send a notification.

The test previously had the server send a notification before the client started the GET request. This worked because the SseWriter's channel buffered the message rather than immediately attempting to write it to the response stream. However, I doubt this was officially a supported scenario, because writing a second notification would have created a deadlock due to the channel filling up (it only had a capacity of 1).

The new implementation just throws if SendNotificationAsync is called before StreamableHttpServerTransport.HandleGetRequestAsync(), because the transport now writes directly to the response stream instead of flowing the message through a channel.

src/ModelContextProtocol.Core/Client/StreamableHttpClientSessionTransport.cs

src/ModelContextProtocol.Core/Server/ISseEventStreamWriter.cs

src/ModelContextProtocol.Core/Server/SseEventStreamMode.cs

src/ModelContextProtocol.AspNetCore/SseEventStreamReaderExtensions.cs

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

halter73 · 2026-01-12T20:50:55Z

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

+        {
+            // The response has completed, and there is no event stream to store the message.
            // Rather than drop the message, fall back to sending it via the parent transport.
            await parentTransport.SendMessageAsync(message, cancellationToken).ConfigureAwait(false);


Whether or not we send the message over the unsolicited GET SSE stream should never be dependent on whether an event store has been configured.

I understand that this logic is mostly for after the response or error for the given request has been written, but it could still be hit in a scenario where there never was an event store and the POST request was aborted prior to the associated request handler completing. We should drop the message in this scenario just like we would if there was an event store that the client never resumed.

it could still be hit in a scenario where there never was an event store and the POST request was aborted prior to the associated request handler completing.

FWIW, this was true prior to this PR. This new logic preserves the original behavior of writing to the parent transport if a message is sent after the response completes, which was introduced in #832.

This logic was creating problems when an ISseEventStore was configured, because messages may then be received twice (once over the original GET stream and again on the resumed stream). Hence the new condition.

Maybe we should update this logic to only send messages via the parent transport if a response or error message has already been sent. This would address the notification scenario that the original PR was intended to support, and it wouldn't interfere with the ISseEventStore (as we'd simply skip writing to the stream in that case).

I've just updated the logic to only fall back to the parent transport for messages sent after the final response/error message.

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs

tests/ModelContextProtocol.AspNetCore.Tests/ResumabilityIntegrationTests.cs

…onTransport.cs Co-authored-by: Stephen Halter <halter73@gmail.com>

halter73

This looks really good. Thanks for responding to all the feedback!

halter73 · 2026-01-14T00:06:52Z

src/Common/ServerSentEvents/ArrayBuffer.cs

+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+// Copied from https://github.com/dotnet/runtime/blob/main/src/libraries/Common/src/System/Net/ArrayBuffer.cs


Suggested change

// Copied from https://github.com/dotnet/runtime/blob/main/src/libraries/Common/src/System/Net/ArrayBuffer.cs

// Copied from https://github.com/dotnet/runtime/blob/3499f694c22a8ed2c4cbdc2bc47de9868bbe32de/src/libraries/Common/src/System/Net/ArrayBuffer.cs

halter73 · 2026-01-14T00:07:13Z

src/Common/ServerSentEvents/ArrayBuffer.cs

+#if NET
+    private static int ArrayMaxLength => Array.MaxLength;
+#else
+        private const int ArrayMaxLength = 0X7FFFFFC7;


Suggested change

private const int ArrayMaxLength = 0X7FFFFFC7;

private const int ArrayMaxLength = 0X7FFFFFC7;

halter73 · 2026-01-14T00:24:08Z

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

+    private ISseEventStreamWriter? _sseEventStreamWriter;
    private RequestId _pendingRequest;
+    private bool _finalResponseMessageSent;
+    private bool _originalResponseCompleted;


Since there's both the JSON-RPC response and the HTTP response, I like adding HTTP to avoid conflating the two. It might be good even to rename responseStream to httpResponseStream.

These are just my suggestions though. You can definitely keep the current naming if you like it better.

Suggested change

private bool _originalResponseCompleted;

private readonly TaskCompletionSource<bool> _httpResponseTcs = new(TaskCreationOptions.RunContinuationsAsynchronously);

private readonly SseEventWriter _httpSseWriter = new(responseStream);

private TaskCompletionSource<bool>? _storeTcs;

private ISseEventStreamWriter? _storeSseWriter;

private RequestId _pendingRequest;

private bool _finalResponseMessageSent;

private bool _httpResponseCompleted;

halter73 · 2026-01-14T00:30:11Z

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs


-            if (message.Data is JsonRpcResponse or JsonRpcError && ((JsonRpcMessageWithId)message.Data).Id == _pendingRequest)
+        _streamTcs = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously);
+        _ = HandleStreamWriterDisposalAsync(_streamTcs.Task, cancellationToken);


We cannot always bubble up unhandled exceptions through the public API now that code can continue running after

I think we're going to have to bite the bullet and add a new constructor to StreamableHttpServerTransport that takes an optional ILoggerFactory, so we can at least log errors if _sseEventStreamWriter!.DisposeAsync() throws in HandleStreamWriterDisposalAsync.

We don't have to do it in this PR, but I think we should follow up quickly if not.

halter73 · 2026-01-14T00:42:38Z

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs

    /// The HTTP application should typically respond with an empty "202 Accepted" response in this scenario.
    /// </returns>
-    public async ValueTask<bool> HandlePostAsync(JsonRpcMessage message, CancellationToken cancellationToken)
+    public async ValueTask<bool> HandlePostAsync(JsonRpcMessage message, CancellationToken postCancellationToken, CancellationToken sessionCancellationToken)


I was going to recommend keeping the sessionCancellationToken naming in HandleStreamWriterDisposalAsync and TryStartSseEventStreamAsync, but could we just make the sessionCancellationToken a constructor parameter for StreamableHttpPostTransport? If not, I think we should be more explicit about the name in the private methods too.

halter73 reviewed Dec 9, 2025

View reviewed changes

stephentoub reviewed Dec 9, 2025

View reviewed changes

mikekistler reviewed Dec 11, 2025

View reviewed changes

MackinnonBuck added 5 commits December 16, 2025 15:40

Client-side polling via Last-Event-ID

1e407ce

ISseEventStreamStore and test implementation

677d9ea

Server-side resumability via Last-Event-ID

63fb022

Server-side disconnect

11494e1

Integration tests

493062a

MackinnonBuck force-pushed the mbuck/resumability-redelivery branch from 348fac0 to 493062a Compare December 17, 2025 00:14

Make EnablePollingAsync no-op in stateless mode

fe71286

MackinnonBuck commented Dec 17, 2025

View reviewed changes

src/ModelContextProtocol.AspNetCore/McpEndpointRouteBuilderExtensions.cs Show resolved Hide resolved

src/ModelContextProtocol.AspNetCore/StreamableHttpHandler.cs Show resolved Hide resolved

src/ModelContextProtocol.Core/Server/StreamableHttpServerTransport.cs Outdated Show resolved Hide resolved

MackinnonBuck marked this pull request as ready for review December 17, 2025 04:31

Merge remote-tracking branch 'origin/main' into mbuck/resumability-re…

2065c0e

…delivery

halter73 reviewed Dec 18, 2025

View reviewed changes

src/ModelContextProtocol.Core/Server/StreamableHttpPostTransport.cs Outdated Show resolved Hide resolved

MackinnonBuck and others added 11 commits December 18, 2025 11:10

Update src/ModelContextProtocol.Core/Client/HttpClientTransportOption…

66fcdb1

…s.cs Co-authored-by: Stephen Halter <halter73@gmail.com>

PR feedback: Don't dispose _sseWriter on final message

c9044c8

PR feedback: Use SseEventStreamMode.Default for unsolicited messages

2f19044

Return 405 on GET in statless mode

f6858ab

Make completing POST responses more robust

8e617bd

Fix TestSseEventStreamStore and make tests more robust

1fdec43

Allow tests to configure their own HttpClient

ef6dd62

Add test: Using an event ID for a different session

58ee59e

Require negotiated protocol version for priming

4dd7383

Improve StreamableHttpPostTransport thread safety

7262e5d

Acquire lock before writing to parent transport

2f7a923

halter73 reviewed Jan 7, 2026

View reviewed changes

halter73 mentioned this pull request Jan 7, 2026

Support stream resumption in stateless mode #1131

Open

MackinnonBuck added 2 commits January 8, 2026 14:51

PR feedback

7804475

Simplify SSE message writing

c2bffd9

MackinnonBuck commented Jan 9, 2026

View reviewed changes

MackinnonBuck added 4 commits January 9, 2026 11:17

PR feedback

45b7382

PR feedback: Throw in EnablePollingAsync

b221f37

PR feedback: Delete SseEventStreamStoreTests

0f9c09f

Make client default reconnection interval configurable

e589876

MackinnonBuck mentioned this pull request Jan 10, 2026

Add DistributedCacheEventStreamStore #1136

Draft

scutuatua-crypto approved these changes Jan 10, 2026

View reviewed changes

halter73 reviewed Jan 12, 2026

View reviewed changes

MackinnonBuck and others added 6 commits January 12, 2026 13:15

Update src/ModelContextProtocol.Core/Client/StreamableHttpClientSessi…

1376430

…onTransport.cs Co-authored-by: Stephen Halter <halter73@gmail.com>

PR feedback

f467015

Drop messages rather than throwing

fe1264c

PR feedback: use init over set

1b1a368

PR feedback: Attempt reconnection on 500 responses

e531a92

PR feedback: Rename _diposed variable

d0cbd05

jeffhandley mentioned this pull request Jan 13, 2026

Add 2025-11-25 as supported version #1130

Open

MackinnonBuck added 4 commits January 13, 2026 11:58

PR feedback: Make stream completion more reliable

b627cba

Remove RetryInterval from HttpServerTransportOptions

b6d4398

Only fallback to parent transport after final message

cb78114

Fix flaky test

e8c3032

halter73 approved these changes Jan 14, 2026

View reviewed changes

	// Copied from https://github.com/dotnet/runtime/blob/main/src/libraries/Common/src/System/Net/ArrayBuffer.cs
	// Copied from https://github.com/dotnet/runtime/blob/3499f694c22a8ed2c4cbdc2bc47de9868bbe32de/src/libraries/Common/src/System/Net/ArrayBuffer.cs

	private const int ArrayMaxLength = 0X7FFFFFC7;
	private const int ArrayMaxLength = 0X7FFFFFC7;

-    private bool _originalResponseCompleted;
+    private readonly TaskCompletionSource<bool> _httpResponseTcs = new(TaskCreationOptions.RunContinuationsAsynchronously);
+    private readonly SseEventWriter _httpSseWriter = new(responseStream);
+    private TaskCompletionSource<bool>? _storeTcs;
+    private ISseEventStreamWriter? _storeSseWriter;
+    private RequestId _pendingRequest;
+    private bool _finalResponseMessageSent;
+    private bool _httpResponseCompleted;

Streamable HTTP resumability + redelivery + SSE polling via server-side disconnect #1077

Are you sure you want to change the base?

Streamable HTTP resumability + redelivery + SSE polling via server-side disconnect #1077

Conversation

MackinnonBuck commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Description

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mikekistler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

halter73 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

MackinnonBuck commented Dec 9, 2025 •

edited

Loading