From 09596c0382e700e2d83b78f890001b4023ef3540 Mon Sep 17 00:00:00 2001
From: ineersa <ineersa@gmail.com>
Date: Fri, 7 Nov 2025 18:37:01 -0500
Subject: [PATCH] Ability to set custom protocol version (#117)

---
 src/Schema/Enum/ProtocolVersion.php           | 24 ++++++
 src/Schema/JsonRpc/MessageInterface.php       |  4 +-
 src/Schema/Result/InitializeResult.php        |  8 +-
 src/Server/Builder.php                        | 12 ++-
 src/Server/Configuration.php                  |  2 +
 .../Handler/Request/InitializeHandler.php     |  2 +
 .../Handler/Request/InitializeHandlerTest.php | 76 +++++++++++++++++++
 7 files changed, 124 insertions(+), 4 deletions(-)
 create mode 100644 src/Schema/Enum/ProtocolVersion.php
 create mode 100644 tests/Unit/Server/Handler/Request/InitializeHandlerTest.php

diff --git a/src/Schema/Enum/ProtocolVersion.php b/src/Schema/Enum/ProtocolVersion.php
new file mode 100644
index 0000000..d2d4443
--- /dev/null
+++ b/src/Schema/Enum/ProtocolVersion.php
@@ -0,0 +1,24 @@
+<?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\Schema\Enum;
+
+/**
+ * Available protocol versions for MCP.
+ */
+enum ProtocolVersion: string
+{
+    case V2024_11_05 = '2024-11-05';
+
+    case V2025_03_26 = '2025-03-26';
+
+    case V2025_06_18 = '2025-06-18';
+}
diff --git a/src/Schema/JsonRpc/MessageInterface.php b/src/Schema/JsonRpc/MessageInterface.php
index 1660a0d..6e4d1c1 100644
--- a/src/Schema/JsonRpc/MessageInterface.php
+++ b/src/Schema/JsonRpc/MessageInterface.php
@@ -11,6 +11,8 @@
 
 namespace Mcp\Schema\JsonRpc;
 
+use Mcp\Schema\Enum\ProtocolVersion;
+
 /**
  * Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent.
  *
@@ -19,5 +21,5 @@ namespace Mcp\Schema\JsonRpc;
 interface MessageInterface extends \JsonSerializable
 {
     public const JSONRPC_VERSION = '2.0';
-    public const PROTOCOL_VERSION = '2025-06-18';
+    public const PROTOCOL_VERSION = ProtocolVersion::V2025_06_18;
 }
diff --git a/src/Schema/Result/InitializeResult.php b/src/Schema/Result/InitializeResult.php
index 9b0087e..f76a1db 100644
--- a/src/Schema/Result/InitializeResult.php
+++ b/src/Schema/Result/InitializeResult.php
@@ -12,6 +12,7 @@
 namespace Mcp\Schema\Result;
 
 use Mcp\Exception\InvalidArgumentException;
+use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\Implementation;
 use Mcp\Schema\JsonRpc\MessageInterface;
 use Mcp\Schema\JsonRpc\Response;
@@ -38,6 +39,7 @@ class InitializeResult implements ResultInterface
         public readonly Implementation $serverInfo,
         public readonly ?string $instructions = null,
         public readonly ?array $_meta = null,
+        public readonly ?ProtocolVersion $protocolVersion = null,
     ) {
     }
 
@@ -66,7 +68,8 @@ class InitializeResult implements ResultInterface
             ServerCapabilities::fromArray($data['capabilities']),
             Implementation::fromArray($data['serverInfo']),
             $data['instructions'] ?? null,
-            $data['_meta'] ?? null
+            $data['_meta'] ?? null,
+            ProtocolVersion::tryFrom($data['protocolVersion']),
         );
     }
 
@@ -81,8 +84,9 @@ class InitializeResult implements ResultInterface
      */
     public function jsonSerialize(): array
     {
+        $protocolVersion = $this->protocolVersion ?? MessageInterface::PROTOCOL_VERSION;
         $data = [
-            'protocolVersion' => MessageInterface::PROTOCOL_VERSION,
+            'protocolVersion' => $protocolVersion->value,
             'capabilities' => $this->capabilities,
             'serverInfo' => $this->serverInfo,
         ];
diff --git a/src/Server/Builder.php b/src/Server/Builder.php
index 744e04b..f432716 100644
--- a/src/Server/Builder.php
+++ b/src/Server/Builder.php
@@ -20,6 +20,7 @@ use Mcp\Capability\Registry\Loader\LoaderInterface;
 use Mcp\Capability\Registry\ReferenceHandler;
 use Mcp\JsonRpc\MessageFactory;
 use Mcp\Schema\Annotations;
+use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\Implementation;
 use Mcp\Schema\ServerCapabilities;
 use Mcp\Schema\ToolAnnotations;
@@ -63,6 +64,8 @@ final class Builder
 
     private ?string $instructions = null;
 
+    private ?ProtocolVersion $protocolVersion = null;
+
     /**
      * @var array<int, RequestHandlerInterface<mixed>>
      */
@@ -288,6 +291,13 @@ final class Builder
         return $this;
     }
 
+    public function setProtocolVersion(?ProtocolVersion $protocolVersion): self
+    {
+        $this->protocolVersion = $protocolVersion;
+
+        return $this;
+    }
+
     /**
      * Manually registers a tool handler.
      *
@@ -404,7 +414,7 @@ final class Builder
         $messageFactory = MessageFactory::make();
 
         $capabilities = $registry->getCapabilities();
-        $configuration = new Configuration($this->serverInfo, $capabilities, $this->paginationLimit, $this->instructions);
+        $configuration = new Configuration($this->serverInfo, $capabilities, $this->paginationLimit, $this->instructions, $this->protocolVersion);
         $referenceHandler = new ReferenceHandler($container);
 
         $requestHandlers = array_merge($this->requestHandlers, [
diff --git a/src/Server/Configuration.php b/src/Server/Configuration.php
index ab629b5..2f0bd7f 100644
--- a/src/Server/Configuration.php
+++ b/src/Server/Configuration.php
@@ -11,6 +11,7 @@
 
 namespace Mcp\Server;
 
+use Mcp\Schema\Enum\ProtocolVersion;
 use Mcp\Schema\Implementation;
 use Mcp\Schema\ServerCapabilities;
 
@@ -34,6 +35,7 @@ class Configuration
         public readonly ServerCapabilities $capabilities,
         public readonly int $paginationLimit = 50,
         public readonly ?string $instructions = null,
+        public readonly ?ProtocolVersion $protocolVersion = null,
     ) {
     }
 }
diff --git a/src/Server/Handler/Request/InitializeHandler.php b/src/Server/Handler/Request/InitializeHandler.php
index 32eae19..d814d9d 100644
--- a/src/Server/Handler/Request/InitializeHandler.php
+++ b/src/Server/Handler/Request/InitializeHandler.php
@@ -52,6 +52,8 @@ final class InitializeHandler implements RequestHandlerInterface
                 $this->configuration->capabilities ?? new ServerCapabilities(),
                 $this->configuration->serverInfo ?? new Implementation(),
                 $this->configuration?->instructions,
+                null,
+                $this->configuration?->protocolVersion,
             ),
         );
     }
diff --git a/tests/Unit/Server/Handler/Request/InitializeHandlerTest.php b/tests/Unit/Server/Handler/Request/InitializeHandlerTest.php
new file mode 100644
index 0000000..36c36f1
--- /dev/null
+++ b/tests/Unit/Server/Handler/Request/InitializeHandlerTest.php
@@ -0,0 +1,76 @@
+<?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\Tests\Unit\Server\Handler\Request;
+
+use Mcp\Schema\Enum\ProtocolVersion;
+use Mcp\Schema\Implementation;
+use Mcp\Schema\JsonRpc\MessageInterface;
+use Mcp\Schema\Request\InitializeRequest;
+use Mcp\Schema\Result\InitializeResult;
+use Mcp\Schema\ServerCapabilities;
+use Mcp\Server\Configuration;
+use Mcp\Server\Handler\Request\InitializeHandler;
+use Mcp\Server\Session\SessionInterface;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+class InitializeHandlerTest extends TestCase
+{
+    #[TestDox('uses configuration protocol version when provided')]
+    public function testHandleUsesConfigurationProtocolVersion(): void
+    {
+        $customProtocolVersion = ProtocolVersion::V2024_11_05;
+
+        $configuration = new Configuration(
+            serverInfo: new Implementation('server', '1.2.3'),
+            capabilities: new ServerCapabilities(),
+            protocolVersion: $customProtocolVersion,
+        );
+
+        $handler = new InitializeHandler($configuration);
+
+        $session = $this->createMock(SessionInterface::class);
+        $session->expects($this->once())
+            ->method('set')
+            ->with('client_info', [
+                'name' => 'client-app',
+                'version' => '1.0.0',
+            ]);
+
+        $request = InitializeRequest::fromArray([
+            'jsonrpc' => MessageInterface::JSONRPC_VERSION,
+            'id' => 'request-1',
+            'method' => InitializeRequest::getMethod(),
+            'params' => [
+                'protocolVersion' => ProtocolVersion::V2024_11_05->value,
+                'capabilities' => [],
+                'clientInfo' => [
+                    'name' => 'client-app',
+                    'version' => '1.0.0',
+                ],
+            ],
+        ]);
+
+        $response = $handler->handle($request, $session);
+
+        $this->assertInstanceOf(InitializeResult::class, $response->result);
+
+        /** @var InitializeResult $result */
+        $result = $response->result;
+
+        $this->assertSame($customProtocolVersion, $result->protocolVersion);
+        $this->assertSame(
+            $customProtocolVersion->value,
+            $result->jsonSerialize()['protocolVersion']
+        );
+    }
+}