Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Detect client extensions without requiring clientInfo (#5196)

Aleksandr Filippov50375b50ef8f
diff --git a/fastmcp_slim/fastmcp/server/context.py b/fastmcp_slim/fastmcp/server/context.py
index aa3f1ea5b..ed5e16467 100644
--- a/fastmcp_slim/fastmcp/server/context.py
+++ b/fastmcp_slim/fastmcp/server/context.py
@@ -658,15 +658,13 @@ class Context:
def client_supports_extension(self, extension_id: str) -> bool:
"""Check whether the connected client supports a given MCP extension.
- Inspects the ``extensions`` extra field on ``ClientCapabilities``
- sent by the client during initialization.
-
- Reads the client's advertised capabilities from the session, which is
- available in request mode and in background-task mode (where the
- snapshot session preserves the client's initialize params). Returns
- ``False`` when no session is available (e.g., a distributed worker with
- no live session, or outside any context) or when the client did not
- advertise the extension.
+ Inspects the ``extensions`` capability the client declared, read from
+ the session's ``client_capabilities``. The session is available in
+ request mode and in background-task mode, where the snapshot session
+ preserves the declared capabilities. Returns ``False`` when no session
+ is available (e.g., a distributed worker with no live session, or
+ outside any context) or when the client did not advertise the
+ extension.
Example::
diff --git a/fastmcp_slim/fastmcp/server/low_level.py b/fastmcp_slim/fastmcp/server/low_level.py
index cef3ad689..51176be28 100644
--- a/fastmcp_slim/fastmcp/server/low_level.py
+++ b/fastmcp_slim/fastmcp/server/low_level.py
@@ -111,25 +111,23 @@ def _forward_ctx(
def client_supports_extension(session: ServerSession, extension_id: str) -> bool:
"""Check whether the connected client supports a given MCP extension.
- Inspects the ``extensions`` capability on ``ClientCapabilities`` sent by the
- client during initialization. In v2 the client's initialize params are
- reachable via ``session.client_params``.
+ Inspects the ``extensions`` capability the client declared, read from
+ ``session.client_capabilities``. On 2026-07-28+ capabilities ride every
+ request's ``_meta`` envelope while client info stays optional, so
+ capabilities can be present while ``session.client_params`` is ``None``.
SDK v2 declares ``extensions`` as a real field on ``ClientCapabilities``, so
a client sending ``ClientCapabilities(extensions={...})`` populates the field
directly. We read that field first and fall back to ``model_extra`` only for
legacy-serialized clients that carried ``extensions`` as an extra key.
"""
- client_params = session.client_params
- if client_params is None:
- return False
- caps = client_params.capabilities
+ caps = session.client_capabilities
if caps is None:
return False
extensions: dict[str, Any] | None = caps.extensions
if extensions is None:
# Legacy fallback: clients that serialized `extensions` as an extra key
- # (ClientCapabilities uses extra="allow") rather than the real field.
+ # rather than the real field.
extras = caps.model_extra or {}
extensions = extras.get("extensions")
if not extensions:
diff --git a/tests/tasks/server/test_context_background_task.py b/tests/tasks/server/test_context_background_task.py
index bdc7b939d..85257a9f4 100644
--- a/tests/tasks/server/test_context_background_task.py
+++ b/tests/tasks/server/test_context_background_task.py
@@ -26,6 +26,7 @@ from fastmcp_tasks.context import (
from mcp import ServerSession
from mcp.server.auth.middleware.auth_context import auth_context_var
from mcp.server.auth.middleware.bearer_auth import AuthenticatedUser
+from mcp.server.connection import Connection
from mcp_types import (
ClientCapabilities,
Implementation,
@@ -236,35 +237,28 @@ class TestContextClientExtensionBackgroundTask:
"""Tests for Context.client_supports_extension() in background task mode.
A background task may carry a stored snapshot session but no request
- context. The client's advertised capabilities are preserved on the
- session's ``client_params``, so extension detection reads from the session
- rather than gating on ``request_context``.
+ context. The client's advertised capabilities are preserved on the stored
+ session, so extension detection reads from the session rather than gating
+ on ``request_context``.
"""
def _make_task_context(
self, mcp: FastMCP, extensions: dict[str, dict[str, Any]] | None
) -> Context:
- capabilities = ClientCapabilities(extensions=extensions)
- client_params = InitializeRequestParams(
+ connection = Connection.for_loop(
+ cast(Any, object()), protocol_version_hint="2025-06-18"
+ )
+ connection.client_params = InitializeRequestParams(
protocol_version="2025-06-18",
- capabilities=capabilities,
+ capabilities=ClientCapabilities(extensions=extensions),
client_info=Implementation(name="test-client", version="1.0"),
)
-
- class MockSession:
- _fastmcp_state_prefix = "session-ext"
-
- def __init__(self) -> None:
- self.client_params = client_params
-
- session = MockSession()
- return Context(
- mcp, session=cast(ServerSession, session), task_id="test-task-ext"
- )
+ session = ServerSession(cast(Any, object()), connection)
+ return Context(mcp, session=session, task_id="test-task-ext")
def test_background_task_detects_advertised_extension(self):
- """The stored session preserves the client's initialize params, so an
- advertised extension is detected even with no request context."""
+ """The stored session preserves the client's advertised capabilities,
+ so an advertised extension is detected even with no request context."""
mcp = FastMCP("test")
ctx = self._make_task_context(mcp, {"ext-abc": {}})
diff --git a/tests/test_apps.py b/tests/test_apps.py
index fe1491ed3..d3d884262 100644
--- a/tests/test_apps.py
+++ b/tests/test_apps.py
@@ -7,13 +7,14 @@ extension negotiation, and the ``Context.client_supports_extension`` method.
from __future__ import annotations
from types import SimpleNamespace
-from typing import Any
+from typing import Any, cast
import pytest
+from mcp.server.connection import Connection
+from mcp.server.session import ServerSession
from mcp_types import (
ClientCapabilities,
Implementation,
- InitializeRequestParams,
)
from fastmcp import Client, FastMCP
@@ -447,21 +448,28 @@ class TestClientSupportsExtension:
SDK v2 declares ``extensions`` as a real field on ``ClientCapabilities``, so
a client sending ``ClientCapabilities(extensions={...})`` populates the field
directly (``model_extra`` stays ``None``). The helper must read the real
- field, not only ``model_extra``.
+ field, not only ``model_extra``. It also covers the 2026-07-28 envelope,
+ where a client declares capabilities without ``clientInfo`` and the session
+ therefore has no ``client_params``.
"""
+ CLIENT_INFO = Implementation(name="test-client", version="1.0")
+
@staticmethod
def _session_with_capabilities(
capabilities: ClientCapabilities | None,
- ) -> Any:
- params: InitializeRequestParams | None = None
+ *,
+ client_info: Implementation | None,
+ ) -> ServerSession:
+ """Build a session over a 2026-07-28 request envelope."""
+ info = None
+ if client_info is not None:
+ info = client_info.model_dump(by_alias=True, mode="json")
+ caps = None
if capabilities is not None:
- params = InitializeRequestParams(
- protocol_version="2026-07-28",
- capabilities=capabilities,
- client_info=Implementation(name="test-client", version="1.0"),
- )
- return SimpleNamespace(client_params=params)
+ caps = capabilities.model_dump(by_alias=True, mode="json")
+ connection = Connection.from_envelope("2026-07-28", info, caps)
+ return ServerSession(cast(Any, object()), connection)
def test_real_extensions_field(self):
"""A client that sets the real `extensions` field is detected."""
@@ -469,14 +477,23 @@ class TestClientSupportsExtension:
# Guard: the regression this covers is the field being populated while
# model_extra stays empty.
assert caps.model_extra in (None, {})
- session = self._session_with_capabilities(caps)
+ session = self._session_with_capabilities(caps, client_info=self.CLIENT_INFO)
assert client_supports_extension(session, UI_EXTENSION_ID) is True
def test_real_extensions_field_without_target_extension(self):
caps = ClientCapabilities(extensions={"other/extension": {}})
- session = self._session_with_capabilities(caps)
+ session = self._session_with_capabilities(caps, client_info=self.CLIENT_INFO)
assert client_supports_extension(session, UI_EXTENSION_ID) is False
+ def test_extensions_without_client_info(self):
+ """clientInfo is optional on 2026-07-28 while clientCapabilities is not,
+ so a client can declare the extension with no client params on the
+ session to read it from."""
+ caps = ClientCapabilities(extensions={UI_EXTENSION_ID: {}})
+ session = self._session_with_capabilities(caps, client_info=None)
+ assert session.client_params is None
+ assert client_supports_extension(session, UI_EXTENSION_ID) is True
+
def test_legacy_model_extra_fallback(self):
"""Defensive fallback: capabilities whose real `extensions` field is None
but which carry `extensions` in `model_extra` are still detected.
@@ -489,18 +506,16 @@ class TestClientSupportsExtension:
extensions=None,
model_extra={"extensions": {UI_EXTENSION_ID: {}}},
)
- session: Any = SimpleNamespace(
- client_params=SimpleNamespace(capabilities=fake_caps)
- )
+ session: Any = SimpleNamespace(client_capabilities=fake_caps)
assert client_supports_extension(session, UI_EXTENSION_ID) is True
def test_no_extensions(self):
caps = ClientCapabilities()
- session = self._session_with_capabilities(caps)
+ session = self._session_with_capabilities(caps, client_info=self.CLIENT_INFO)
assert client_supports_extension(session, UI_EXTENSION_ID) is False
def test_no_capabilities(self):
- session = self._session_with_capabilities(None)
+ session = self._session_with_capabilities(None, client_info=self.CLIENT_INFO)
assert client_supports_extension(session, UI_EXTENSION_ID) is False