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?

[chemicL]

@thiagomendes thank you for the summary. Can you paraphrase more succinctly what is your API proposal in pseudocode/public API signatures?

[thiagomendes]

@thiagomendes thank you for the summary. Can you paraphrase more succinctly what is your API proposal in pseudocode/public API signatures?

Sure! Here's the proposal distilled to public API and internal behavior:

Public API (no changes to handler/exchange)

// Streamable transport - add jsonResponse(boolean) to existing builder
HttpServletStreamableServerTransportProvider.builder()
    .jsonMapper(mapper)
    .mcpEndpoint("/mcp")
    .jsonResponse(true)        // NEW - opt-in, default false (preserves current SSE behavior)
    .build();

Handler code: zero changes. The handler API stays exactly as-is:

// McpRequestHandler<T> - UNCHANGED
Mono<T> handle(McpAsyncServerExchange exchange, Object params);

// McpAsyncServerExchange - UNCHANGED (no new methods, no branching)
// McpSyncServerExchange  - UNCHANGED

Internal behavior (in transport provider, transparent to handlers)

When jsonResponse is enabled, doPost() for JSONRPCRequest would reuse the existing reactive pipeline but collect the result instead of streaming SSE events:

// HttpServletStreamableServerTransportProvider.doPost() - pseudocode
if (message instanceof JSONRPCRequest jsonrpcRequest) {
    if (this.jsonResponse) {
        // Reuse existing reactive pipeline, collect single response as JSON
        response.setContentType(APPLICATION_JSON);
        McpSchema.JSONRPCResponse result = session.responseAsJson(jsonrpcRequest)
            .contextWrite(ctx -> ctx.put(McpTransportContext.KEY, transportContext))
            .block();
        writer.write(jsonMapper.writeValueAsString(result));
    } else {
        // Current SSE behavior (unchanged)
        response.setContentType(TEXT_EVENT_STREAM);
        AsyncContext asyncContext = request.startAsync();
        // ... existing SSE stream logic
    }
}

For intermediate notifications (progress/logging) during handler execution, I'd suggest starting with the simpler Python/TypeScript approach: skip them in JSON mode, since it's opt-in and the developer knowingly trades streaming capabilities for simplicity. The Go approach (redirect to standalone SSE stream) could be added later as an evolution if needed.

This could also symmetrically apply to the stateless transport in the future (opt-in SSE upgrade), but keeping the scope focused on the streamable transport for now.

[thiagomendes]

Adding a few sequence diagrams to help visualize the current vs proposed flow:

Current flow: SSE response (text/event-stream)

sequenceDiagram
    participant C as Client
    participant TP as TransportProvider<br/>(doPost)
    participant AC as AsyncContext
    participant ST as SessionTransport<br/>(SSE Writer)
    participant S as Session<br/>(responseStream)
    participant SS as SessionStream<br/>(per-request)
    participant E as Exchange
    participant H as Handler

    C->>TP: POST /mcp (JSONRPCRequest)
    TP->>TP: check jsonResponse flag
    Note over TP: jsonResponse = false (default)
    TP->>TP: setContentType(text/event-stream)
    TP->>AC: request.startAsync()
    TP->>ST: new SessionTransport(asyncContext, writer)
    TP->>S: responseStream(request, transport)
    S->>SS: new SessionStream(transport)
    S->>E: new Exchange(sessionId, stream, capabilities)
    S->>H: handler.handle(exchange, params)
    H-->>S: Mono<Result>
    S->>S: map(result → JSONRPCResponse)
    S->>ST: transport.sendMessage(response)
    ST->>ST: writeEvent("event: message\ndata: {json}\n\n")
    ST-->>C: SSE event (chunked transfer)
    S->>ST: transport.closeGracefully()
    ST->>AC: asyncContext.complete()

Loading

Proposed flow: JSON response (application/json)

sequenceDiagram
    participant C as Client
    participant TP as TransportProvider<br/>(doPost)
    participant S as Session<br/>(responseAsJson)
    participant E as Exchange
    participant H as Handler

    C->>TP: POST /mcp (JSONRPCRequest)
    TP->>TP: check jsonResponse flag
    Note over TP: jsonResponse = true (opt-in)
    TP->>TP: setContentType(application/json)

    rect rgba(128, 128, 128, 0.15)
    Note over TP,H: NEW: JSON response path (no AsyncContext, no SSE transport)
    TP->>S: responseAsJson(request)
    S->>S: wrap session with no-op notification handler
    S->>E: new Exchange(sessionId, noOpWrapper, capabilities)
    S->>H: handler.handle(exchange, params)
    H-->>S: Mono<Result>
    S->>S: map(result → JSONRPCResponse)
    S-->>TP: Mono<JSONRPCResponse>
    end

    TP->>TP: .block()
    TP->>TP: writer.write(jsonMapper.writeValueAsString(result))
    TP-->>C: HTTP 200, Content-Type: application/json<br/>{"jsonrpc":"2.0","id":"1","result":{...}}

Loading

Edge case: handler emits notifications in JSON mode

sequenceDiagram
    participant C as Client
    participant TP as TransportProvider<br/>(doPost)
    participant S as Session<br/>(responseAsJson)
    participant E as Exchange
    participant H as Handler

    C->>TP: POST /mcp (JSONRPCRequest)
    TP->>TP: check jsonResponse flag (true)
    TP->>TP: setContentType(application/json)
    TP->>S: responseAsJson(request)
    S->>S: wrap session with no-op notification handler
    S->>E: new Exchange(sessionId, noOpWrapper, capabilities)
    S->>H: handler.handle(exchange, params)

    rect rgba(128, 128, 128, 0.15)
    Note over H,E: Handler emits intermediate notification
    H->>E: exchange.progressNotification(...)
    E->>E: noOpWrapper.sendNotification(...)
    Note over E: Returns Mono.empty() - silently skipped<br/>(Python/TypeScript approach)
    end

    H-->>S: Mono<Result>
    S-->>TP: Mono<JSONRPCResponse>
    TP->>TP: .block()
    TP-->>C: HTTP 200, application/json

Loading

Key differences

Aspect	Current (SSE)	Proposed (JSON)
Content-Type	text/event-stream	application/json
AsyncContext	Required	Not needed
SSE SessionTransport	Created per-request	Not needed
SSE framing	event: message\ndata: ...\n\n	Direct JSON body
Transfer encoding	Chunked	Regular
Intermediate notifications	Delivered via SSE stream	Silently skipped
Handler code	Unchanged	Unchanged

[chemicL]

Thanks for clarifying.

My main concerns are:

• the out-of-band requests or notifications going to the generic listening stream are undesired; interactions related with a client request should be sent on the dedicated SSE stream
• ignoring notifications/requests is poor UX
• your follow-up uses public API that you did not document - responseAsJson

There might be more but you provide a lot of text, pretty certain that out of an LLM interaction and the investment on our part is best on actually implementing this with adherence to the design philosophy outlined in the .md files of this repo and the existing patterns - especially type safety, backwards-compatibility, etc. Please don't open a PR for this.

[thiagomendes]

@chemicL Thanks for the feedback.

[chemicL]

I didn't mean to close the issue, the request is absolutely valid. Just the actual solution must be one that is not surprising and uses APIs that clearly indicate to the user what is and what is not possible.