Support application/json responses in Streamable HTTP transport (opt-in JSON response mode)

[thiagomendes]

Expected Behavior

An opt-in configuration to return application/json for JSON-RPC requests within the Streamable HTTP transport, even with active sessions. Example:

HttpServletStreamableServerTransportProvider.builder()
    .jsonMapper(mapper)
    .mcpEndpoint("/mcp")
    .jsonResponse(true)    // opt-in, default false
    .build();

When enabled, doPost() for JSONRPCRequest would buffer the response from session.responseStream() and return it as application/json instead of opening an SSE stream. Server-initiated notifications would go through the standalone SSE stream (GET on the same /mcp endpoint, as defined in the Streamable HTTP spec).

All other official MCP SDKs already support this as an opt-in option:

SDK	Config option	Default
Go	StreamableHTTPOptions.JSONResponse bool	false
Python	is_json_response_enabled: bool	False
TypeScript	enableJsonResponse?: boolean	false
Rust	StreamableHttpServerConfig.json_response: bool	false

Current Behavior

In HttpServletStreamableServerTransportProvider.doPost(), session-bound JSONRPCRequest messages always get text/event-stream:

else if (message instanceof McpSchema.JSONRPCRequest jsonrpcRequest) {
    // For streaming responses, we need to return SSE
    response.setContentType(TEXT_EVENT_STREAM);   // ← always SSE
    // ...
}

There is no way to get application/json for session-bound requests. The initialize request (line 461) and HttpServletStatelessServerTransport (line 173) already return application/json - so the pattern exists in the codebase.

Context

The MCP Streamable HTTP spec (2025-06-18, §2.1.5) states:

"If the input is a JSON-RPC request, the server MUST either return Content-Type: text/event-stream [...] or Content-Type: application/json, to return one JSON object."

This means session management does not require SSE for every response. There are scenarios where a server benefits from sessions (capability negotiation, logging, server-initiated notifications via GET) but its tool handlers produce simple single-message responses that don't need SSE framing.

The existing STATELESS mode (HttpServletStatelessServerTransport) does return application/json, but it removes session management entirely - no server-to-client notifications, no sampling, no capability tracking. This feature request is about supporting application/json responses within the Streamable transport, with sessions, as the spec allows and as the other SDKs already implement.

In local benchmarks comparing MCP server implementations across different SDKs, we observed that switching from SSE-only to JSON responses for simple tool calls (single request-response, no intermediate notifications) resulted in significant performance improvements, primarily due to eliminating chunked transfer encoding, AsyncContext lifecycle overhead, and SSE framing/parsing on both server and client sides.

Would it make sense to add this? Happy to contribute a PR if the maintainers agree.

[chemicL]

Hey, thanks. Absolutely that would be wonderful to give that option as well. The design question to resolve is - do you have an idea how to evolve the API around Mcp(Sync|Async)ServerExchange to handle that gracefully without branching logic at every handler? It would also be reasonable to address this together with a design idea for the stateless transport to allow a symmetrical option to upgrade to SSE. Let's discuss this before you open a PR. Thanks!

[thiagomendes]

Hey, thanks. Absolutely that would be wonderful to give that option as well. The design question to resolve is - do you have an idea how to evolve the API around Mcp(Sync|Async)ServerExchange to handle that gracefully without branching logic at every handler? It would also be reasonable to address this together with a design idea for the stateless transport to allow a symmetrical option to upgrade to SSE. Let's discuss this before you open a PR. Thanks!

Great questions @chemicL ! I took a closer look at the codebase to think through the design.

1. Exchange/Handler API: No changes needed

The McpRequestHandler is already transport-agnostic, returning Mono<T> with no awareness of SSE or JSON. The JSON/SSE decision can be resolved below the handler layer, so no branching is needed in handler code.

In McpStreamableServerSession.responseStream() (line 198), the flow is:

requestHandler.handle(exchange, params)   // returns Mono<response> - handler doesn't know about transport
    .map(result -> JSONRPCResponse)        // wraps result
    .flatMap(transport::sendMessage)        // transport decides format
    .then(transport.closeGracefully())

For JSON mode, the transport provider could adapt how responseStream() is used, collecting the JSONRPCResponse and writing it as application/json rather than streaming via SSE. A similar pattern already exists in HttpServletStatelessServerTransport.doPost() (line 137-180).

One subtlety I noticed: if a handler calls exchange.progressNotification() or exchange.loggingNotification() during execution, these currently flow through McpStreamableServerSessionStream.sendNotification() (line 409), which sends to the per-request transport. In JSON mode, there's no SSE stream on that request to receive these.

Looking at how other SDKs handle this:

Go SDK (streamable.go L562-568) explicitly documents the approach:

"Notifications or requests made within the context of a server request will be sent to the standalone SSE stream, if any."

The Go SDK redirects intermediate messages to the GET SSE stream and buffers only the response in pendingJSONMessages (L775-791).

Python SDK (streamable_http.py L534-541) takes a simpler approach: in JSON mode, it iterates through the message stream, keeps only the JSONRPCResponse, and logs/skips intermediate notifications:

async for event_message in request_stream_reader:
    if isinstance(event_message.message, JSONRPCResponse | JSONRPCError):
        response_message = event_message.message
        break
    else:  # notifications - skipped
        logger.debug(f"received: {event_message.message.method}")

TypeScript SDK (streamableHttp.ts L972-981) follows the same pattern as Python: when enableJsonResponse is true, the SSE write path is guarded by if (!this._enableJsonResponse), meaning intermediate notifications are simply not delivered. Only the final JSONRPCResponse is collected and resolved as JSON (L994-1009).

Both are valid approaches depending on the architecture. In the Java SDK context, the Go-style approach (redirect to listeningStreamRef) might be achievable by constructing the exchange differently in responseStream() when JSON mode is enabled, but you all know the architecture much better than I do.

2. Symmetrical transport capabilities

I really like the idea of a stateless SSE upgrade. Currently the two modes are asymmetric:

	Streamable (stateful)	Stateless
SSE responses	always	never
JSON responses	never	always

With both opt-in options:

	Streamable (stateful)	Stateless
SSE responses	default (can opt into JSON)	opt-in
JSON responses	opt-in	default (can opt into SSE)

Both transport variants could share the same internal pattern: a ResponseMode (or a boolean flag in the builder) that determines the serialization format.

For you who know the implementation deeply: does this rationale make sense, or am I overlooking something?