Streamable HTTP GET requests hang

[eleftherias]

Describe the bug
GET requests with valid session IDs do not immediately return HTTP headers as required by the MCP specification. Instead, they hang indefinitely until the client disconnects, at which point they return a 204 status.

According to the MCP Streamable HTTP Transport specification:

"The server MUST either return Content-Type: text/event-stream in response to this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server does not offer an SSE stream at this endpoint."

To Reproduce
Steps to reproduce the behavior:

1. Run any streamable HTTP MCP server, for example:

func main() {
	// Create a minimal MCP server
	server := mcp.NewServer(&mcp.Implementation{
		Name:    "minimal-test-server",
		Version: "1.0.0",
	}, nil)

	handler := mcp.NewStreamableHTTPHandler(func(req *http.Request) *mcp.Server {
		return server
	}, nil)

	port := 8010
	log.Printf("Starting minimal reproduction server on localhost:%d", port)

	if err := http.ListenAndServe(fmt.Sprintf("localhost:%d", port), handler); err != nil {
		log.Fatalf("Server failed: %v", err)
	}
}

2. Establish session

   curl -X POST http://localhost:8010/ \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' -i

3. Extract Mcp-Session-Id from response
4. Make a GET request

 curl -v -H "Accept: text/event-stream" -H "Mcp-Session-Id: <SESSION_ID>" http://localhost:8010/ --max-time 30

Expected behavior
When a client makes a GET request with a valid Mcp-Session-Id header:

1. Server should immediately respond with HTTP status 200 and headers including Content-Type: text/event-stream
2. Connection should remain open to stream server-sent events

Actual behavior

1. Server receives the GET request
2. No HTTP response headers are sent immediately
3. Request hangs indefinitely
4. Only when client disconnects/times out does server respond with status 204

[findleyr]

We do send text/event-stream, and 204 (no content) seems right when there are no messages along the hanging GET.

go-sdk/mcp/streamable.go

Line 749 in a1eb484

w.Header().Set("Content-Type", "text/event-stream") // Accept checked in [StreamableHTTPHandler]

If any data is written to the hanging GET, headers should be written along with status 200.

It sounds like the problems is that we need to force a flush of headers.

Can you say more about the problems this caused in practice? Is there a client that blocks until it receives the content-type header?

[findleyr]

Indeed, an explicit Flush fixes this. Thank you for the report.

[eleftherias]

Can you say more about the problems this caused in practice? Is there a client that blocks until it receives the content-type header?

Block's Goose blocks waiting for the response.

[findleyr]

@eleftherias would very much appreciate if you could verify that this fixes the problem you experienced.

[eleftherias]

Thanks @findleyr this fixes the issue