Settle the era lock exactly once and unify the modern-entry boundaries

The dual-era loop's lock-on-success rule approximated "client-visible
success" with "the handler returned", leaving windows where a request the
client saw fail still moved the era: a pipelined envelope-bearing request
completing after an inline initialize overwrote the committed legacy lock
(stranding the freshly-handshaked client), and a peer cancel landing
during the handler's shielded teardown locked the era while the client
received "Request cancelled". Era commits now run through a single
era_settles predicate: monotone (the first success wins, a straggler from
the other era can never move a committed lock) and skipped when a pending
cancel is about to replace the response.

Two modern-path divergences between the stream loop and the HTTP entry
close by sharing one pipeline: Connection.from_envelope takes the
classifier's raw envelope values and owns the tolerant coercion (custom
methods now degrade mis-shaped clientInfo identically everywhere), and a
shared modern_error_data boundary maps unmapped handler exceptions to a
generic INTERNAL_ERROR instead of the legacy code-0 catch-all putting
str(e) on the wire.

The classifier's non-string protocol-version guard moves below the header
rung, so the HTTP wire is untouched whenever the version header is
present, while the guard still backstops the header-absent null-version
corner that previously escaped as a ValidationError.

Author: maxisbey

src/mcp/server/_streamable_http_modern.py

@@ -22,21 +22,18 @@
 import logging
 from collections.abc import Awaitable, Mapping
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Any, Final, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Final, cast
 
 import anyio
 from anyio.streams.memory import MemoryObjectSendStream
 from mcp_types import (
     CLIENT_CAPABILITIES_META_KEY,
     CLIENT_INFO_META_KEY,
     HEADER_MISMATCH,
-    INTERNAL_ERROR,
     INVALID_REQUEST,
     PARSE_ERROR,
     PROTOCOL_VERSION_META_KEY,
-    ClientCapabilities,
     ErrorData,
-    Implementation,
     JSONRPCError,
     JSONRPCNotification,
     JSONRPCRequest,
@@ -45,13 +42,13 @@
     RequestId,
 )
 from mcp_types import methods as _methods
-from pydantic import BaseModel, ValidationError
+from pydantic import ValidationError
 from starlette.requests import Request
 from starlette.responses import Response
 from starlette.types import Receive, Scope, Send
 
 from mcp.server.connection import Connection
-from mcp.server.runner import serve_one
+from mcp.server.runner import modern_error_data, serve_one
 from mcp.server.streamable_http import check_accept_headers
 from mcp.server.transport_security import TransportSecurityMiddleware, TransportSecuritySettings
 from mcp.shared.dispatcher import CallOptions
@@ -65,7 +62,7 @@
     find_duplicated_routing_header,
     validate_mcp_param_headers,
 )
-from mcp.shared.jsonrpc_dispatcher import handler_exception_to_error_data, progress_token_from_params
+from mcp.shared.jsonrpc_dispatcher import progress_token_from_params
 from mcp.shared.message import MessageMetadata, ServerMessageMetadata
 from mcp.shared.transport_context import TransportContext
 
@@ -74,7 +71,6 @@
 
 logger = logging.getLogger(__name__)
 
-_ModelT = TypeVar("_ModelT", bound=BaseModel)
 
 _OK_STATUS = 200
 
@@ -125,37 +121,20 @@ async def progress(self, progress: float, total: float | None = None, message: s
         await self.notify("notifications/progress", params)
 
 
-def _typed(model: type[_ModelT], raw: Any) -> _ModelT | None:
-    """Validate the classifier's raw envelope value into a typed model.
-
-    Rung 1 guarantees the envelope key was present; a ``null`` or mis-shaped
-    value falls through to ``ValidationError`` and is treated as not supplied
-    so the request still routes.
-    """
-    try:
-        return model.model_validate(raw, by_name=False)
-    except ValidationError:
-        return None
-
-
 async def _to_jsonrpc_response(
     request_id: RequestId, coro: Awaitable[dict[str, Any]]
 ) -> JSONRPCResponse | JSONRPCError:
     """Await ``coro`` and wrap its outcome as the JSON-RPC reply for ``request_id``.
 
     The exception-to-wire boundary for the modern HTTP entry, composed around
-    `serve_one`. `MCPError` and `ValidationError` map via the shared
-    `handler_exception_to_error_data` ladder; any other exception is logged and
-    surfaced as `INTERNAL_ERROR` so handler internals never reach the wire.
+    `serve_one`: `modern_error_data` maps the shared ladder and surfaces
+    anything else as a generic `INTERNAL_ERROR` so handler internals never
+    reach the wire.
     """
     try:
         result = await coro
     except Exception as exc:
-        error = handler_exception_to_error_data(exc)
-        if error is None:
-            logger.exception("request handler raised")
-            error = ErrorData(code=INTERNAL_ERROR, message="Internal server error")
-        return JSONRPCError(jsonrpc="2.0", id=request_id, error=error)
+        return JSONRPCError(jsonrpc="2.0", id=request_id, error=modern_error_data(exc))
     return JSONRPCResponse(jsonrpc="2.0", id=request_id, result=result)
 
 
@@ -251,16 +230,16 @@ async def _tool_input_schema(
         logger.debug("Mcp-Param header validation skipped: the request envelope fails tools/list validation")
         return None
     seen_cursors: set[str] = set()
-    client_info = _typed(Implementation, verdict.client_info)
-    client_capabilities = _typed(ClientCapabilities, verdict.client_capabilities)
     dctx = _SingleExchangeDispatchContext(
         transport=TransportContext(kind="streamable-http", can_send_request=False, headers=request.headers),
         request_id=request_id,
         message_metadata=ServerMessageMetadata(request_context=request),
     )
     for _ in range(_MCP_PARAM_LIST_PAGE_CAP):
         # Fresh Connection per page: serve_one tears down the connection's exit stack on the way out.
-        connection = Connection.from_envelope(verdict.protocol_version, client_info, client_capabilities)
+        connection = Connection.from_envelope(
+            verdict.protocol_version, verdict.client_info, verdict.client_capabilities
+        )
         try:
             result = await serve_one(
                 app, dctx, "tools/list", list_params, connection=connection, lifespan_state=lifespan_state
@@ -409,8 +388,8 @@ async def handle_modern_request(
 
     connection = Connection.from_envelope(
         verdict.protocol_version,
-        _typed(Implementation, verdict.client_info),
-        _typed(ClientCapabilities, verdict.client_capabilities),
+        verdict.client_info,
+        verdict.client_capabilities,
     )
     dctx = _SingleExchangeDispatchContext(
         transport=TransportContext(kind="streamable-http", can_send_request=False, headers=request.headers),

src/mcp/server/connection.py

@@ -42,7 +42,7 @@
 )
 from mcp_types import methods as _methods
 from mcp_types.version import LATEST_HANDSHAKE_VERSION
-from pydantic import BaseModel
+from pydantic import BaseModel, ValidationError
 from typing_extensions import deprecated
 
 from mcp.shared.dispatcher import CallOptions, Outbound
@@ -68,6 +68,23 @@
 }
 
 
+_ModelT = TypeVar("_ModelT", bound=BaseModel)
+
+
+def _typed(model: type[_ModelT], raw: Any) -> _ModelT | None:
+    """Validate a raw envelope value into a typed model.
+
+    A missing, null or mis-shaped value falls through to `ValidationError`
+    and is treated as not supplied so the request still routes. Spec methods
+    are separately re-validated by the kernel's per-version params surface,
+    which types the reserved `_meta` keys strictly.
+    """
+    try:
+        return model.model_validate(raw, by_name=False)
+    except ValidationError:
+        return None
+
+
 def _notification_params(payload: dict[str, Any] | None, meta: Meta | None) -> dict[str, Any] | None:
     if not meta:
         return payload
@@ -172,26 +189,34 @@ def __init__(
     def from_envelope(
         cls,
         protocol_version: str,
-        client_info: Implementation | None,
-        client_capabilities: ClientCapabilities | None,
+        client_info: Any,
+        client_capabilities: Any,
         *,
         outbound: Outbound = _NO_CHANNEL,
     ) -> Connection:
         """A born-ready connection populated from a request's `_meta` envelope.
 
-        `initialized` is set and the envelope's client info/capabilities (when
-        both supplied) are recorded as `client_params` so capability checks
-        work. `outbound` defaults to the no-channel sentinel for the
-        single-exchange HTTP path; duplex modern transports (e.g. stdio) pass
-        a notify-only wrapper around the dispatcher so server notifications
-        ride the pipe while server-initiated requests stay refused.
+        `protocol_version` must be an already-validated version string - the
+        inbound classification ladder owns rejecting non-string or unsupported
+        values. `client_info` and `client_capabilities` are the raw envelope
+        values: this constructor owns turning them into connection identity,
+        identically on every modern entry, so a mis-shaped value degrades to
+        not-supplied rather than failing the request. `initialized`
+        is set and the info/capabilities (when both supplied and well-formed)
+        are recorded as `client_params` so capability checks work. `outbound`
+        defaults to the no-channel sentinel for the single-exchange HTTP path;
+        duplex modern transports (e.g. stdio) pass a notify-only wrapper
+        around the dispatcher so server notifications ride the pipe while
+        server-initiated requests stay refused.
         """
+        info = _typed(Implementation, client_info)
+        capabilities = _typed(ClientCapabilities, client_capabilities)
         client_params = None
-        if client_info is not None and client_capabilities is not None:
+        if info is not None and capabilities is not None:
             client_params = InitializeRequestParams(
                 protocol_version=protocol_version,
-                capabilities=client_capabilities,
-                client_info=client_info,
+                capabilities=capabilities,
+                client_info=info,
             )
         connection = cls(outbound, protocol_version=protocol_version, client_params=client_params)
         connection.initialized.set()

src/mcp/server/runner.py

@@ -59,7 +59,7 @@
 from mcp.shared.dispatcher import CallOptions, DispatchContext, Dispatcher, OnNotify, OnRequest
 from mcp.shared.exceptions import MCPError, NoBackChannelError
 from mcp.shared.inbound import InboundLadderRejection, classify_inbound_request
-from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher
+from mcp.shared.jsonrpc_dispatcher import JSONRPCDispatcher, handler_exception_to_error_data
 from mcp.shared.message import MessageMetadata, ServerMessageMetadata, SessionMessage
 from mcp.shared.transport_context import TransportContext
 
@@ -468,6 +468,23 @@ def _initialize_after_modern_data(params: Mapping[str, Any] | None) -> dict[str,
     return {"supported": list(MODERN_PROTOCOL_VERSIONS)}
 
 
+def modern_error_data(exc: Exception) -> ErrorData:
+    """Map a modern request's handler exception to its wire `ErrorData`.
+
+    The exception-to-wire fact shared by the modern entries (the
+    single-exchange HTTP path and the dual-era stream loop), so an identical
+    modern request fails identically on every transport: `MCPError` and
+    `ValidationError` map via the shared `handler_exception_to_error_data`
+    ladder; anything else is logged server-side and surfaced as a generic
+    INTERNAL_ERROR so handler internals never reach the wire.
+    """
+    error = handler_exception_to_error_data(exc)
+    if error is not None:
+        return error
+    logger.exception("modern request handler raised")
+    return ErrorData(code=INTERNAL_ERROR, message="Internal server error")
+
+
 @dataclass
 class _NoServerRequestsDispatchContext:
     """Delegating `DispatchContext` that refuses server-initiated requests.
@@ -562,7 +579,11 @@ async def serve_dual_era_loop(
     (`initialize`, `server/discover`) that completes before the next frame is
     read, so the canonical probe-then-go flow is race-free; a pinned-modern
     client that pipelines frames ahead of its first response should expect
-    envelope-less notifications sent in that window to be dropped.
+    envelope-less notifications sent in that window to be dropped. The lock
+    settles exactly once: a request from the other era that was already in
+    flight when the lock committed may still complete and its response
+    stands, but the era does not move; and a success the peer cancelled away
+    (it sees "Request cancelled", not the result) does not lock either.
     """
     dispatcher: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(
         read_stream,
@@ -579,6 +600,15 @@ async def serve_dual_era_loop(
     era: Literal["unlocked", "legacy", "modern"] = "unlocked"
     modern_version = LATEST_MODERN_VERSION
 
+    def era_settles(dctx: DispatchContext[TransportContext]) -> bool:
+        # The one definition of "this request may lock the era": it settled as
+        # a client-visible success on a still-unlocked connection. The lock is
+        # monotone - the first success wins, so a straggling request from the
+        # other era can never overwrite a committed lock. A pending peer
+        # cancel means the dispatcher is about to replace this response with
+        # "Request cancelled": the client never sees the success, no lock.
+        return era == "unlocked" and not dctx.cancel_requested.is_set()
+
     async def serve_modern(
         dctx: DispatchContext[TransportContext], method: str, params: Mapping[str, Any] | None
     ) -> dict[str, Any]:
@@ -599,18 +629,25 @@ async def serve_modern(
             route.client_capabilities,
             outbound=standalone_outbound,
         )
-        result = await serve_one(
-            server,
-            _NoServerRequestsDispatchContext(dctx),
-            method,
-            params,
-            connection=connection,
-            lifespan_state=lifespan_state,
-        )
-        if era != "modern":
-            # Lock only on success, mirroring the legacy side: a request that
-            # failed (malformed envelope content, unknown method) must not
-            # strand the client, whose initialize fallback stays available.
+        try:
+            result = await serve_one(
+                server,
+                _NoServerRequestsDispatchContext(dctx),
+                method,
+                params,
+                connection=connection,
+                lifespan_state=lifespan_state,
+            )
+        except (MCPError, ValidationError):
+            # The dispatcher's shared ladder maps these to the same wire error
+            # the modern HTTP entry produces.
+            raise
+        except Exception as exc:
+            if raise_exceptions:
+                raise
+            error = modern_error_data(exc)
+            raise MCPError(code=error.code, message=error.message, data=error.data) from exc
+        if era_settles(dctx):
             era, modern_version = "modern", route.protocol_version
         return result
 
@@ -643,7 +680,7 @@ async def on_request(
         if method != "initialize" and (method == "server/discover" or _has_modern_envelope(params)):
             return await serve_modern(dctx, method, params)
         result = await loop_runner.on_request(dctx, method, params)
-        if method == "initialize":
+        if method == "initialize" and era_settles(dctx):
             # Lock only on success: a failed handshake leaves both eras open.
             era = "legacy"
         return result

src/mcp/shared/inbound.py

@@ -377,16 +377,19 @@ def classify_inbound_request(
     Rungs, in order — first failure wins:
 
     1. `params._meta` is a mapping carrying every reserved envelope key
-       (protocol version, client info, client capabilities), and the protocol
-       version is a string → else :data:`~mcp_types.jsonrpc.INVALID_PARAMS`.
+       (protocol version, client info, client capabilities) → else
+       :data:`~mcp_types.jsonrpc.INVALID_PARAMS`.
     2. When `headers` is given, `MCP-Protocol-Version` equals the envelope's
        protocol version, `Mcp-Method` equals `body.method`, and — for the
        methods in :data:`NAME_BEARING_METHODS` — `Mcp-Name` equals the named
        body param → else :data:`~mcp_types.jsonrpc.HEADER_MISMATCH`. Runs
        before the supported-version rung so a client that disagrees with itself
        is told so, rather than told the body's version is unsupported.
-    3. The envelope's protocol version is in `supported_modern_versions` →
-       else :data:`~mcp_types.jsonrpc.UNSUPPORTED_PROTOCOL_VERSION` with
+    3. The envelope's protocol version is a string in
+       `supported_modern_versions` → non-string values are
+       :data:`~mcp_types.jsonrpc.INVALID_PARAMS` (a shape defect, not a
+       negotiation outcome), else
+       :data:`~mcp_types.jsonrpc.UNSUPPORTED_PROTOCOL_VERSION` with
        `data = {"supported": [...], "requested": <value>}`.
 
     Method existence is *not* a rung: kernel dispatch owns that decision so
@@ -411,15 +414,6 @@ def classify_inbound_request(
             message="params._meta must carry the reserved protocol-version, client-info and "
             "client-capabilities envelope keys",
         )
-    if not isinstance(protocol_version, str):
-        # A shape defect, not a version-negotiation outcome: -32022 is the one
-        # code auto-negotiating clients do NOT fall back from, and the typed
-        # rung-3 payload itself requires a string `requested`.
-        return InboundLadderRejection(
-            code=INVALID_PARAMS,
-            message="the protocol-version envelope value must be a string",
-        )
-
     if headers is not None:
         if headers.get(MCP_PROTOCOL_VERSION_HEADER) != protocol_version:
             return InboundLadderRejection(
@@ -442,6 +436,18 @@ def classify_inbound_request(
                     message=f"{MCP_NAME_HEADER} header does not match the request body's {name_key!r} parameter",
                 )
 
+    if not isinstance(protocol_version, str):
+        # Rung 3's precondition: a shape defect, not a version-negotiation
+        # outcome - -32022 is the one code auto-negotiating clients do NOT
+        # fall back from, and the typed rung-3 payload itself requires a
+        # string `requested`. Sits after the header rung so the HTTP wire is
+        # untouched when the version header is present (a string header can
+        # never equal a non-string body value, so rung 2 fires first there).
+        return InboundLadderRejection(
+            code=INVALID_PARAMS,
+            message="the protocol-version envelope value must be a string",
+        )
+
     if protocol_version not in supported_modern_versions:
         return InboundLadderRejection(
             code=UNSUPPORTED_PROTOCOL_VERSION,