Address extension-API review: layering, enforcement, version gating, Apps fixes

Framework:
- Move the Extension base class from mcp/server/mcpserver/extension.py to
  mcp/server/extension.py so helper-tier modules (apps.py) and third-party
  extensions depend on the base, not the composition tier.
- Enforce a vendor-prefix/name identifier via __init_subclass__ (and at apply
  time for per-instance identifiers), failing at class-definition rather than
  late with AttributeError.
- Add MethodBinding.protocol_versions so an extension method can be scoped to
  specific wire versions; out-of-range requests get METHOD_NOT_FOUND.
- Add require_client_extension(ctx, identifier) raising the -32021 missing
  required client capability error with a requiredCapabilities payload.

Apps:
- client_supports_apps now checks the client advertised the
  text/html;profile=mcp-app MIME type, not just the extension key.
- Add a visibility kwarg to @apps.tool (_meta.ui.visibility).
- Let add_html_resource set csp/permissions/domain/prefers_border on the
  resource _meta via typed ResourceCsp/ResourcePermissions models.
- Fix the meta= double-keyword TypeError by making meta an explicit param
  merged with the ui entry instead of passing through **tool_kwargs.

Author: Kludex

docs/migration.md

@@ -411,9 +411,10 @@ For protocol 2026-07-28 over Streamable HTTP, a tool's input-schema property may
 
 `MCPServer` now accepts opt-in extensions that bundle MCP behaviour behind a
 reverse-DNS identifier and advertise it under `ServerCapabilities.extensions`
-(the 2026-07-28 capability map). An extension subclasses `mcp.server.mcpserver.Extension`
+(the 2026-07-28 capability map). An extension subclasses `mcp.server.extension.Extension`
 and overrides only the contribution methods it needs: `tools()`/`resources()`/`methods()`
-(additive) and `intercept_tool_call()` (wraps `tools/call`). Pass instances at
+(additive) and `intercept_tool_call()` (wraps `tools/call`). The `identifier` must be a
+`vendor-prefix/name` string, enforced when the subclass is defined. Pass instances at
 construction:
 
 ```python
@@ -425,7 +426,14 @@ mcp = MCPServer("demo", extensions=[Apps()])
 
 The reference extension is `mcp.server.apps.Apps` (`io.modelcontextprotocol/ui`):
 it binds a tool to a `ui://` UI resource via `_meta.ui.resourceUri`, and
-`client_supports_apps(ctx)` gates the SEP-2133 text-only fallback.
+`client_supports_apps(ctx)` gates the SEP-2133 text-only fallback (checking the
+client advertised the `text/html;profile=mcp-app` MIME type).
+
+A `MethodBinding` may set `protocol_versions` to scope an extension method to
+specific wire versions; a request at any other version is `METHOD_NOT_FOUND`. An
+extension handler can call `mcp.server.mcpserver.require_client_extension(ctx, identifier)`
+to reject a request with the `-32021` (missing required client capability) error
+when the client did not declare the extension.
 
 Clients advertise extension support with the new `Client(extensions=...)` /
 `ClientSession(extensions=...)` argument, mirrored into `ClientCapabilities.extensions`.

src/mcp/server/apps.py

@@ -4,7 +4,7 @@
 `_meta.ui.resourceUri` points at a `ui://` resource (an HTML document served
 with the `text/html;profile=mcp-app` MIME type) that the host renders in a
 sandboxed iframe. See https://modelcontextprotocol.io/specification/draft/extensions/apps
-and SEP-2133 for the extension framework.
+and the ext-apps spec for the wire format, and SEP-2133 for the extension framework.
 
 This is a self-contained, additive `Extension`: it contributes tools and
 resources and advertises the capability, but does not intercept any core method.
@@ -22,17 +22,22 @@ def get_time(ctx: Context) -> str:
 
 Per SEP-2133, an extension MUST degrade gracefully: a UI-enabled tool should
 still return meaningful text for clients that did not negotiate Apps. Use
-`client_supports_apps(ctx)` to branch on the client's advertised support.
+`client_supports_apps(ctx)` to branch on the client's advertised support. (The SDK
+keeps Apps in-core under `mcp.server.apps` rather than a separate package; the
+TypeScript and C# SDKs ship it as a standalone package.)
 """
 
 from __future__ import annotations
 
 from collections.abc import Callable, Sequence
-from typing import Any, TypeVar
+from typing import Any, Literal, TypeVar
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
 
 from mcp.server.context import ServerRequestContext
+from mcp.server.extension import Extension, ResourceBinding, ToolBinding
 from mcp.server.mcpserver.context import Context
-from mcp.server.mcpserver.extension import Extension, ResourceBinding, ToolBinding
 from mcp.server.mcpserver.resources import TextResource
 
 EXTENSION_ID = "io.modelcontextprotocol/ui"
@@ -41,9 +46,34 @@ def get_time(ctx: Context) -> str:
 APP_MIME_TYPE = "text/html;profile=mcp-app"
 """MIME type for a `ui://` app resource."""
 
+Visibility = Literal["model", "app"]
+"""Where a UI-bound tool is surfaced (`_meta.ui.visibility`)."""
+
 _CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
 
 
+class ResourcePermissions(BaseModel):
+    """Iframe permissions a `ui://` resource requests (`_meta.ui.permissions`)."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    camera: dict[str, Any] | None = None
+    microphone: dict[str, Any] | None = None
+    geolocation: dict[str, Any] | None = None
+    clipboard_write: dict[str, Any] | None = None
+
+
+class ResourceCsp(BaseModel):
+    """Content-Security-Policy domains for a `ui://` resource (`_meta.ui.csp`)."""
+
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True)
+
+    connect_domains: list[str] | None = None
+    resource_domains: list[str] | None = None
+    frame_domains: list[str] | None = None
+    base_uri_domains: list[str] | None = None
+
+
 class Apps(Extension):
     """The MCP Apps extension: bind tools to `ui://` UI resources.
 
@@ -58,23 +88,36 @@ def __init__(self) -> None:
         self._tools: list[ToolBinding] = []
         self._resources: list[ResourceBinding] = []
 
-    def tool(self, *, resource_uri: str, **tool_kwargs: Any) -> Callable[[_CallableT], _CallableT]:
+    def tool(
+        self,
+        *,
+        resource_uri: str,
+        visibility: Sequence[Visibility] | None = None,
+        meta: dict[str, Any] | None = None,
+        **tool_kwargs: Any,
+    ) -> Callable[[_CallableT], _CallableT]:
         """Decorator registering a tool bound to a `ui://` resource.
 
-        Stamps `_meta.ui.resourceUri` on the tool. `tool_kwargs` are forwarded to
-        `MCPServer.add_tool` (name, title, description, annotations, ...).
+        Stamps `_meta.ui.resourceUri` (and `_meta.ui.visibility` when given) on the
+        tool. `tool_kwargs` are forwarded to `MCPServer.add_tool` (name, title,
+        description, annotations, ...); pass `meta=` to merge extra `_meta` keys
+        alongside the `ui` entry.
 
         Args:
             resource_uri: The `ui://` URI of the UI resource this tool renders.
+            visibility: Where the tool is surfaced (`["model", "app"]`).
+            meta: Additional `_meta` keys to merge with the `ui` entry.
 
         Raises:
             ValueError: If `resource_uri` does not use the `ui://` scheme.
         """
         _require_ui_scheme(resource_uri)
+        ui: dict[str, Any] = {"resourceUri": resource_uri}
+        if visibility is not None:
+            ui["visibility"] = list(visibility)
 
         def decorator(fn: _CallableT) -> _CallableT:
-            meta = {"ui": {"resourceUri": resource_uri}}
-            self._tools.append(ToolBinding(fn=fn, meta=meta, kwargs=tool_kwargs))
+            self._tools.append(ToolBinding(fn=fn, meta={**(meta or {}), "ui": ui}, kwargs=tool_kwargs))
             return fn
 
         return decorator
@@ -87,9 +130,16 @@ def add_html_resource(
         name: str | None = None,
         title: str | None = None,
         description: str | None = None,
+        csp: ResourceCsp | None = None,
+        permissions: ResourcePermissions | None = None,
+        domain: str | None = None,
+        prefers_border: bool | None = None,
     ) -> None:
         """Register a `ui://` HTML resource served as `text/html;profile=mcp-app`.
 
+        `csp`, `permissions`, `domain`, and `prefers_border` populate the
+        resource's `_meta.ui` per the ext-apps spec.
+
         Args:
             uri: The `ui://` URI; a tool references it via `resource_uri`.
             html: The HTML document the host renders.
@@ -98,12 +148,22 @@ def add_html_resource(
             ValueError: If `uri` does not use the `ui://` scheme.
         """
         _require_ui_scheme(uri)
+        ui: dict[str, Any] = {}
+        if csp is not None:
+            ui["csp"] = csp.model_dump(by_alias=True, exclude_none=True)
+        if permissions is not None:
+            ui["permissions"] = permissions.model_dump(by_alias=True, exclude_none=True)
+        if domain is not None:
+            ui["domain"] = domain
+        if prefers_border is not None:
+            ui["prefersBorder"] = prefers_border
         resource = TextResource(
             uri=uri,
             name=name or uri,
             title=title,
             description=description,
             mime_type=APP_MIME_TYPE,
+            meta={"ui": ui} if ui else None,
             text=html,
         )
         self._resources.append(ResourceBinding(resource=resource))
@@ -118,12 +178,17 @@ def resources(self) -> Sequence[ResourceBinding]:
 def client_supports_apps(ctx: Context[Any] | ServerRequestContext[Any, Any]) -> bool:
     """Whether the connected client negotiated MCP Apps support.
 
-    Returns `False` when the client did not advertise the extension (or sent no
-    capabilities), so a UI-enabled tool can fall back to text-only output.
+    Returns `True` only when the client advertised the extension AND listed the
+    `text/html;profile=mcp-app` MIME type in its settings, so a UI-enabled tool
+    can fall back to text-only output otherwise.
     """
     capabilities = _client_capabilities(ctx)
     extensions = capabilities.extensions if capabilities else None
-    return bool(extensions and EXTENSION_ID in extensions)
+    settings = extensions.get(EXTENSION_ID) if extensions else None
+    if settings is None:
+        return False
+    mime_types = settings.get("mimeTypes")
+    return mime_types is None or APP_MIME_TYPE in mime_types
 
 
 def _client_capabilities(ctx: Context[Any] | ServerRequestContext[Any, Any]) -> Any:

src/mcp/server/mcpserver/extension.py src/mcp/server/extension.pysrc/mcp/server/mcpserver/extension.py renamed to src/mcp/server/extension.py

@@ -1,32 +1,55 @@
-"""Pluggable extension interface for `MCPServer` (SEP-2133).
+"""Pluggable extension interface for MCP servers (SEP-2133).
 
 An extension is a self-contained, opt-in bundle of MCP behaviour, identified by
-a reverse-DNS string (e.g. `io.modelcontextprotocol/ui`). It is passed at
-construction - `MCPServer(..., extensions=[Apps(), Tasks(store)])` - and the
-server applies a *closed* set of contribution kinds: tools, resources, new
-request methods, and one `tools/call` interceptor. The server never hands itself
-to an extension; the extension declares what it adds, and the server consumes it.
-
-The shape follows the HTTPX `Transport`/`Auth` pattern: a narrow base class
-whose methods have sensible defaults, so an extension overrides only what it
-needs. A purely additive extension (Apps) overrides `tools`/`resources`; an
-interceptive one (Tasks) overrides `methods`/`intercept_tool_call`.
+a reverse-DNS string (e.g. `io.modelcontextprotocol/ui`). It is passed to
+`MCPServer(extensions=[...])`, and the server applies a *closed* set of
+contribution kinds: tools, resources, new request methods, and one `tools/call`
+interceptor. The server never hands itself to an extension; the extension
+declares what it adds, and the server consumes it.
+
+The shape follows the HTTPX `Transport`/`Auth` pattern: a narrow base class whose
+methods have sensible defaults, so an extension overrides only what it needs. A
+purely additive extension (Apps) overrides `tools`/`resources`; an interceptive
+one overrides `methods`/`intercept_tool_call`.
+
+This module lives at the `mcp.server` tier (not `mcp.server.mcpserver`) so that
+third-party extensions and helper modules like `mcp.server.apps` depend only on
+the base class, never on the composition tier that consumes it.
 """
 
 from __future__ import annotations
 
+import re
 from collections.abc import Awaitable, Callable, Sequence
 from dataclasses import dataclass, field
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from mcp_types import CallToolRequestParams
 from pydantic import BaseModel
 
 from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
-from mcp.server.mcpserver.resources import Resource
+
+if TYPE_CHECKING:
+    from mcp.server.mcpserver.resources import Resource
 
 RequestHandler = Callable[[ServerRequestContext[Any, Any], Any], Awaitable[HandlerResult]]
 
+# Extension identifiers follow the `_meta` key grammar: a mandatory reverse-DNS
+# prefix, a slash, then the extension name (SEP-2133 / the spec's _meta rules).
+_IDENTIFIER_RE = re.compile(r"^[A-Za-z0-9.-]+/[A-Za-z0-9._-]+$")
+
+
+def validate_extension_identifier(identifier: Any, *, owner: str) -> None:
+    """Raise `TypeError` unless `identifier` is a `vendor-prefix/name` string.
+
+    SEP-2133 requires extension identifiers to carry a reverse-DNS prefix.
+    """
+    if not isinstance(identifier, str) or not _IDENTIFIER_RE.match(identifier):
+        raise TypeError(
+            f"{owner}.identifier must be a `vendor-prefix/name` string "
+            f"(reverse-DNS prefix required), got {identifier!r}"
+        )
+
 
 @dataclass(frozen=True)
 class ToolBinding:
@@ -49,25 +72,41 @@ class MethodBinding:
     """A new request method an extension serves, e.g. `tasks/get`.
 
     `params_type` validates incoming params before `handler` runs; it should
-    subclass `RequestParams` so `_meta` parses uniformly.
+    subclass `RequestParams` so `_meta` parses uniformly. `protocol_versions`,
+    when set, restricts the method to those wire versions - a request for the
+    method at any other version is rejected as `METHOD_NOT_FOUND`, mirroring the
+    spec's `(method, version)` boundary table. `None` (the default) admits the
+    method at every version.
     """
 
     method: str
     params_type: type[BaseModel]
     handler: RequestHandler
+    protocol_versions: frozenset[str] | None = None
 
 
 class Extension:
     """Base class for an opt-in MCP extension. Override only the methods you need.
 
     Subclass and set `identifier`, then override the contribution methods that
     apply. Every method has a default, so a minimal extension overrides nothing
-    but `identifier` and one of `tools`/`resources`/`methods`.
+    but `identifier` and one of `tools`/`resources`/`methods`. `identifier` is
+    enforced at subclass-definition time.
     """
 
     #: Reverse-DNS extension identifier, advertised under `ServerCapabilities.extensions`.
     identifier: str
 
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # Validate a class-level `identifier` at definition time. A subclass may
+        # instead assign `identifier` in `__init__` (per-instance ids); that case
+        # is validated when the extension is applied, since no class attribute
+        # exists to inspect here.
+        identifier = cls.__dict__.get("identifier")
+        if identifier is not None:
+            validate_extension_identifier(identifier, owner=cls.__name__)
+
     def settings(self) -> dict[str, Any]:
         """Per-extension settings advertised at `capabilities.extensions[identifier]`.
 

src/mcp/server/mcpserver/__init__.py

@@ -2,10 +2,11 @@
 
 from mcp_types import Icon
 
+from mcp.server.extension import Extension, MethodBinding, ResourceBinding, ToolBinding
+
 from .context import Context
-from .extension import Extension, MethodBinding, ResourceBinding, ToolBinding
 from .resources import DEFAULT_RESOURCE_SECURITY, ResourceSecurity
-from .server import MCPServer
+from .server import MCPServer, require_client_extension
 from .utilities.types import Audio, Image
 
 __all__ = [
@@ -18,6 +19,7 @@
     "ToolBinding",
     "ResourceBinding",
     "MethodBinding",
+    "require_client_extension",
     "ResourceSecurity",
     "DEFAULT_RESOURCE_SECURITY",
 ]