Rename SUPPORTED_PROTOCOL_VERSIONS to HANDSHAKE_PROTOCOL_VERSIONS; consolidate header constant

- HANDSHAKE_PROTOCOL_VERSIONS names what the constant actually holds (versions
  reachable via the initialize handshake); SUPPORTED_PROTOCOL_VERSIONS survives
  as a deprecated union of HANDSHAKE + MODERN for v1.x compatibility
- The three handshake-ceiling call sites (initialize offer, server negotiate
  fallback, for_loop seed) now read HANDSHAKE_PROTOCOL_VERSIONS[-1] instead of
  LATEST_PROTOCOL_VERSION
- Era-routing in the streamable-HTTP manager reads HANDSHAKE_PROTOCOL_VERSIONS
  (interim; the body-primary classifier is the structural fix)
- mcp-protocol-version header constant: three duplicate definitions collapsed
  to the single MCP_PROTOCOL_VERSION_HEADER in shared/inbound; client and
  server importers point at the canonical module
- migration.md documents the SUPPORTED deprecation

Author: maxisbey

docs/migration.md

@@ -764,6 +764,10 @@ async def my_tool(ctx: Context) -> str: ...
 async def my_tool(ctx: Context[MyLifespanState]) -> str: ...
 ```
 
+### Version constants
+
+`SUPPORTED_PROTOCOL_VERSIONS` is deprecated — it's now the union of `HANDSHAKE_PROTOCOL_VERSIONS` (initialize-handshake versions) and `MODERN_PROTOCOL_VERSIONS` (per-request-envelope versions). If you were using it to mean "versions the initialize handshake accepts", switch to `HANDSHAKE_PROTOCOL_VERSIONS`.
+
 ### `ProgressContext` and `progress()` context manager removed
 
 The `mcp.shared.progress` module (`ProgressContext`, `Progress`, and the `progress()` context manager) has been removed. This module had no real-world adoption — all users send progress notifications via `Context.report_progress()` or `session.send_progress_notification()` directly.

src/mcp/client/auth/oauth2.py

@@ -40,7 +40,6 @@
     validate_authorization_response_iss,
     validate_metadata_issuer,
 )
-from mcp.client.streamable_http import MCP_PROTOCOL_VERSION
 from mcp.shared.auth import (
     AuthorizationCodeResult,
     OAuthClientInformationFull,
@@ -54,6 +53,7 @@
     check_resource_allowed,
     resource_url_from_server_url,
 )
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
 from mcp.shared.version import is_version_at_least
 
 logger = logging.getLogger(__name__)
@@ -534,7 +534,7 @@ async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.
                 await self._initialize()
 
             # Capture protocol version from request headers
-            self.context.protocol_version = request.headers.get(MCP_PROTOCOL_VERSION)
+            self.context.protocol_version = request.headers.get(MCP_PROTOCOL_VERSION_HEADER)
 
             if not self.context.is_token_valid() and self.context.can_refresh_token():
                 # Try to refresh token

src/mcp/client/auth/utils.py

@@ -5,14 +5,14 @@
 from pydantic import AnyUrl, ValidationError
 
 from mcp.client.auth import OAuthFlowError, OAuthRegistrationError, OAuthTokenError
-from mcp.client.streamable_http import MCP_PROTOCOL_VERSION
 from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
     OAuthMetadata,
     OAuthToken,
     ProtectedResourceMetadata,
 )
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
 from mcp.types import LATEST_PROTOCOL_VERSION
 
 
@@ -273,7 +273,7 @@ def validate_metadata_issuer(oauth_metadata: OAuthMetadata, expected_issuer: str
 
 
 def create_oauth_metadata_request(url: str) -> Request:
-    return Request("GET", url, headers={MCP_PROTOCOL_VERSION: LATEST_PROTOCOL_VERSION})
+    return Request("GET", url, headers={MCP_PROTOCOL_VERSION_HEADER: LATEST_PROTOCOL_VERSION})
 
 
 def create_client_registration_request(

src/mcp/client/session.py

@@ -21,7 +21,7 @@
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.shared.session import RequestResponder
 from mcp.shared.transport_context import TransportContext
-from mcp.shared.version import MODERN_PROTOCOL_VERSIONS, SUPPORTED_PROTOCOL_VERSIONS
+from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
 from mcp.types import (
     CLIENT_CAPABILITIES_META_KEY,
     CLIENT_INFO_META_KEY,
@@ -320,15 +320,15 @@ async def initialize(self) -> types.InitializeResult:
                 params=types.InitializeRequestParams(
                     protocol_version=self._pinned_version
                     if self._pinned_version is not None
-                    else types.LATEST_PROTOCOL_VERSION,
+                    else HANDSHAKE_PROTOCOL_VERSIONS[-1],
                     capabilities=capabilities,
                     client_info=self._client_info,
                 ),
             ),
             types.InitializeResult,
         )
 
-        if result.protocol_version not in SUPPORTED_PROTOCOL_VERSIONS:
+        if result.protocol_version not in HANDSHAKE_PROTOCOL_VERSIONS:
             raise RuntimeError(f"Unsupported protocol version from the server: {result.protocol_version}")
 
         self._initialize_result = result

src/mcp/client/streamable_http.py

@@ -20,6 +20,7 @@
 from mcp.shared._compat import resync_tracer
 from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
 from mcp.shared._httpx_utils import create_mcp_http_client
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
 from mcp.shared.version import MODERN_PROTOCOL_VERSIONS
 from mcp.types import (
@@ -46,7 +47,6 @@
 StreamReader = ContextReceiveStream[SessionMessage]
 
 MCP_SESSION_ID = "mcp-session-id"
-MCP_PROTOCOL_VERSION = "mcp-protocol-version"
 MCP_METHOD = "mcp-method"
 MCP_NAME = "mcp-name"
 LAST_EVENT_ID = "last-event-id"
@@ -138,7 +138,7 @@ def _prepare_headers(self) -> dict[str, str]:
         if self.session_id:
             headers[MCP_SESSION_ID] = self.session_id
         if self.protocol_version:
-            headers[MCP_PROTOCOL_VERSION] = self.protocol_version
+            headers[MCP_PROTOCOL_VERSION_HEADER] = self.protocol_version
         return headers
 
     def _is_initialization_request(self, message: JSONRPCMessage) -> bool:

src/mcp/server/auth/routes.py

@@ -17,8 +17,8 @@
 from mcp.server.auth.middleware.client_auth import ClientAuthenticator
 from mcp.server.auth.provider import OAuthAuthorizationServerProvider
 from mcp.server.auth.settings import ClientRegistrationOptions, RevocationOptions
-from mcp.server.streamable_http import MCP_PROTOCOL_VERSION_HEADER
 from mcp.shared.auth import OAuthMetadata, ProtectedResourceMetadata
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
 
 
 def validate_issuer_url(url: AnyHttpUrl):

src/mcp/server/connection.py

@@ -31,8 +31,8 @@
 from mcp.shared.dispatcher import CallOptions, Outbound
 from mcp.shared.exceptions import MCPDeprecationWarning, NoBackChannelError
 from mcp.shared.peer import Meta, dump_params
+from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS
 from mcp.types import (
-    LATEST_PROTOCOL_VERSION,
     ClientCapabilities,
     CreateMessageRequest,
     CreateMessageResult,
@@ -192,12 +192,14 @@ def for_loop(
 
         Not born-ready: `initialized` is set later by the kernel when
         `notifications/initialized` arrives. `protocol_version` is seeded from
-        the transport hint (or `LATEST_PROTOCOL_VERSION`) so it's never `None`;
+        the transport hint (or `HANDSHAKE_PROTOCOL_VERSIONS[-1]`) so it's never `None`;
         the handshake overwrites it once negotiated.
         """
         return cls(
             outbound,
-            protocol_version=protocol_version_hint if protocol_version_hint is not None else LATEST_PROTOCOL_VERSION,
+            protocol_version=protocol_version_hint
+            if protocol_version_hint is not None
+            else HANDSHAKE_PROTOCOL_VERSIONS[-1],
             session_id=session_id,
         )
 

src/mcp/server/runner.py

@@ -36,11 +36,10 @@
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher, handler_exception_to_error_data
 from mcp.shared.message import ServerMessageMetadata, SessionMessage
 from mcp.shared.transport_context import TransportContext
-from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
+from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS
 from mcp.types import (
     INTERNAL_ERROR,
     INVALID_PARAMS,
-    LATEST_PROTOCOL_VERSION,
     METHOD_NOT_FOUND,
     ErrorData,
     Implementation,
@@ -414,7 +413,7 @@ def _negotiate_initialize(params: Mapping[str, Any] | None) -> tuple[InitializeR
         """Validate `initialize` params and pick the protocol version."""
         init = InitializeRequestParams.model_validate(params or {}, by_name=False)
         requested = init.protocol_version
-        negotiated = requested if requested in SUPPORTED_PROTOCOL_VERSIONS else LATEST_PROTOCOL_VERSION
+        negotiated = requested if requested in HANDSHAKE_PROTOCOL_VERSIONS else HANDSHAKE_PROTOCOL_VERSIONS[-1]
         return init, negotiated
 
     def _handle_initialize(self, params: Mapping[str, Any] | None) -> InitializeResult:

src/mcp/server/streamable_http.py

@@ -28,6 +28,7 @@
 from mcp.server.transport_security import TransportSecurityMiddleware, TransportSecuritySettings
 from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
 from mcp.shared._stream_protocols import ReadStream, WriteStream
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
 from mcp.shared.message import ServerMessageMetadata, SessionMessage
 from mcp.shared.version import is_version_at_least
 from mcp.types import (
@@ -50,7 +51,6 @@
 
 # Header names
 MCP_SESSION_ID_HEADER = "mcp-session-id"
-MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version"
 LAST_EVENT_ID_HEADER = "last-event-id"
 
 # Content types
@@ -818,7 +818,7 @@ async def _handle_unsupported_request(self, request: Request, send: Send) -> Non
 
     async def _validate_request_headers(self, request: Request, send: Send) -> bool:
         # Protocol-version validation lives in the manager's era-routing: only
-        # values in `SUPPORTED_PROTOCOL_VERSIONS` (or no header at all) reach
+        # values in `HANDSHAKE_PROTOCOL_VERSIONS` (or no header at all) reach
         # this transport, so the legacy version-gate is gone.
         return await self._validate_session(request, send)
 

src/mcp/server/streamable_http_manager.py

@@ -19,16 +19,16 @@
 from mcp.server.connection import Connection
 from mcp.server.runner import serve_connection, serve_loop
 from mcp.server.streamable_http import (
-    MCP_PROTOCOL_VERSION_HEADER,
     MCP_SESSION_ID_HEADER,
     EventStore,
     StreamableHTTPServerTransport,
 )
 from mcp.server.transport_security import TransportSecuritySettings
 from mcp.shared._compat import resync_tracer
+from mcp.shared.inbound import MCP_PROTOCOL_VERSION_HEADER
 from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
 from mcp.shared.transport_context import TransportContext
-from mcp.shared.version import SUPPORTED_PROTOCOL_VERSIONS
+from mcp.shared.version import HANDSHAKE_PROTOCOL_VERSIONS
 from mcp.types import DEFAULT_NEGOTIATED_VERSION, INVALID_REQUEST, ErrorData, JSONRPCError
 
 if TYPE_CHECKING:
@@ -169,7 +169,7 @@ async def handle_request(self, scope: Scope, receive: Receive, send: Send) -> No
         # and return a structured rejection. 2025 paths below remain unchanged.
         header = MCP_PROTOCOL_VERSION_HEADER.encode("ascii")
         pv = next((v.decode("latin-1") for k, v in scope["headers"] if k == header), None)
-        if pv is not None and pv not in SUPPORTED_PROTOCOL_VERSIONS:
+        if pv is not None and pv not in HANDSHAKE_PROTOCOL_VERSIONS:
             await handle_modern_request(self.app, self.security_settings, self._lifespan_state, scope, receive, send)
             return