[Server] Serve an extension's methods under the modern lifecycle

The modern dispatcher takes the method-to-extension map the builder collects,
so a method belonging to an extension this server does not serve is answered
-32601 naming the extension instead of a bare "no handler found". It is still
an unknown method - the server genuinely does not implement it - but the
caller can now act on the answer.

Author: chr-hertel

src/Server/Builder.php

@@ -236,6 +236,9 @@ final class Builder
     /** @var list<class-string<\Mcp\Schema\JsonRpc\Request>|class-string<\Mcp\Schema\JsonRpc\Notification>> */
     private array $extensionMessages = [];
 
+    /** @var array<string, string> RPC method to the extension identifier defining it */
+    private array $extensionMethods = [];
+
     /**
      * @var LoaderInterface[]
      */
@@ -406,6 +409,9 @@ public function enableExtension(ExtensionInterface ...$extensions): self
             // downstream ever sees it.
             foreach ($extension->getMessages() as $message) {
                 $this->extensionMessages[] = $message;
+                // Recorded even though the handler answers it, so a server with
+                // the extension *off* can say so instead of "no such method".
+                $this->extensionMethods[$message::getMethod()] = $id;
             }
 
             foreach ($extension->getRequestHandlers() as $handler) {
@@ -836,6 +842,7 @@ public function buildStateless(array $supportedVersions = [ProtocolVersion::V202
                 : null,
             cachePolicy: $this->cachePolicy,
             notificationBus: $this->notificationBus,
+            extensionMethods: $this->extensionMethods,
         );
     }
 

src/Server/Stateless/StatelessProtocol.php

@@ -89,6 +89,7 @@ final class StatelessProtocol
     /**
      * @param iterable<RequestHandlerInterface<ResultInterface>> $requestHandlers
      * @param list<ProtocolVersion>                              $supportedVersions
+     * @param array<string, string>                              $extensionMethods  RPC method to the extension identifier defining it
      */
     public function __construct(
         private readonly iterable $requestHandlers,
@@ -102,6 +103,7 @@ public function __construct(
         private readonly ?RequestStateCodec $requestStateCodec = null,
         ?CachePolicy $cachePolicy = null,
         private readonly ?NotificationBusInterface $notificationBus = null,
+        private readonly array $extensionMethods = [],
     ) {
         $this->codec = $codec ?? new Rev2026Codec($configuration->serverInfo, $cachePolicy);
 
@@ -396,7 +398,7 @@ private function dispatch(string $method, array $decoded, RequestMeta $meta, str
         } catch (\Throwable $e) {
             $this->logger->warning('Rejected an unparseable modern-era request.', ['method' => $method, 'exception' => $e]);
 
-            return StatelessResult::error(Error::forMethodNotFound(\sprintf('Method "%s" is not supported.', $method), $id), 404);
+            return StatelessResult::error($this->unknownMethod($method, $id), 404);
         }
 
         $request = $messages[0] ?? null;
@@ -410,7 +412,7 @@ private function dispatch(string $method, array $decoded, RequestMeta $meta, str
 
             return StatelessResult::error(
                 $unknownMethod
-                    ? Error::forMethodNotFound($request->getMessage(), $id)
+                    ? $this->unknownMethod($method, $id)
                     : Error::forInvalidRequest($request->getMessage(), $id),
                 $unknownMethod ? 404 : 400,
             );
@@ -510,7 +512,28 @@ private function dispatch(string $method, array $decoded, RequestMeta $meta, str
             return $this->encode($method, $id, $result->result, null === $input);
         }
 
-        return StatelessResult::error(Error::forMethodNotFound(\sprintf('No handler found for method "%s".', $method), $id), 404);
+        return StatelessResult::error($this->unknownMethod($method, $id), 404);
+    }
+
+    /**
+     * A method with no handler, said as precisely as the server can.
+     *
+     * An extension's method is still `-32601` when the extension is off — the
+     * server genuinely does not implement it — but naming the extension turns
+     * an opaque refusal into something the caller can act on.
+     */
+    private function unknownMethod(string $method, string|int $id): Error
+    {
+        $extension = $this->extensionMethods[$method] ?? null;
+
+        if (null !== $extension) {
+            return Error::forMethodNotFound(
+                \sprintf('Method "%s" belongs to the "%s" extension, which this server does not serve.', $method, $extension),
+                $id,
+            );
+        }
+
+        return Error::forMethodNotFound(\sprintf('No handler found for method "%s".', $method), $id);
     }
 
     /**

tests/Unit/Server/Stateless/StatelessProtocolTest.php

@@ -34,6 +34,7 @@
 use Mcp\Server\Stateless\StatelessResult;
 use Mcp\Server\Subscription\InMemoryNotificationBus;
 use Mcp\Server\Wire\CachePolicy;
+use Mcp\Tests\Unit\Server\Extension\ThingExtension;
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\TestDox;
 use PHPUnit\Framework\TestCase;
@@ -791,6 +792,55 @@ public function testAcknowledgmentReflectsWhatTheServerCanDo(): void
         $this->assertSame(['toolsListChanged' => true], (array) $first['params']['notifications']);
     }
 
+    #[TestDox('an extension method is served by the extension that claims it')]
+    public function testExtensionMethodIsServed(): void
+    {
+        $protocol = Server::builder()
+            ->setServerInfo('test-server', '1.0.0')
+            ->enableExtension(new ThingExtension())
+            ->buildStateless([ProtocolVersion::V2026_07_28]);
+
+        $answer = self::callWithHeaders($protocol, 'com.example/things.list', [], [
+            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
+            'Mcp-Method' => 'com.example/things.list',
+        ]);
+
+        $this->assertSame(200, $answer['status']);
+        $this->assertSame(['a', 'b'], $answer['body']['result']['things']);
+    }
+
+    #[TestDox('the extension is advertised under capabilities.extensions')]
+    public function testExtensionIsAdvertised(): void
+    {
+        $protocol = Server::builder()
+            ->setServerInfo('test-server', '1.0.0')
+            ->enableExtension(new ThingExtension())
+            ->buildStateless([ProtocolVersion::V2026_07_28]);
+
+        $answer = self::call($protocol, 'server/discover');
+
+        $this->assertSame(['flavour' => 'vanilla'], (array) $answer['body']['result']['capabilities']['extensions']['com.example/things']);
+    }
+
+    #[TestDox('a method of an extension this server does not serve says so by name')]
+    public function testDisabledExtensionMethodNamesItsExtension(): void
+    {
+        $protocol = Server::builder()
+            ->setServerInfo('test-server', '1.0.0')
+            ->buildStateless([ProtocolVersion::V2026_07_28]);
+
+        $answer = self::callWithHeaders($protocol, 'com.example/things.list', [], [
+            'MCP-Protocol-Version' => ProtocolVersion::V2026_07_28->value,
+            'Mcp-Method' => 'com.example/things.list',
+        ]);
+
+        $this->assertSame(404, $answer['status']);
+        $this->assertSame(Error::METHOD_NOT_FOUND, $answer['body']['error']['code']);
+        // Without the extension enabled there is nothing to name it by.
+        $this->assertStringContainsString('com.example/things.list', $answer['body']['error']['message']);
+        $this->assertStringNotContainsString('extension', $answer['body']['error']['message']);
+    }
+
     #[TestDox('a notification is acknowledged with no body, never answered')]
     public function testNotificationIsAcknowledged(): void
     {