[Server] Close the conformance gaps in the modern lifecycle (#447)

* [Server] Let the client gateway see modern-era capabilities

The six supports*() probes read session state only InitializeHandler wrote,
so every request served statelessly reported no client capabilities at all —
a tool guarding on them took the unsupported branch without a signal.
StatelessProtocol now writes the request's declaration under the same keys.

* [Server] Reject the RPCs 2026-07-28 removed

resources/subscribe and resources/unsubscribe were still dispatched and
answered 200 OK, recording subscriptions the modern era never reads. They
join initialize, ping and logging/setLevel in the era guard; the handlers
stay registered because the handshake era still serves them.

* [Server] Decode a wrapped Mcp-Name before comparing it

The Base64 sentinel was only unwrapped for Mcp-Param-*, so any resource URI
or tool name outside the header-safe ASCII set — which the spec explicitly
tells clients to wrap — was compared encoded and refused with -32020.

* [Server] Require the MCP-Protocol-Version header

It was only checked for contradicting the body, so omitting it entirely
passed — leaving the value intermediaries route on unenforced. Tied to the
header validator's presence, since that is what a header-bearing transport
installs and stdio carries its metadata inline.

* [Server] Read the modern-era request body whole

A single read() takes whatever the stream cares to give — 64 bytes from a
chunked transfer is legal — so an oversized-but-valid POST came back as a
parse error. Shares the legacy transport's incremental read as a trait.

* [Schema][Server] Answer a notification with a status, not a response

A body with no id was dispatched as a request and came back as a JSON-RPC
error carrying "id": "" — an id nobody issued, and on a path a client uses
to tell a modern server from a legacy one. Notifications now get 202 and no
body, and Error omits an id it could not read instead of emptying it.

* [Server] Stop emitting the error codes 2026-07-28 reserved

resources/read answered -32002, which this revision forbids; prompts/get
and completion/complete answered it for an unknown *name*, which it never
meant; tools/call answered -32601, which belongs to an unknown method.
Only the resources/read code is revision-gated — older peers expect -32002
there, and nowhere else. Also routes the -32021 capability exception out of
the prompt and resource handlers, which were swallowing it into -32603.

src/Server/Handler/Request/CallToolHandler.php

@@ -73,7 +73,9 @@ final class CallToolHandler implements RequestHandlerInterface
         } catch (ToolNotFoundException $e) {
             $this->logger->error('Tool not found', ['name' => $toolName, 'exception' => $e]);
 
-            return new Error($request->getId(), Error::METHOD_NOT_FOUND, $e->getMessage());
+            // -32601 answers an unknown *method*; tools/call exists, it is the
+            // name in its params that does not.
+            return Error::forInvalidParams($e->getMessage(), $request->getId());
         }
 
         $inputSchema = $reference->tool->inputSchema;

src/Server/Handler/Request/CompletionCompleteHandler.php

@@ -85,7 +85,9 @@ final class CompletionCompleteHandler implements RequestHandlerInterface
 
             return new Response($request->getId(), new CompletionCompleteResult($paged, $total, $hasMore));
         } catch (PromptNotFoundException|ResourceNotFoundException $e) {
-            return Error::forResourceNotFound($e->getMessage(), $request->getId());
+            // The reference names something the server does not have, which is
+            // a bad parameter rather than a missing resource.
+            return Error::forInvalidParams($e->getMessage(), $request->getId());
         } catch (\Throwable $e) {
             return Error::forInternalError('Error while handling completion request', $request->getId());
         }

src/Server/Handler/Request/GetPromptHandler.php

@@ -13,6 +13,7 @@ namespace Mcp\Server\Handler\Request;
 
 use Mcp\Capability\Registry\ReferenceHandlerInterface;
 use Mcp\Capability\RegistryInterface;
+use Mcp\Exception\MissingRequiredClientCapabilityException;
 use Mcp\Exception\PromptGetException;
 use Mcp\Exception\PromptNotFoundException;
 use Mcp\Schema\JsonRpc\Error;
@@ -70,6 +71,10 @@ final class GetPromptHandler implements RequestHandlerInterface
             $formatted = $reference->formatResult($result);
 
             return new Response($request->getId(), new GetPromptResult($formatted));
+        } catch (MissingRequiredClientCapabilityException $e) {
+            // Not a handler failure — the request was unservable, and the client
+            // needs to retry declaring the capability. Rendered as -32021.
+            throw $e;
         } catch (PromptGetException $e) {
             $this->logger->error(\sprintf('Error while handling prompt "%s": "%s".', $promptName, $e->getMessage()), ['exception' => $e]);
 
@@ -77,7 +82,9 @@ final class GetPromptHandler implements RequestHandlerInterface
         } catch (PromptNotFoundException $e) {
             $this->logger->error('Prompt not found', ['prompt_name' => $promptName, 'exception' => $e]);
 
-            return Error::forResourceNotFound($e->getMessage(), $request->getId());
+            // An unknown prompt name is a bad parameter, not a missing
+            // resource: -32002 was never the code for this.
+            return Error::forInvalidParams($e->getMessage(), $request->getId());
         } catch (\Throwable $e) {
             $this->logger->error(\sprintf('Unexpected error while handling prompt "%s": "%s".', $promptName, $e->getMessage()), ['exception' => $e]);
 

src/Server/Handler/Request/ReadResourceHandler.php

@@ -14,6 +14,7 @@ namespace Mcp\Server\Handler\Request;
 use Mcp\Capability\Registry\ReferenceHandlerInterface;
 use Mcp\Capability\Registry\ResourceTemplateReference;
 use Mcp\Capability\RegistryInterface;
+use Mcp\Exception\MissingRequiredClientCapabilityException;
 use Mcp\Exception\ResourceNotFoundException;
 use Mcp\Exception\ResourceReadException;
 use Mcp\Schema\JsonRpc\Error;
@@ -21,6 +22,7 @@ use Mcp\Schema\JsonRpc\Request;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\ReadResourceRequest;
 use Mcp\Schema\Result\ReadResourceResult;
+use Mcp\Server\RequestContext;
 use Mcp\Server\Session\SessionInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
@@ -76,6 +78,10 @@ final class ReadResourceHandler implements RequestHandlerInterface
             }
 
             return new Response($request->getId(), new ReadResourceResult($formatted));
+        } catch (MissingRequiredClientCapabilityException $e) {
+            // Not a handler failure — the request was unservable, and the client
+            // needs to retry declaring the capability. Rendered as -32021.
+            throw $e;
         } catch (ResourceReadException $e) {
             $this->logger->error(\sprintf('Error while reading resource "%s": "%s".', $uri, $e->getMessage()), ['exception' => $e]);
 
@@ -83,7 +89,12 @@ final class ReadResourceHandler implements RequestHandlerInterface
         } catch (ResourceNotFoundException $e) {
             $this->logger->error('Resource not found', ['uri' => $uri, 'exception' => $e]);
 
-            return Error::forResourceNotFound($e->getMessage(), $request->getId());
+            // SEP-2164 retired -32002 in favour of the JSON-RPC code that
+            // already meant this. Older peers still expect the old one, so the
+            // revision answering the request decides.
+            return (new RequestContext($session, $request))->getProtocolVersion()->usesInvalidParamsForResourceNotFound()
+                ? Error::forInvalidParams($e->getMessage(), $request->getId(), ['uri' => $uri])
+                : Error::forResourceNotFound($e->getMessage(), $request->getId());
         } catch (\Throwable $e) {
             $this->logger->error(\sprintf('Unexpected error while reading resource "%s": "%s".', $uri, $e->getMessage()), ['exception' => $e]);