[Client] Default to protocol version 2026-07-28

Author: chr-hertel

CHANGELOG.md

@@ -28,6 +28,7 @@ All notable changes to `mcp/sdk` will be documented in this file.
 * Serve both protocol eras over stdio: `StdioTransport` settles the era on the client's first request and serves `2026-07-28` requests, `subscriptions/listen` and `notifications/cancelled` on the one channel.
 * Answer a bare `initialize` on a `2026-07-28`-only endpoint with `-32022` naming the served revisions, and a request without a session on the handshake leg with its id.
 * Speak both protocol eras from a client configured with `2026-07-28`: `connect()` probes with `server/discover` and falls back to the `initialize` handshake on `2025-11-25` when the server does not speak the modern era. `Builder::setFallbackProtocolVersion()` picks the fallback revision, or `null` for a modern-only client.
+* [BC Break] Bump the client's default protocol version to `2026-07-28`, so a client speaks both protocol eras unless told otherwise. Against a server that speaks both, a default client now settles on `2026-07-28`, which removed sampling and roots; call `Builder::setProtocolVersion(ProtocolVersion::V2025_11_25)` to keep them.
 * On a `2026-07-28` connection, `Client::setLoggingLevel()` stamps the level on every following request, `Client::ping()` sends `server/discover` and `Client::sendRootsListChanged()` sends nothing.
 * Fail a client request at once when the HTTP server refuses it with an error status or the stdio server process exits, instead of waiting out the timeout.
 

docs/client/connecting.md

@@ -61,34 +61,33 @@ $client = Client::builder()
 
 ### Protocol Version
 
-Specify the MCP protocol version to speak (defaults to `V2025_11_25`). A handshake revision opens with `initialize`:
-
-```php
-use Mcp\Schema\Enum\ProtocolVersion;
-
-$client = Client::builder()
-    ->setProtocolVersion(ProtocolVersion::V2025_11_25)
-    ->build();
-```
-
-A modern revision makes the client speak both protocol eras: it probes for `2026-07-28` with `server/discover` when
+A client speaks both protocol eras by default. It prefers `2026-07-28`, probes for it with `server/discover` when
 connecting, and falls back to the `initialize` handshake on `2025-11-25` when the server turns out not to speak it.
 Use `$client->getProtocolVersion()` after connecting to read what the connection settled on.
 
 ```php
+use Mcp\Schema\Enum\ProtocolVersion;
+
 // Fall back to an older handshake revision instead of 2025-11-25…
 $client = Client::builder()
-    ->setProtocolVersion(ProtocolVersion::V2026_07_28)
     ->setFallbackProtocolVersion(ProtocolVersion::V2025_06_18)
     ->build();
 
 // …or not at all, refusing servers without the modern era.
 $client = Client::builder()
-    ->setProtocolVersion(ProtocolVersion::V2026_07_28)
     ->setFallbackProtocolVersion(null)
     ->build();
 ```
 
+Passing a handshake revision to `setProtocolVersion()` skips the probe and opens with `initialize`, the way a client
+from before the modern era would:
+
+```php
+$client = Client::builder()
+    ->setProtocolVersion(ProtocolVersion::V2025_11_25)
+    ->build();
+```
+
 The handshake is an offer, not a demand. A server that does not support the requested revision counter-offers one it
 does, as described in the specification's
 [protocol version negotiation](https://modelcontextprotocol.io/specification/latest/basic/versioning#protocol-version-negotiation)

docs/protocol-versions.md

@@ -106,14 +106,13 @@ either lifecycle. What changes:
 
 ## Speaking it from a client
 
-Ask for `2026-07-28` and the client speaks both eras: it finds out on `connect()` whether
-the server does too, and nothing about the [client API](client/index.md) depends on the
-answer.
+A client speaks both eras out of the box. It prefers `2026-07-28`, and finds out on
+`connect()` whether the server does too; nothing about the [client API](client/index.md)
+depends on the answer.
 
 ```php
 $client = Client::builder()
     ->setClientInfo('my-client', '1.0.0')
-    ->setProtocolVersion(ProtocolVersion::V2026_07_28)
     ->setCapabilities(new ClientCapabilities(elicitation: true))
     ->addRequestHandler($myElicitationHandler)
     ->build();

src/Client/Builder.php

@@ -69,7 +69,7 @@ public function setClientInfo(string $name, string $version, ?string $descriptio
     /**
      * Set the protocol version the client prefers.
      *
-     * Defaults to 2025-11-25. A modern revision is probed for with
+     * Defaults to 2026-07-28. A modern revision is probed for with
      * `server/discover` and falls back to the `initialize` handshake when the
      * server turns out not to speak it, see {@see self::setFallbackProtocolVersion()};
      * a handshake revision skips the probe and opens with the handshake.
@@ -218,7 +218,7 @@ public function build(): Client
         $config = new Configuration(
             clientInfo: $clientInfo,
             capabilities: $capabilities,
-            protocolVersion: $this->protocolVersion ?? ProtocolVersion::V2025_11_25,
+            protocolVersion: $this->protocolVersion ?? ProtocolVersion::V2026_07_28,
             initTimeout: $this->initTimeout,
             requestTimeout: $this->requestTimeout,
             maxRetries: $this->maxRetries,

src/Client/Configuration.php

@@ -34,7 +34,7 @@ class Configuration
     public function __construct(
         public readonly Implementation $clientInfo,
         public readonly ClientCapabilities $capabilities,
-        public readonly ProtocolVersion $protocolVersion = ProtocolVersion::V2025_11_25,
+        public readonly ProtocolVersion $protocolVersion = ProtocolVersion::V2026_07_28,
         public readonly int $initTimeout = 30,
         public readonly int $requestTimeout = 120,
         public readonly int $maxRetries = 3,

src/Schema/JsonRpc/MessageInterface.php

@@ -21,5 +21,5 @@
 interface MessageInterface extends \JsonSerializable
 {
     public const JSONRPC_VERSION = '2.0';
-    public const PROTOCOL_VERSION = ProtocolVersion::V2025_11_25;
+    public const PROTOCOL_VERSION = ProtocolVersion::V2026_07_28;
 }

src/Schema/Result/InitializeResult.php

@@ -14,7 +14,6 @@
 use Mcp\Exception\InvalidArgumentException;
 use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\Implementation;
-use Mcp\Schema\JsonRpc\MessageInterface;
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\JsonRpc\ResultInterface;
 use Mcp\Schema\ServerCapabilities;
@@ -91,7 +90,7 @@ public static function fromArray(array $data): self
      */
     public function jsonSerialize(): array
     {
-        $protocolVersion = $this->protocolVersion ?? MessageInterface::PROTOCOL_VERSION;
+        $protocolVersion = $this->protocolVersion ?? ProtocolVersion::latestHandshake();
         $data = [
             'protocolVersion' => $protocolVersion->value,
             'capabilities' => $this->capabilities,

tests/Integration/ElicitationTest.php

@@ -82,7 +82,9 @@ public function testAdvertisedCapabilityWithoutHandler(): void
         // with an error, see below.
         $client = $this->connect(
             'elicitation',
-            $this->clientBuilder()->setCapabilities(new ClientCapabilities(elicitation: true)),
+            $this->clientBuilder()
+                ->setProtocolVersion(ProtocolVersion::V2025_11_25)
+                ->setCapabilities(new ClientCapabilities(elicitation: true)),
         );
 
         $result = $client->callTool('ask_name');

tests/Integration/HandshakeTest.php

@@ -47,7 +47,9 @@ public function testNegotiatedVersion(?ProtocolVersion $clientVersion, ?Protocol
      */
     public static function provideNegotiations(): iterable
     {
-        yield 'both unconfigured' => [null, null, ProtocolVersion::latestHandshake()];
+        // Both ends speak both eras, so they settle on the modern one.
+        yield 'both unconfigured' => [null, null, ProtocolVersion::V2026_07_28];
+        yield 'server without the modern era, client unconfigured' => [null, null, ProtocolVersion::V2025_11_25, true];
 
         // Whichever end of the supported range it sits at.
         foreach (ProtocolVersion::handshakeVersions() as $version) {

tests/Integration/RootsTest.php

@@ -16,6 +16,7 @@
 use Mcp\Client\Handler\Request\RootsCallbackInterface;
 use Mcp\Schema\ClientCapabilities;
 use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\Request\ListRootsRequest;
 use Mcp\Schema\Result\ListRootsResult;
 use Mcp\Schema\Root;
@@ -28,6 +29,15 @@
  */
 final class RootsTest extends IntegrationTestCase
 {
+    /**
+     * Roots exists only on the handshake era: 2026-07-28 removed it, so a
+     * client and server that could both settle on the modern era are kept off it.
+     */
+    protected function clientBuilder(): ClientBuilder
+    {
+        return parent::clientBuilder()->setProtocolVersion(ProtocolVersion::V2025_11_25);
+    }
+
     #[TestDox('the roots the client exposes reach the tool that asked')]
     public function testRootsReachTheTool(): void
     {