Report the negotiated protocol_version once initialized; clarify envelope-overwrite semantics

- ClientSession.protocol_version returns the value from the InitializeResult
  once one exists (negotiated for stateful, the pin for stateless via the
  synthesized result), falling back to the pin only before the handshake.
  A stateful pin is the requested version, not a guarantee of the negotiated
  one; inbound validation now keys off what the server actually agreed to.
- Reword lifecycle:stateless:caller-meta-preserved: the three envelope keys
  overwrite caller-supplied values for those keys; non-colliding caller keys
  are preserved. The capstone now passes a colliding key and the wire snapshot
  proves the overwrite.

Author: maxisbey

src/mcp/client/session.py

@@ -351,10 +351,14 @@ def initialize_result(self) -> types.InitializeResult | None:
 
     @property
     def protocol_version(self) -> str | None:
-        """Negotiated or pinned protocol version. None until initialize() unless pinned at construction."""
-        if self._pinned_version is not None:
-            return self._pinned_version
-        return self._initialize_result.protocol_version if self._initialize_result else None
+        """Negotiated or pinned protocol version. None until initialize() unless pinned at construction.
+
+        Once `initialize()` has completed, this is the version the server actually
+        negotiated (which can differ from a stateful pin); before that, the pin.
+        """
+        if self._initialize_result is not None:
+            return self._initialize_result.protocol_version
+        return self._pinned_version
 
     async def send_ping(self, *, meta: RequestParamsMeta | None = None) -> types.EmptyResult:
         """Send a ping request."""

tests/client/test_session.py

@@ -1432,8 +1432,10 @@ async def do_initialize() -> None:
             assert isinstance(out.message, JSONRPCRequest)
             assert out.message.params is not None
             assert out.message.params["protocolVersion"] == "2025-06-18"
+            assert session.protocol_version == "2025-06-18"
+            # Server negotiates a different (older) supported version than the pin requested.
             result = InitializeResult(
-                protocol_version="2025-06-18",
+                protocol_version="2025-03-26",
                 capabilities=ServerCapabilities(),
                 server_info=Implementation(name="mock-server", version="0.1.0"),
             )
@@ -1450,6 +1452,8 @@ async def do_initialize() -> None:
         # measures only what the second initialize() emits.
         notif = await from_client.receive()
         assert isinstance(notif.message, JSONRPCNotification)
+        # The property reports the negotiated version, not the pin, once the handshake is done.
+        assert session.protocol_version == "2025-03-26"
         # A second call returns the cached result without a second handshake frame.
         again = await session.initialize()
         assert again is first[0]

tests/interaction/_requirements.py

@@ -379,7 +379,8 @@ def __post_init__(self) -> None:
         source=f"{SPEC_2026_BASE_URL}/basic/lifecycle#stateless-operation",
         behavior=(
             "Caller-supplied _meta keys on a request survive the per-request envelope merge: the "
-            "io.modelcontextprotocol/* keys are added alongside, never overwriting the caller's keys."
+            "three io.modelcontextprotocol/* envelope keys overwrite any caller-supplied values for "
+            "those keys; non-colliding caller keys are preserved."
         ),
         added_in="2026-07-28",
     ),

tests/interaction/transports/test_hosting_http_modern.py

@@ -240,7 +240,11 @@ async def on_response(response: httpx.Response) -> None:
             ),
             ClientSession(read, write, client_info=client_info, protocol_version=MODERN_VERSION) as session,
         ):
-            result = await session.call_tool("add", {"a": 2, "b": 3}, meta={"custom-key": "x"})
+            result = await session.call_tool(
+                "add",
+                {"a": 2, "b": 3},
+                meta={"custom-key": "x", "io.modelcontextprotocol/protocolVersion": "evil"},
+            )
 
     assert result.model_dump(by_alias=True, mode="json", exclude_none=True) == snapshot(
         {"content": [{"type": "text", "text": "5"}], "isError": False, "resultType": "complete"}
@@ -254,8 +258,8 @@ async def on_response(response: httpx.Response) -> None:
     )
     assert all("initialize" not in body["method"] for body in bodies)
 
-    # The tools/call POST carries the body-derived headers, and its _meta envelope merges the
-    # caller's key alongside the three io.modelcontextprotocol/* keys.
+    # The tools/call POST carries the body-derived headers, and its _meta envelope overwrites the
+    # caller's colliding io.modelcontextprotocol/* key while preserving the non-colliding caller key.
     call = requests[0]
     assert {k: v for k, v in call.headers.items() if k.startswith("mcp-")} == snapshot(
         {"mcp-protocol-version": "2026-07-28", "mcp-method": "tools/call", "mcp-name": "add"}