[Server] Add MCP stateless mode support

src/Server/Builder.php

@@ -223,6 +223,8 @@ final class Builder
 
     private bool $lazyLoading = true;
 
+    private bool $stateless = false;
+
     /**
      * Sets the server's identity. Required.
      *
@@ -725,7 +727,6 @@ public function build(): Server
             new Handler\Request\CallToolHandler($registry, $referenceHandler, $logger),
             new Handler\Request\CompletionCompleteHandler($registry, $container),
             new Handler\Request\GetPromptHandler($registry, $referenceHandler, $logger),
-            new Handler\Request\InitializeHandler($configuration),
             new Handler\Request\ListPromptsHandler($registry, $this->paginationLimit),
             new Handler\Request\ListResourcesHandler($registry, $this->paginationLimit),
             new Handler\Request\ListResourceTemplatesHandler($registry, $this->paginationLimit),
@@ -737,9 +738,14 @@ public function build(): Server
             new Handler\Request\SetLogLevelHandler(),
         ]);
 
-        $notificationHandlers = array_merge($this->notificationHandlers, [
-            new Handler\Notification\InitializedHandler(),
-        ]);
+        $notificationHandlers = array_merge($this->notificationHandlers, []);
+
+        if ($this->stateless) {
+            $requestHandlers[] = new Handler\Request\ServerDiscoverHandler($configuration);
+        } else {
+            array_unshift($requestHandlers, new Handler\Request\InitializeHandler($configuration));
+            $notificationHandlers[] = new Handler\Notification\InitializedHandler();
+        }
 
         $protocol = new Protocol(
             requestHandlers: $requestHandlers,
@@ -748,6 +754,7 @@ public function build(): Server
             sessionManager: $sessionManager,
             logger: $logger,
             eventDispatcher: $this->eventDispatcher,
+            stateless: $this->stateless,
         );
 
         return new Server($protocol, $logger);
@@ -806,4 +813,11 @@ private function createDiscoverer(LoggerInterface $logger): DiscovererInterface
 
         return $discoverer;
     }
+
+    public function setStateless(bool $stateless = true): self
+    {
+        $this->stateless = $stateless;
+
+        return $this;
+    }
 }

src/Server/Handler/Request/ServerDiscoverHandler.php

@@ -0,0 +1,58 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Server\Handler\Request;
+
+use Mcp\Schema\Implementation;
+use Mcp\Schema\JsonRpc\Request;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Result\InitializeResult;
+use Mcp\Schema\ServerCapabilities;
+use Mcp\Server\Configuration;
+use Mcp\Server\Session\SessionInterface;
+
+/**
+ * Handles server/discover for MCP 2026-07-28 stateless mode.
+ *
+ * Replaces initialize handshake — returns capabilities and serverInfo
+ * without creating a persistent session.
+ *
+ * @phpstan-ignore missingType.generics
+ */
+final class ServerDiscoverHandler implements RequestHandlerInterface
+{
+    public function __construct(
+        public readonly ?Configuration $configuration = null,
+    ) {
+    }
+
+    public function supports(Request $request): bool
+    {
+        return 'server/discover' === $request::getMethod();
+    }
+
+    /**
+     * @return Response<InitializeResult>
+     */
+    public function handle(Request $request, SessionInterface $session): Response
+    {
+        return new Response(
+            $request->getId(),
+            new InitializeResult(
+                $this->configuration->capabilities ?? new ServerCapabilities(),
+                $this->configuration->serverInfo ?? new Implementation(),
+                $this->configuration?->instructions,
+                null,
+                $this->configuration?->protocolVersion,
+            ),
+        );
+    }
+}

src/Server/Protocol.php

@@ -72,6 +72,7 @@ public function __construct(
         private readonly SessionManagerInterface $sessionManager,
         private readonly LoggerInterface $logger = new NullLogger(),
         private readonly ?EventDispatcherInterface $eventDispatcher = null,
+        private readonly bool $stateless = false,
     ) {
     }
 
@@ -122,9 +123,17 @@ public function processInput(TransportInterface $transport, string $input, ?Uuid
             return;
         }
 
-        $session = $this->resolveSession($transport, $sessionId, $messages);
-        if (null === $session) {
-            return;
+        if ($this->stateless) {
+            $session = $this->sessionManager->create();
+            $this->logger->debug('Created new ephemeral session for stateless request', [
+                'session_id' => $session->getId()->toRfc4122(),
+            ]);
+            $transport->setSessionId($session->getId());
+        } else {
+            $session = $this->resolveSession($transport, $sessionId, $messages);
+            if (null === $session) {
+                return;
+            }
         }
 
         foreach ($messages as $message) {