[Server] Serve handshake-era clients without sessions by ruudk · Pull Request #645 · modelcontextprotocol/php-sdk

ruudk · 2026-10-31T13:00:12Z

Closes #644.

A session is optional in the handshake era: a server "MAY assign a session ID at initialization time". The SDK always creates one on initialize and refuses every later request without it, so a horizontally scaled server has to share a session store and lock only to serve handshake-era clients.

Sessions over Streamable HTTP are now only turned on by Builder::setSession(). Without it:

initialize is answered without Mcp-Session-Id, and a session id the client sends anyway is ignored;
every request runs on an EphemeralSession that is never stored, with the protocol version taken from the MCP-Protocol-Version header;
GET and DELETE are answered with 405, which the spec allows for a server without a stream and for one that does not let clients end sessions.

What needs a session fails loud: requests to the client (elicitation, sampling, roots/list), the supports*() client capability checks, messages sent outside a request and saving the session throw a LogicException; input-required results, resources/subscribe/unsubscribe and logging/setLevel are answered with -32603, and the subscribe resource capability is not advertised. Progress and other notifications sent during a request still reach the client. The TypeScript SDK serves handshake-era traffic the same way with sessionIdGenerator: undefined.

This is a BC break for HTTP servers that relied on the in-memory fallback session, which was lost between requests under PHP-FPM or php -S anyway; they keep sessions with setSession(new InMemorySessionStore()). stdio and the 2026-07-28 era are not affected.

Copilot

🟡 Changes recommended

Sessionless requests can leave persisted ephemeral sessions unreachable until expiry and expose the wrong protocol version to handlers.

2 open issues

What changed in this PR

Adds opt-in sessionless handling for handshake-era Streamable HTTP clients, allowing horizontally scaled servers to serve them without shared session storage.

Changes:

Adds Builder::withoutSessions() and request-local session handling, while preserving default behavior.
Omits session headers, rejects GET and DELETE, and fails client-directed requests immediately.
Documents the trade-offs and adds unit and integration coverage.

File	Description
`tests/Unit/Server/Transport/SessionlessHttpTest.php`	Tests sessionless HTTP requests, streaming, and client-request rejection.
`tests/Unit/Server/ProtocolTest.php`	Checks that other transports retain session requirements.
`tests/Integration/SessionlessHttpTest.php`	Tests sessionless client communication over HTTP.
`tests/Integration/Fixture/http.php`	Enables sessionless mode in the shared fixture.
`src/Server/Transport/StreamableHttpTransport.php`	Suppresses session headers and rejects unsupported methods.
`src/Server/Protocol.php`	Adds ephemeral sessions and client-request guards.
`src/Server/Builder.php`	Exposes and wires `withoutSessions()`.
`docs/run/sessions.md`	Explains sessionless configuration and limitations.
`docs/run/server-builder.md`	Lists the new builder option.
`CHANGELOG.md`	Records sessionless HTTP support.

_{Review effort: Balanced}

chr-hertel · 2026-11-03T00:08:05Z

Hi @ruudk, on the one hand i'm a bit scared about some side-effects here, but i think this is worth going into, so thanks for bringing this up.

Some thoughts:

at first i thought "we should call it disableSession()
session usually is configured explicitly anyways
session is deprecated
and we are pre v1.0

should we maybe remove the fallback session mechanism and session only gets activated is setSession() is called? so even disableSession() would not be needed

cc @soyuka opinion on that call?

one layer of rework is missing tho: a lot of feature don't work without session in handshake era and would need error handling (fail loud):

Elicitation (elicit(), elicitUrl())
Sampling (sample())
Roots (listRoots())
InputRequiredResult on the handshake leg
Resource subscriptions
Log level (logging/setLevel)
Queued messages (Protocol::sendRequest(), sendNotification())
Client capability checks (supportsElicitation() etc.)
Negotiated protocol version (RequestContext::getProtocolVersion())
Handler data kept between requests ($context->getSession()->set(...))

We'd need some tests around that as well 🙏

ruudk · 2026-11-04T08:43:34Z

Went with your proposal: withoutSessions() is gone, and sessions over HTTP are only active once setSession() is called (stdio keeps its in-memory one). Everything on your list now fails loud, with tests in SessionlessHttpTest: requests to the client and the supports*() checks throw a LogicException, input-required results, subscriptions and logging/setLevel get -32603, and the protocol version comes from the header.

ruudk · 2026-11-04T09:16:59Z

@chr-hertel could you take another look?

soyuka · 2026-11-06T10:32:13Z

+    {
+        return json_decode((string) $response->getBody(), true, flags: \JSON_THROW_ON_ERROR);
+    }
+}


not sure we need that many tests

_{🤖 Ruud's Claude here}

Trimmed the duplicates: the supports*() checks share one code path and are covered by a single test now, and the raw-wire integration test is gone, as the unit tests cover the same responses.

soyuka · 2026-11-06T10:32:29Z

+ *
+ * It lives as long as its request and is never stored, so it cannot be saved.
+ */
+final class EphemeralSession extends Session


either remove final or create an interface ?

_{🤖 Ruud's Claude here}

Added EphemeralSessionInterface, which EphemeralSession implements and every check uses, so the class stays final.

soyuka · 2026-11-06T10:32:46Z

        $capabilities = ($this->configuration->capabilities ?? new ServerCapabilities())->withoutListChanged();

+        // Updates of a subscribed resource reach the client outside a request, which needs a session.
+        if ($session instanceof EphemeralSession) {


i dislike that its a class i'd prefer an interface here

_{🤖 Ruud's Claude here}

It checks against EphemeralSessionInterface now, like the other places.

soyuka · 2026-11-06T10:33:47Z

+progress and log messages, still reach the client on that request's stream. Servers that need the rest call
+`setSession()`.
+
+The modern (`2026-07-28`) era has no sessions to begin with and is not affected, and neither is stdio, where the


indeed maybe this feature could even help us with migrating pre-(2026-07-28) servers. +1 to add this

Copilot

🟡 Changes recommended

The first request suspension is still registered and streamed for ephemeral sessions, producing client requests whose replies cannot be correlated.

1 open issue

Reject initial RequestSuspension in ephemeral sessions before registration · New

2 resolved since last review

_{Review effort: Balanced}

chr-hertel · 2026-11-08T17:01:15Z

Thanks @ruudk - took this over to get it moving: rebased on main and patched the rest on top. Handlers now get a SessionRequiredException whose message reaches the client, supports*() return false so fallbacks keep working, and logging is no longer offered without sessions, since logging/setLevel cannot work there. Also refuses a first request suspension (Copilot was right on that one) and updates the docs.

A session is optional in the handshake era, but the SDK always created one on initialize and refused every later request without it. So a horizontally scaled server had to share a session store and lock only to serve those clients, and the in-memory fallback was lost between requests under PHP-FPM anyway. Sessions over Streamable HTTP are now turned on by Builder::setSession() only. Without it, initialize is answered without an Mcp-Session-Id, every later request runs on an EphemeralSession that is never stored, and GET and DELETE are answered with 405. What needs a session fails loud: requests to the client, the client capability checks, queued messages and saving the session throw a LogicException; input-required results, resource subscriptions and logging/setLevel are answered with -32603. The protocol version comes from the MCP-Protocol-Version header. Stdio and the 2026-07-28 era are not affected.

An uncaught LogicException from elicit() and the like reached the client as "Error while executing tool", with the hint only in the log.

Only later suspensions were refused, so a handler suspending on a request itself sent the client a request whose answer could not be matched.

Throwing turned the documented fallback of a handler into an error, although that fallback works: the client cannot be asked, and what it declared is not known.

logging/setLevel always failed while logging stayed advertised, which can fail the connect of clients that set a level on it, and the level stayed at warning.

ruudk · 2026-11-08T17:04:22Z

Thank you!

Copilot

🟢 Approval recommended

No active review issues are reported for the sessionless HTTP changes.

No open issues 🎉

1 resolved since last review

Reject initial RequestSuspension in ephemeral sessions before registration

_{Review effort: Balanced}

chr-hertel

Thanks @ruudk - let's hope for little regressions 🤞

ruudk requested review from CodeWithKyrian, Nyholm, chr-hertel and soyuka as code owners October 31, 2026 13:00

chr-hertel requested a balanced review from Copilot November 2, 2026 20:39

Copilot started reviewing on behalf of chr-hertel November 2, 2026 20:40

View session

Copilot AI reviewed Nov 2, 2026

View reviewed changes

Comment thread src/Server/Protocol.php Resolved

Comment thread src/Server/Protocol.php Resolved

chr-hertel added the Server Issues & PRs related to the Server component label Nov 3, 2026

ruudk force-pushed the sessionless-handshake-era branch from 6fe6535 to bca19b6 Compare November 4, 2026 08:42

ruudk force-pushed the sessionless-handshake-era branch from bca19b6 to 1478479 Compare November 4, 2026 08:46

chr-hertel added the breaking change Breaking the Backwards Compatibility Promise label Nov 4, 2026

chr-hertel added this to the 0.10.0 milestone Nov 4, 2026

soyuka reviewed Nov 6, 2026

View reviewed changes

ruudk force-pushed the sessionless-handshake-era branch from 1478479 to 42a953f Compare November 6, 2026 10:50

ruudk requested a review from soyuka November 6, 2026 13:10

chr-hertel requested a balanced review from Copilot November 8, 2026 15:59

Copilot started reviewing on behalf of chr-hertel November 8, 2026 16:00

View session

Copilot AI reviewed Nov 8, 2026

View reviewed changes

Comment thread src/Server/Protocol.php Resolved

chr-hertel force-pushed the sessionless-handshake-era branch from 42a953f to e247750 Compare November 8, 2026 17:01

chr-hertel requested a balanced review from Copilot November 8, 2026 17:01

Copilot started reviewing on behalf of chr-hertel November 8, 2026 17:02

View session

ruudk and others added 2 commits November 8, 2026 18:02

[Server] Tell the client when a handler needs a session

873e8ed

An uncaught LogicException from elicit() and the like reached the client as "Error while executing tool", with the hint only in the log.

chr-hertel added 4 commits November 8, 2026 18:02

[Server] Refuse a first request suspension on a server without sessions

dc5ccaf

Only later suspensions were refused, so a handler suspending on a request itself sent the client a request whose answer could not be matched.

[Server] Answer false from client capability checks without a session

a1f28c2

Throwing turned the documented fallback of a handler into an error, although that fallback works: the client cannot be asked, and what it declared is not known.

[Server] Do not offer logging without sessions

c0f773f

logging/setLevel always failed while logging stayed advertised, which can fail the connect of clients that set a level on it, and the level stayed at warning.

[Server] Document what a server without sessions offers

e1c5a9f

chr-hertel force-pushed the sessionless-handshake-era branch from e247750 to e1c5a9f Compare November 8, 2026 17:03

Copilot AI reviewed Nov 8, 2026

View reviewed changes

chr-hertel approved these changes Nov 8, 2026

View reviewed changes

chr-hertel merged commit 8430e9c into modelcontextprotocol:main Nov 8, 2026
31 checks passed

Conversation

ruudk commented Oct 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

chr-hertel commented Nov 3, 2026

Uh oh!

ruudk commented Nov 4, 2026

Uh oh!

ruudk commented Nov 4, 2026

Uh oh!

soyuka Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

ruudk Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

soyuka Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

ruudk Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

soyuka Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

ruudk Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

soyuka Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

chr-hertel commented Nov 8, 2026

Uh oh!

ruudk commented Nov 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

chr-hertel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ruudk commented Oct 31, 2026 •

edited

Loading