[Server] Fix lost responses on concurrent requests of the same session (Streamable HTTP)

[guillaume-sainthillier]

Fixes #275, fixes #467. Implements the approach discussed in #275 (comment), replacing the filtering of #508.

Symptom

On Streamable HTTP (handshake era, JSON responses), concurrent requests on one session lose responses. A POST answers 202 with an empty body instead of its JSON-RPC response, or answers with another request's response, sometimes inside an array. The client waits until it times out (TypeScript SDK: MCP error -32001: Request timed out). Parallel tool calls from LLM agents (n8n / LangChain) and Claude Code's concurrent tools/list and resources/list on connect run into it.

Reproduction

Any server with several workers and a shared session store. Initialize a session, then send N POSTs at once with the same Mcp-Session-Id. Measured with https://github.com/chr-hertel/mcp-concurrency-test (file store, loopback):

Server	Load	main	this PR
FrankenPHP worker mode	100 rounds × 10 tools/call	0 rounds correct; 328 foreign, 185 lost	100 rounds correct; 0 foreign, 0 lost
php -S, 8 workers	100 rounds × 10 tools/call	10 rounds correct; 159 foreign, 80 lost	100 rounds correct; 0 foreign, 0 lost
php -S, 8 workers	200 rounds × tools/list + resources/list	104 rounds correct; 58 foreign, 38 lost	200 rounds correct; 0 foreign, 0 lost

In production on FrankenPHP worker mode (mcp/sdk 0.8.1 through symfony/mcp-bundle), 1 call in 10 got a 202.

Root cause

A response was not returned by the POST that carried its request. It went through the session:

1. Protocol::sendResponse() queued it in _mcp.outgoing_queue (Protocol.php#L476-L482, #L503-L508) in the session data loaded at the start of the request.
2. doProcessInput() saved that whole session back (#L223).
3. createJsonResponse() reloaded the session and took the whole queue (StreamableHttpTransport.php#L224-L234, Protocol.php#L516-L524).

With two requests A and B on one session:

• If both load the session before either saves, the second save overwrites the first one's queued response. That response is gone (a lost update), and its POST answers 202.
• If B saves after A, whichever consumes first takes both responses, and the other POST answers 202.

Filtering the queue by request id (#508) fixes the second case but not the first.

Fix

• StreamableHttpTransport implements a new marker interface, InlineResponseTransportInterface. For such a transport, Protocol::sendResponse() hands every response to TransportInterface::send(), with the session id in the session_id context key, instead of queueing it. This is the path session-less errors already took.
• The transport collects these responses and answers the POST with them: one object, or an array for a batch, as before. Responses no longer go through the session store, so no interleaving can lose them.
• When a request in a batch suspends (SSE), the other requests' responses are written first in the stream.
• The session queue still carries server-initiated requests and notifications: fiber yields on SSE streams, and resource-updated notifications. A JSON POST still drains it as before, so notifications are delivered as they were.
• consumeOutgoingMessages() only saves when it took something. Saving an unchanged session on every POST could only overwrite what a concurrent request had saved in the meantime. The same save ran on every poll of an SSE stream waiting for a client's answer (sampling, elicitation, roots), and could overwrite that answer when another worker stored it: the rare hangs seen in the multi-worker client tests ([Server] Stop overwriting client responses while polling for them #545, closed in favor of this PR).

Tests

• StreamableHttpTransportTest::testConcurrentPostsOfOneSessionEachGetTheirOwnResponse runs two tools/call POSTs through real Server and StreamableHttpTransport instances that share one store. The fixture InterleavingSessionStore runs B from inside A's session save, so the interleaving is deterministic and needs no real concurrency. There are two cases:

  • B runs between A's save and A's response;
  • B loaded the session before A saved it (the lost update).

  Each POST must answer 200 with its own id and the session header. Both cases fail on main, where A answers 202.

• testStreamedBatchCarriesInlineResponses: a batch whose tool call suspends to send progress still streams the ping response.

• ProtocolSessionRaceTest, ported from [Server] Stop overwriting client responses while polling for them #545: a client's answer stored by one worker while another polls the session for it is not overwritten. It fails without the consumeOutgoingMessages() change.

• Unit and integration suites pass, PHPStan (level 8) and php-cs-fixer are clean.

Backward compatibility

• The new behavior only applies to transports that implement InlineResponseTransportInterface. StdioTransport, InMemoryTransport and custom transports keep the queue. Stdio would work unchanged on the inline path too; making it the default for every transport could be a follow-up.
• StreamableHttpTransport: no signature changes. createJsonResponse() and createStreamedResponse() keep their protected signatures.
• Protocol::consumeOutgoingMessages() returns the same thing. It just skips a save that would not change anything.

Not in this PR

• Other session keys written by concurrent requests can still be lost when both requests actually change the session: pending requests, client responses, client info. Fixing that needs per-session serialization, e.g. an opt-in lock around load → handle → save (flock for FileSessionStore, symfony/lock for the PSR-16 store). symfony/mcp-bundle would then need an option to wire it. Happy to follow up if that direction suits you.
• Until now, applications worked around this with a per-session lock around the whole request, e.g. a decorator of symfony/mcp-bundle's mcp.server.<name>.controller wrapping handle() in symfony/lock's LockFactory::createLock('mcp-session-'.$sessionId). With this PR, that lock is no longer needed for responses.

[chr-hertel]

nevermind changelog conflicts. they will happen all the time, and i can easily solve them while merging. just put the PR to ready for review when you think you're done :)

[Copilot]

🟢 Approval recommended

The response race is addressed without changing other transports, with focused deterministic coverage for both interleavings.

0 open findings

What changed in this PR

Moves Streamable HTTP responses out of shared session queues, preventing concurrent requests from losing or consuming each other’s responses.

Changes:

• Adds inline-response transport behavior and protocol routing.
• Preserves queued notifications and SSE delivery.
• Adds deterministic concurrency and streamed-batch tests.

File	Description
CHANGELOG.md	Documents the concurrency fix.
src/​Server/​Protocol.php	Sends eligible responses inline and avoids unnecessary saves.
src/​Server/​Transport/​InlineResponseTransportInterface.php	Defines inline-response transport capability.
src/​Server/​Transport/​StreamableHttpTransport.php	Collects inline responses for JSON and SSE output.
tests/​Unit/​Server/​Transport/​Fixture/​InterleavingSessionStore.php	Simulates deterministic concurrent session writes.
tests/​Unit/​Server/​Transport/​StreamableHttpTransportTest.php	Tests concurrent POSTs and streamed batches.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chr-hertel]

@guillaume-sainthillier Please rebase and have a look if the test added in PR #545 is valuable to add here - thanks already!

[guillaume-sainthillier]

Rebased on main and added the test from #545, adapted to share the store fixture.