[Server] (Re-)Implement Streamable Transport

[chr-hertel]

The original php-mcp/server component already had a Streamable Transport, using Evenement and ReactPHP though.

Goal of this issue is to bring in a new Streamable Transport implementation, that is compatible with this SDK's architecture.

---

Please announce yourself before working on this - so we can avoid duplicate effort.

[Adebayo120]

Hi Christopher, I’m Adam .. I’ll like to be assigned this issue. I’ll come back with my findings and questions if I’ve got any

[CodeWithKyrian]

So I’ve been thinking a lot about this, especially coming from my work on [php-mcp/server](https://github.com/php-mcp/server/blob/main/src/Transports/StreamableHttpServerTransport.php), and wanted to share some thoughts that might help guide how we approach this.

My old transport was built to be the server: a long-running ReactPHP process that handled its own routing (similar to how StdioTransport is self-contained). That worked with the Server::connect() since this starts the HTTP server and is super easy to use for the end user, just like the STDIO transport.

But it's an opinionated implementation so we're moving away from that. Now, the vast majority of PHP applications operate on a request/response model (e.g., Nginx + PHP-FPM), where a script initializes, handles a single request, and then terminates. Sure, long-running servers exist (Octane, RoadRunner, Swoole, FrankenPHP), but they aren't the norm. In that world, the SDK’s current Server::connect() loop actually feels very natural for single-request lifecycles.

The tricky part has to do with the spec's requirements for Streamable Http Transport. It works best with a long-running, stateful server (persistent GET streams, sessions, etc). That’s normal in Python/TS because:

• The Python SDK (fastmcp) is built on Starlette and runs as a persistent, asynchronous server with uvicorn.
• Typescript SDK provides handlers meant to plug into a Node HTTP server and can hold SSE connections.

Both solutions rely on an event-driven long-running process, but that model doesn’t translate cleanly to PHP-FPM. To avoid async, we’d need some kind of message store/queue to carry state across requests (which we already lean on a bit).

So I think we need to align on three areas:

1. Routing + Framework Integration (biggest question)

There’s no single way to serve HTTP in PHP. Forcing one setup would be restrictive.
So do we:

• Ship an opinionated built-in server with its own router (like I did before)?
• Or just provide clean integration points so people wire MCP into whatever framework/router they’re using?

I lean strongly to the second. A Laravel dev can do Route::any('/mcp', ...), etc. The transport isn’t “running the show” — it’s just a service their app calls.

Question: If we go this route, what should that API look like? Maybe something like $transport->handlePostRequest($request) and $transport->handleGetStream($request) that controllers call (where the request is a PSR-7 ServerRequestInterface instance? And where does Server::connect() fit into this lifecycle?

2. Session Management

Spec says sessions are managed via Mcp-Session-Id. But PHP apps are stateless across requests, so we can’t hold it in memory. It has to be loaded/saved from storage (cache, DB, etc).

Question: Do we make users handle that boilerplate around $server->connect() themselves? Or should our transport abstract it (e.g. accept a PSR cache/session handler)? I handled it a certain way in the server package, do we bring that over?

3. Streams + Long-lived GETs

This is the hardest mismatch with PHP-FPM. A GET request that opens an SSE stream basically needs a process that stays alive and pushes events later. Doing that in a typical synchronous PHP server locks up the current process till the stream is done. (The spec talks about two streams...the persistent GET stream, and the optional POST stream)

On long-running servers (Octane, ReactPHP, Swoole), it's not an issue at all.

Question: What;s the best way to handle this cleanly that works for both synchronous and asynchronous servers (Assuming we chose not to ship an opinionated built in server)?

Given all this, my proposal:

We start with a simple, stateless request/response HTTP transport that plays nicely with PSR-7 requests. That gives us a solid baseline most PHP apps can actually use. Then we can figure out how to layer in the more advanced stuff (sessions, streams, long-running support) as we go.

Curious what you all think @chr-hertel @Nyholm.

[marcod85]

I'd like to add one issue I had with the php-mcp approach here, which might influence the further implementation:

Due to the ReactPHP loop being used, any tools/call execution blocked the whole execution process.
I started last week on trying to refactor return types to Promises, so I could facilitate a React\Http\Client in my tool implementation.
This would decouple the wait for the SDK/API response from the loop, and only once it resolves, the tool's response content will be handled further to a message resp. stdio output/HTTP response/SSE event.

[SamMousa]

If we go this route, what should that API look like?

Psr15 specifies an interface for request handlers. That feels cleaner to me than to do partial routing using controllers. This happens at the router level.

Spec says sessions are managed via Mcp-Session-Id. But PHP apps are stateless across requests, so we can’t hold it in memory. It has to be loaded/saved from storage (cache, DB, etc).

We could use psr16 (simple cache), given the way the server is allowed to terminate sessions at will according to the spec, this fits quite well with cache TTL etc.

[chr-hertel]

Done by @CodeWithKyrian - thanks & closed! :)