Streamable HTTP clients can get stuck connecting

[richard-rance]

Describe the bug
When connecting to some MCP servers that support making SSE GET requests, client.Connect gets hung up waiting for the first notification from the server. This is particularly a problem if they don't manually flush the response buffer after writing the headers.

To Reproduce
I found the problem when running the following to connect to Zapier's MCP server. I then adjusted the unit tests to reproduce it locally in https://github.com/modelcontextprotocol/go-sdk/pull/634/files#diff-bc2db7f8b168cfd247ed95d1ac34698f70d9ad808c40102361253f4beda91058R110-R121

func main() {
	ctx := context.Background()

	client := mcp.NewClient(&mcp.Implementation{}, &mcp.ClientOptions{})
	logging.Infof(ctx, "Initializing...")

	cs, err := client.Connect(ctx,
		&mcp.StreamableClientTransport{
			Endpoint: "https://mcp.zapier.com/api/mcp/s/my-streamable-server-key-here/mcp",
		},
		&mcp.ClientSessionOptions{})
	if err != nil {
		logging.Errorf(ctx, "Failed to connect to MCP: %v", err)
		return
	}
	defer cs.Close()

	logging.Infof(ctx, "This doesn't run until the GET request times out 5 times")
}

Expected behavior
I expect creating a client connection to complete in under 1 second. (I tested this same server URL in other MCP clients.)
If the MCP server has configured their server correctly they will be able to send the client notifications.
If they haven't the client should still be able to use the server's tools, prompts and resources.

Additional context
This works as expected using the SDK version prior to #604 / #583. That PR changed initialization of the standalone SSE connection to be synchronous. That allows some server errors from starting the stand alone SSE connection be returned as part of client.Connect.

As a client developer I have no control over the server's behaviour. The server misbehaving only affects the server's ability to send notifications. If the POST initialization request is successful but the GET SSE stream is not it is probably because the server does not send messages so didn't test it. I don't think that creating the connection needs to wait for the stand alone SSE connection.

In my particular use case I am building a stateless client so would like to disable creating the standalone SSE connections entirely.

[findleyr]

Hi, I may have been hasty to make this block in #583, but let's figure it out once and for all.

The rationale was that connection should provide some guarantee that the bidirectional stream is established. For the streamable transport, that's not guaranteed until the standalone GET exists.

Previously, users have filed bugs against this SDK when the server transport didn't flush HTTP headers soon enough for the hanging GET (#410). I think it's a bug in the server you're connecting to that they don't send response headers immediately.

Rather than go back and forth changing SDK behavior to match certain servers, I'd prefer if we took this opportunity to form a consensus among SDKs. I can start this conversation.

To fix your specific problem, what do you think about adding a field to the StreamableClientTransport that disables the standalone GET entirely? If you agree that would be helpful, want to research what this field is called in other SDKs and file a proposal?

[richard-rance]

Sorry I missed seeing issue #410 when I checked. I total agree that it is a bug in the server if they don't flush. The question is what should the client do about it.

I had a look to see what the other SDKs are doing

Language	SSE starts	Configuration
C#	Async after receiving non-error response to `initialize` request	None
Go	Synchronous* after receiving non-error response to `initialize` request
Java	Async after receiving non-error response to `initialize` request	None
Kotlin	Synchronously after receiving 202 Accepted response to `notifications/initialized` notification	None
Python	Async in parallel with sending the notifications/initialized notification	Only starts if server returned a session id
Ruby	Undefined	Manual call by user so could be either or none
Rust	Async after sending the `notifications/initialized` notification	Only starts if server returned a session id
Swift	Async. May happen before the `initialize` request if the client does not make any other requests before `sseInitializationTimeout`	`streaming` = false will disable the GET SSE call
Typescript	Async after receiving 202 Accepted response to `notifications/initialized` notification	None

The general pattern that I saw was that after getting a non-error response from the initialize request the SDK will start an async task to setup the GET SSE stream.

The Swift SDK was the only one that had an option (streaming=false) to explicitly skip the GET SSE request.

A few clients only do it when the server returned a session id. I don't see anything in the spec indicating that is expected. The resumability section indicates that it might be called without a session. With dynamic client id registration there is a different client per install so session ids are not needed.

For the go-sdk I think it would make sense to add a bool property to StreamableClientTransport. The name should start with Disable so that the default behavior stays the same. The server can stream responses to post requests so I think we should be more explicit about what is being disabled. I would suggest DisableStandaloneStreaming or DisableServerInitiatedFeatures.

I'll leave it to you to follow up with the other SDK maintainers about what the correct way to start the SSE request is.

My Research Notes

C#

Always starts the ReceiveUnsolicitedMessagesAsync process after the Initialize request completes. It does so async. code

Of interest don't make users pick between steaming HTTP and SSE clients.
HttpClientTransportOptions has a TransportMode field with enum options of
AutoDetect (Default)
StreamableHttp
Sse

It also has OAuth options.

Java

Has a openConnectionOnStartup boolean option that defaults to not creating the SSE connection until the first request is made.

It looks like when the markInitilized request is made it always starts the SSE stream async.

Kotlin

It always starts the SSE stream after the client sends "notifications/initialized".

PHP

Is only a server SDK.

Python

Has option for sse_read_timeout that limits how long the connections stay open for.
The SSE only starts if a session id was returned when initializing. It runs in an async task group

It also has auth config settings

Ruby

It is a lower level SDK. Users need to make the POST initialize and GET SSE requests themselves.
It has a stateless boolean config option. When true it does not allow GET requests.

Rust

I had a hard time reading it but according to Cursor AI

The StreamableHttpClientTransportConfig struct provides:

• uri: Arc — Server URI endpoint
• retry_config: Arc — SSE reconnection policy
  • Default: ExponentialBackoff (starts at 1s, doubles each retry)
  • Options: ExponentialBackoff, FixedInterval, NeverRetry
• channel_buffer_capacity: usize — Internal message buffer size
  • Default: 16
• allow_stateless: bool — Allow operation without a session ID
  • Default: true
  • If false, initialization fails if no session_id is returned
• auth_header: Option — Bearer token (without "Bearer " prefix)
  • Default: None

It only starts the GET SSE stream if the server returns a session id

Swift

The Swift SDK had good documentation. The HTTPClientTransport options include

• streaming: Whether to enable SSE streaming mode (default: true)
• sseInitializationTimeout: Maximum time to wait for session ID before proceeding with SSE (default: 10 seconds)

The Client has a strict option that enforces the initialization request being made.

When client.Connect is called setting up the SSE stream is put into a background task. It waits upto a configurable amount of time for a session id to be set before making a stream without a session id. (Code)
The initialize request is not sent to the server until users make their first other message request.

Typescript

Has options to to control retry of the SSE.

• initialReconnectionDelay: 1000,
• maxReconnectionDelay: 30000,
• reconnectionDelayGrowFactor: 1.5,
• maxRetries: 2

StreamableHTTPClientTransportOptions also has an auth option that takes in a OAuthClientProvider

It always starts the GET SSE after sending an initialized notification. _startOrAuthSse is an async function that is not waited on during the connect flow. Any errors are caught and sent to the onerror handler function.