Accept modern envelope without the optional clientInfo key (spec PR #3002)

Spec PR #3002 made io.modelcontextprotocol/clientInfo optional
(SHOULD-include): the required per-request envelope is now the
protocolVersion + clientCapabilities pair.

- classify_inbound_request rung 1 demands the pair and reads absent
  clientInfo as None; a missing required key rejects -32602 with a
  message naming the key(s), per basic/index.mdx.
- Era evidence on the stdio dual-era loop is now presence of the
  reserved protocolVersion _meta key alone: the io.modelcontextprotocol/
  prefix is spec-reserved, so legacy traffic never mints it, and a
  half-built envelope (version without capabilities) routes modern to
  get the classifier's named rejection instead of the legacy path's
  generic one. Failed classification still locks no era.
- The regenerated surface types (previous commit) already carry the
  optional clientInfo on RequestMetaObject.
- Connection records client_capabilities as its own fact so capability
  checks (check_capability, sampling tools validation, extension and
  apps gates) work for pair-only requests; the client_params setter
  keeps the two in lockstep on the handshake path. ServerSession
  exposes client_capabilities and all capability consumers read it.
- The Mcp-Param schema-resolving tools/list walk omits the clientInfo
  key from its synthetic envelope when the caller sent none.

Author: maxisbey

src/mcp/server/_streamable_http_modern.py

@@ -218,9 +218,11 @@ async def _tool_input_schema(
     """
     meta = {
         PROTOCOL_VERSION_META_KEY: verdict.protocol_version,
-        CLIENT_INFO_META_KEY: verdict.client_info,
         CLIENT_CAPABILITIES_META_KEY: verdict.client_capabilities,
     }
+    if verdict.client_info is not None:
+        # Optional key: a conforming pair-only caller omits it rather than sending null.
+        meta[CLIENT_INFO_META_KEY] = verdict.client_info
     list_params: dict[str, Any] = {"_meta": meta}
     try:
         _methods.validate_client_request("tools/list", verdict.protocol_version, list_params)

src/mcp/server/apps.py

@@ -233,8 +233,7 @@ def client_supports_apps(ctx: Context[Any] | ServerRequestContext[Any, Any]) ->
 def _client_capabilities(ctx: Context[Any] | ServerRequestContext[Any, Any]) -> Any:
     if isinstance(ctx, Context):
         return ctx.client_capabilities
-    client_params = ctx.session.client_params
-    return client_params.capabilities if client_params else None
+    return ctx.session.client_capabilities
 
 
 def _require_ui_scheme(uri: str) -> None:

src/mcp/server/connection.py

@@ -147,9 +147,13 @@ class Connection:
 
     session_id: str | None
 
-    client_params: InitializeRequestParams | None
-    """The full `initialize` request params, or the equivalent built from the
-    2026-era envelope. `None` when no client info was supplied."""
+    client_capabilities: ClientCapabilities | None
+    """The capabilities the peer declared: the handshake's on the loop path,
+    the request envelope's on the modern path. `None` when none were declared.
+    Kept in lockstep with `client_params` by its setter, and settable on its
+    own for the modern envelope, where capabilities are required but client
+    info is optional (spec PR #3002) - capability checks must not depend on the
+    peer having identified itself."""
 
     protocol_version: str
     """The protocol version this connection speaks. Populated at construction
@@ -180,11 +184,29 @@ def __init__(
         self.outbound = outbound
         self.protocol_version = protocol_version
         self.session_id = session_id
+        self.client_capabilities = None
         self.client_params = client_params
         self.initialized = anyio.Event()
         self.state = {}
         self.exit_stack = AsyncExitStack()
 
+    @property
+    def client_params(self) -> InitializeRequestParams | None:
+        """The full `initialize` request params, or the equivalent built from the
+        2026-era envelope. `None` when no client info was supplied."""
+        return self._client_params
+
+    @client_params.setter
+    def client_params(self, value: InitializeRequestParams | None) -> None:
+        # Assignment is the sync point: recording full client params (the
+        # handshake commit, or a modern envelope carrying client info) also
+        # records the capabilities fact, so the two can never drift. Clearing
+        # to `None` leaves `client_capabilities` alone - the modern envelope
+        # declares capabilities without client info.
+        self._client_params = value
+        if value is not None:
+            self.client_capabilities = value.capabilities
+
     @classmethod
     def from_envelope(
         cls,
@@ -201,13 +223,15 @@ def from_envelope(
         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.
+        not-supplied rather than failing the request. `initialized` is set,
+        well-formed capabilities are recorded as `client_capabilities` (client
+        info is optional per spec PR #3002, so capability checks never depend on
+        it), and the full `client_params` is additionally synthesized when
+        client info was supplied too. `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)
@@ -219,6 +243,7 @@ def from_envelope(
                 client_info=info,
             )
         connection = cls(outbound, protocol_version=protocol_version, client_params=client_params)
+        connection.client_capabilities = capabilities
         connection.initialized.set()
         return connection
 
@@ -369,13 +394,13 @@ async def send_resource_updated(self, uri: str, *, meta: Meta | None = None) ->
     def check_capability(self, capability: ClientCapabilities) -> bool:
         """Return whether the connected client declared the given capability.
 
-        Returns `False` when no client info has been recorded.
+        Returns `False` when no capabilities have been recorded.
         """
         # TODO(L53): redesign - mirrors v1 ServerSession.check_client_capability
         # verbatim for parity.
-        if self.client_params is None:
+        if self.client_capabilities is None:
             return False
-        have = self.client_params.capabilities
+        have = self.client_capabilities
         if capability.roots is not None:
             if have.roots is None:
                 return False

src/mcp/server/mcpserver/context.py

@@ -326,11 +326,11 @@ def request_state(self) -> str | None:
     def client_capabilities(self) -> ClientCapabilities | None:
         """The client's declared capabilities for this connection.
 
-        `None` when the client supplied no client info (e.g. an anonymous
-        stateless request without the reserved `_meta` keys).
+        `None` when the client declared none (e.g. an anonymous stateless
+        request without the reserved `_meta` keys). Client info is not
+        required for capabilities to be recorded.
         """
-        client_params = self.request_context.session.client_params
-        return client_params.capabilities if client_params else None
+        return self.request_context.session.client_capabilities
 
     @property
     def session(self):

src/mcp/server/mcpserver/server.py

@@ -1320,8 +1320,8 @@ def require_client_extension(ctx: ServerRequestContext[Any, Any], identifier: st
         MCPError: With code `MISSING_REQUIRED_CLIENT_CAPABILITY` if the client
             did not advertise `identifier`.
     """
-    client_params = ctx.session.client_params
-    declared = client_params.capabilities.extensions if client_params else None
+    capabilities = ctx.session.client_capabilities
+    declared = capabilities.extensions if capabilities else None
     if not declared or identifier not in declared:
         data = MissingRequiredClientCapabilityErrorData(
             required_capabilities=ClientCapabilities(extensions={identifier: {}})

src/mcp/server/runner.py

@@ -439,19 +439,23 @@ async def serve_loop(
     )
 
 
-_MODERN_ENVELOPE_KEYS = (PROTOCOL_VERSION_META_KEY, CLIENT_INFO_META_KEY, CLIENT_CAPABILITIES_META_KEY)
-
-
 def _has_modern_envelope(params: Mapping[str, Any] | None) -> bool:
-    """Whether `params._meta` carries every reserved modern-envelope key.
-
-    Era evidence is the FULL key triple - bare `_meta` is not (legacy traffic
-    carries `progressToken` there).
+    """Whether `params._meta` carries the reserved protocol-version key.
+
+    Era evidence is the client's explicit version declaration: the
+    `io.modelcontextprotocol/protocolVersion` key exists only in 2026-07-28+
+    envelopes, and the `io.modelcontextprotocol/` prefix is spec-reserved, so
+    legacy traffic never mints it (bare `_meta` is NOT evidence - legacy
+    requests carry `progressToken` there). Presence of the version key alone
+    is the rule, not the full required pair, so a half-built envelope
+    (version present, capabilities missing) still routes modern and gets the
+    classifier's INVALID_PARAMS naming the missing key instead of the legacy
+    path's generic one - and, like every failed classification, locks no era.
     """
     if not params:
         return False
     meta = params.get("_meta")
-    return isinstance(meta, Mapping) and all(key in meta for key in _MODERN_ENVELOPE_KEYS)
+    return isinstance(meta, Mapping) and PROTOCOL_VERSION_META_KEY in meta
 
 
 def _initialize_after_modern_data(params: Mapping[str, Any] | None) -> dict[str, Any]:
@@ -557,8 +561,8 @@ async def serve_dual_era_loop(
       like `serve_loop` for its lifetime, and modern envelope traffic is then
       rejected with INVALID_REQUEST. `initialize` never routes modern - the
       method is legacy-distinctive by definition - even when a confused
-      client stamps the envelope triple on it.
-    - A request carrying the modern `_meta` envelope triple - or
+      client stamps the envelope keys on it.
+    - A request whose `_meta` declares the modern protocol version - or
       `server/discover`, a modern-only method - is classified
       (`classify_inbound_request`) and served single-exchange via `serve_one`
       with a born-ready per-request `Connection`, the same dispatch model as
@@ -676,7 +680,7 @@ async def on_request(
             return await serve_modern(dctx, method, params)
         # Unlocked. `initialize` is legacy-distinctive by definition (the
         # method does not exist at modern versions), so it takes the handshake
-        # path even when the envelope triple is stamped on it.
+        # path even when the envelope keys are stamped on it.
         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)

src/mcp/server/session.py

@@ -45,6 +45,16 @@ def client_params(self) -> types.InitializeRequestParams | None:
         """The client's `initialize` request params; `None` when no client info was supplied."""
         return self._connection.client_params
 
+    @property
+    def client_capabilities(self) -> types.ClientCapabilities | None:
+        """The capabilities the client declared; `None` when none were declared.
+
+        Prefer this over `client_params.capabilities`: on 2026-07-28+ the
+        request envelope declares capabilities while client info stays
+        optional, so capabilities can be present without `client_params`.
+        """
+        return self._connection.client_capabilities
+
     @property
     def can_send_request(self) -> bool:
         """Whether this request's channel can currently deliver a server-initiated request."""
@@ -236,8 +246,7 @@ async def create_message(
             NoBackChannelError: The connection has no back-channel for
                 server-initiated requests.
         """
-        client_caps = self.client_params.capabilities if self.client_params else None
-        validate_sampling_tools(client_caps, tools, tool_choice)
+        validate_sampling_tools(self.client_capabilities, tools, tool_choice)
         validate_tool_use_result_messages(messages)
 
         request = types.CreateMessageRequest(

src/mcp/shared/inbound.py

@@ -327,9 +327,10 @@ def _value_at_path(arguments: Mapping[str, Any], path: tuple[str, ...]) -> Any:
 class InboundModernRoute:
     """A modern-protocol request whose envelope passed every ladder rung.
 
-    `client_info` and `client_capabilities` are the raw envelope values;
-    the classifier checks presence only, not shape. Method existence is not a
-    ladder rung — kernel dispatch is the single source of truth for that.
+    `client_info` and `client_capabilities` are the raw envelope values; the
+    classifier checks presence only, not shape, and `client_info` is `None`
+    when the (optional, SHOULD-include) key is absent. Method existence is not
+    a ladder rung — kernel dispatch is the single source of truth for that.
     """
 
     protocol_version: str
@@ -376,9 +377,11 @@ 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) → else
-       :data:`~mcp_types.jsonrpc.INVALID_PARAMS`.
+    1. `params._meta` is a mapping carrying the required envelope pair
+       (protocol version, client capabilities) → else
+       :data:`~mcp_types.jsonrpc.INVALID_PARAMS` naming the missing key(s)
+       (basic/index.mdx "Per-request protocol fields"). Client info is
+       optional (SHOULD-include, spec PR #3002); absent reads as `None`.
     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
@@ -404,16 +407,24 @@ def classify_inbound_request(
             accepts on the per-request-envelope path.
     """
     try:
-        meta = body["params"]["_meta"]
-        protocol_version = meta[PROTOCOL_VERSION_META_KEY]
-        client_info = meta[CLIENT_INFO_META_KEY]
-        client_capabilities = meta[CLIENT_CAPABILITIES_META_KEY]
+        meta_value = body["params"]["_meta"]
     except (KeyError, TypeError):
+        meta_value = None
+    if not isinstance(meta_value, Mapping):
         return InboundLadderRejection(
             code=INVALID_PARAMS,
-            message="params._meta must carry the reserved protocol-version, client-info and "
-            "client-capabilities envelope keys",
+            message="params._meta must be an object carrying the required "
+            f"{PROTOCOL_VERSION_META_KEY!r} and {CLIENT_CAPABILITIES_META_KEY!r} envelope keys",
         )
+    meta = cast("Mapping[str, Any]", meta_value)
+    if missing := [key for key in (PROTOCOL_VERSION_META_KEY, CLIENT_CAPABILITIES_META_KEY) if key not in meta]:
+        return InboundLadderRejection(
+            code=INVALID_PARAMS,
+            message=f"params._meta is missing the required envelope key(s): {', '.join(missing)}",
+        )
+    protocol_version: Any = meta[PROTOCOL_VERSION_META_KEY]
+    client_info: Any = meta.get(CLIENT_INFO_META_KEY)
+    client_capabilities: Any = meta[CLIENT_CAPABILITIES_META_KEY]
     if headers is not None:
         version_header = headers.get(MCP_PROTOCOL_VERSION_HEADER)
         # Presence is checked explicitly: a null body version would otherwise
@@ -431,8 +442,8 @@ def classify_inbound_request(
             )
         name_key = NAME_BEARING_METHODS.get(method)
         if name_key is not None:
-            # Rung 1 already proved body["params"] is a mapping.
-            body_value = body["params"].get(name_key)
+            # Rung 1 already proved body["params"] is a mapping (its `_meta` is one).
+            body_value = cast("Mapping[str, Any]", body["params"]).get(name_key)
             if body_value is not None and decode_header_value(headers.get(MCP_NAME_HEADER)) != body_value:
                 return InboundLadderRejection(
                     code=HEADER_MISMATCH,

tests/server/test_connection.py

@@ -22,6 +22,7 @@
     ElicitationCapability,
     EmptyResult,
     Implementation,
+    InitializeRequestParams,
     ListRootsRequest,
     ListRootsResult,
     PingRequest,
@@ -321,15 +322,42 @@ async def test_connection_send_tool_list_changed_with_meta_includes_meta_only_pa
 # --- check_capability ----------------------------------------------------------
 
 
-def test_connection_check_capability_false_when_no_client_params_recorded():
-    """SDK-defined: `check_capability` returns False when no `client_params`
+def test_connection_check_capability_false_when_no_capabilities_recorded():
+    """SDK-defined: `check_capability` returns False when no capabilities
     were recorded, regardless of which factory built the connection."""
     conn = Connection.for_loop(StubOutbound())
     assert conn.check_capability(ClientCapabilities(sampling=SamplingCapability())) is False
     # Same for a born-ready connection that supplied neither info nor caps.
     assert Connection.from_envelope(LATEST_MODERN_VERSION, None, None).check_capability(ClientCapabilities()) is False
 
 
+def test_from_envelope_records_capabilities_without_client_info():
+    """Spec-mandated (spec PR #3002): the envelope requires capabilities but not
+    client info, so a pair-only request still gets working capability checks -
+    `client_capabilities` is recorded on its own while `client_params` stays
+    `None`."""
+    caps = ClientCapabilities(sampling=SamplingCapability())
+    conn = Connection.from_envelope(LATEST_MODERN_VERSION, None, caps)
+    assert conn.client_params is None
+    assert conn.client_capabilities == caps
+    assert conn.check_capability(ClientCapabilities(sampling=SamplingCapability())) is True
+
+
+def test_client_params_assignment_keeps_capabilities_in_lockstep():
+    """SDK-defined: recording `client_params` (the loop path's handshake
+    commit) is the sync point that also records `client_capabilities`, so the
+    two facts cannot drift."""
+    conn = Connection.for_loop(StubOutbound())
+    assert conn.client_capabilities is None
+    conn.client_params = InitializeRequestParams(
+        protocol_version=LATEST_HANDSHAKE_VERSION,
+        capabilities=ClientCapabilities(roots=RootsCapability()),
+        client_info=Implementation(name="c", version="0"),
+    )
+    assert conn.client_capabilities == ClientCapabilities(roots=RootsCapability())
+    assert conn.check_capability(ClientCapabilities(roots=RootsCapability())) is True
+
+
 @pytest.mark.parametrize(
     ("have", "want", "expected"),
     [