Address extension review: identifier grammar, additive-only methods, Apps checks

- Validate extension identifiers against the spec's _meta key grammar
  (per-label structure, fullmatch so a trailing newline cannot pass)
- Reject MethodBindings that name spec-defined request methods, collide
  with an already-registered handler, or pin an empty version set; the
  runner's per-version surface gate would never route those anyway
- client_supports_apps requires mimeTypes to list text/html;profile=mcp-app,
  matching the reference implementation; a missing key means unsupported
- Require every @apps.tool resource_uri to resolve to a resource registered
  on the Apps instance, failing at construction instead of 404ing on
  resources/read; add Apps.add_resource for pre-built ui:// resources
- Document the new construction-time errors in the migration guide

Author: maxisbey

docs/migration.md

@@ -414,8 +414,9 @@ reverse-DNS identifier and advertise it under `ServerCapabilities.extensions`
 (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`). The `identifier` must be a
-`vendor-prefix/name` string, enforced when the subclass is defined. Pass instances at
-construction:
+`vendor-prefix/name` string following the spec's `_meta` key grammar; a class-level
+`identifier` is validated when the subclass is defined, one assigned in `__init__` when
+the extension is registered. Pass instances at construction:
 
 ```python
 from mcp.server.mcpserver import MCPServer
@@ -426,11 +427,20 @@ 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 (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
+`client_supports_apps(ctx)` gates the SEP-2133 text-only fallback — `True` only
+when the client's ui-extension settings list the `text/html;profile=mcp-app`
+MIME type, per the Apps spec's required `mimeTypes` field. Every
+`@apps.tool(resource_uri=...)` must have a matching resource registered on the
+same `Apps` instance (`add_html_resource` for inline HTML, `add_resource` for a
+pre-built `Resource`); a tool bound to an unregistered URI raises at
+`MCPServer(...)` construction rather than 404ing on `resources/read` at runtime.
+
+Extension methods are strictly additive: a `MethodBinding` cannot name a
+spec-defined request method, and registering one whose method collides with
+another handler raises at construction. A `MethodBinding` may set
+`protocol_versions` to scope an extension method to specific wire versions
+(`frozenset()` is rejected — use `None` to admit every version); 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.

src/mcp/server/apps.py

@@ -38,7 +38,7 @@ def get_time(ctx: Context) -> str:
 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.resources import TextResource
+from mcp.server.mcpserver.resources import Resource, TextResource
 
 EXTENSION_ID = "io.modelcontextprotocol/ui"
 """The MCP Apps extension identifier (the shipped TS/C# constant)."""
@@ -85,7 +85,7 @@ class Apps(Extension):
     identifier = EXTENSION_ID
 
     def __init__(self) -> None:
-        self._tools: list[ToolBinding] = []
+        self._tools: list[tuple[ToolBinding, str]] = []  # (binding, bound resource_uri)
         self._resources: list[ResourceBinding] = []
 
     def tool(
@@ -117,7 +117,8 @@ def tool(
             ui["visibility"] = list(visibility)
 
         def decorator(fn: _CallableT) -> _CallableT:
-            self._tools.append(ToolBinding(fn=fn, meta={**(meta or {}), "ui": ui}, kwargs=tool_kwargs))
+            binding = ToolBinding(fn=fn, meta={**(meta or {}), "ui": ui}, kwargs=tool_kwargs)
+            self._tools.append((binding, resource_uri))
             return fn
 
         return decorator
@@ -147,7 +148,6 @@ def add_html_resource(
         Raises:
             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)
@@ -157,19 +157,48 @@ def add_html_resource(
             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.add_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,
+            )
         )
+
+    def add_resource(self, resource: Resource) -> None:
+        """Register a pre-built `ui://` resource.
+
+        The escape hatch for resources `add_html_resource` cannot express (e.g. a
+        `FileResource` serving HTML from disk). The resource should carry the
+        `text/html;profile=mcp-app` MIME type for hosts to render it.
+
+        Raises:
+            ValueError: If the resource URI does not use the `ui://` scheme.
+        """
+        _require_ui_scheme(resource.uri)
         self._resources.append(ResourceBinding(resource=resource))
 
     def tools(self) -> Sequence[ToolBinding]:
-        return self._tools
+        """The bound tools.
+
+        Raises:
+            ValueError: If a tool's `resource_uri` has no matching resource
+                registered on this instance — a tool advertising a
+                `_meta.ui.resourceUri` that 404s on `resources/read` is a
+                misconfiguration, caught when the server consumes the extension.
+        """
+        registered = {binding.resource.uri for binding in self._resources}
+        for tool, uri in self._tools:
+            if uri not in registered:
+                raise ValueError(
+                    f"Apps tool {tool.fn.__name__!r} binds resource_uri {uri!r}, but no such resource "
+                    "is registered; add it with add_html_resource() or add_resource()"
+                )
+        return [tool for tool, _ in self._tools]
 
     def resources(self) -> Sequence[ResourceBinding]:
         return self._resources
@@ -188,7 +217,7 @@ def client_supports_apps(ctx: Context[Any] | ServerRequestContext[Any, Any]) ->
     if settings is None:
         return False
     mime_types = settings.get("mimeTypes")
-    return mime_types is None or APP_MIME_TYPE in mime_types
+    return isinstance(mime_types, list | tuple) and APP_MIME_TYPE in mime_types
 
 
 def _client_capabilities(ctx: Context[Any] | ServerRequestContext[Any, Any]) -> Any:

src/mcp/server/extension.py

@@ -12,9 +12,9 @@
 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.
+This module lives at the `mcp.server` tier (not `mcp.server.mcpserver`) so the
+base class itself never drags in the composition tier that consumes it;
+extensions remain importable without constructing an `MCPServer`.
 """
 
 from __future__ import annotations
@@ -25,6 +25,7 @@
 from typing import TYPE_CHECKING, Any
 
 from mcp_types import CallToolRequestParams
+from mcp_types.methods import SPEC_CLIENT_METHODS
 from pydantic import BaseModel
 
 from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
@@ -34,17 +35,21 @@
 
 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._-]+$")
+# Extension identifiers follow the `_meta` key grammar with a mandatory prefix
+# (SEP-2133 / basic/index.mdx): dot-separated labels, each starting with a
+# letter and ending with a letter or digit (hyphens interior), then `/`, then a
+# name that starts and ends alphanumeric (`.`/`_`/`-` interior).
+_LABEL = r"[A-Za-z](?:[A-Za-z0-9-]*[A-Za-z0-9])?"
+_NAME = r"[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?"
+_IDENTIFIER_RE = re.compile(rf"{_LABEL}(?:\.{_LABEL})*/{_NAME}")
 
 
 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):
+    if not isinstance(identifier, str) or not _IDENTIFIER_RE.fullmatch(identifier):
         raise TypeError(
             f"{owner}.identifier must be a `vendor-prefix/name` string "
             f"(reverse-DNS prefix required), got {identifier!r}"
@@ -77,13 +82,34 @@ class MethodBinding:
     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.
+
+    Extension methods are additive: `method` must not name a spec-defined
+    request method (`tools/list`, `completion/complete`, ...) — those handlers
+    belong to the server, and an extension binding one would silently shadow or
+    be shadowed by it. Both constraints are enforced at construction. To
+    re-provide a spec method the 2026 revision removed (e.g. `logging/setLevel`
+    for legacy clients), use the lowlevel `Server.add_request_handler` API
+    instead — the runner's per-version surface gate would never route such a
+    method to an extension handler anyway.
     """
 
     method: str
     params_type: type[BaseModel]
     handler: RequestHandler
     protocol_versions: frozenset[str] | None = None
 
+    def __post_init__(self) -> None:
+        if self.method in SPEC_CLIENT_METHODS:
+            raise ValueError(
+                f"MethodBinding cannot bind spec method {self.method!r}; extension methods are "
+                "additive — use Extension.intercept_tool_call or Server.middleware to wrap core behaviour"
+            )
+        if self.protocol_versions is not None and not self.protocol_versions:
+            raise ValueError(
+                f"MethodBinding for {self.method!r} has an empty protocol_versions set, so it could "
+                "never be served; use None to admit every version"
+            )
+
 
 class Extension:
     """Base class for an opt-in MCP extension. Override only the methods you need.

src/mcp/server/mcpserver/server.py

@@ -291,6 +291,11 @@ def _apply_extension(self, extension: Extension) -> None:
         for resource in extension.resources():
             self.add_resource(resource.resource)
         for method in extension.methods():
+            if self._lowlevel_server.get_request_handler(method.method) is not None:
+                raise ValueError(
+                    f"Extension {identifier!r} binds method {method.method!r}, which is already "
+                    "registered; extension methods are additive and cannot replace another handler"
+                )
             handler = _version_gated(method) if method.protocol_versions is not None else method.handler
             self._lowlevel_server.add_request_handler(method.method, method.params_type, handler)
 

tests/server/mcpserver/test_extension.py

@@ -26,6 +26,7 @@
     ResourceBinding,
     ToolBinding,
     compose_tool_call_interceptor,
+    validate_extension_identifier,
 )
 from mcp.server.mcpserver import Context, MCPServer, require_client_extension
 from mcp.server.mcpserver.resources import TextResource
@@ -74,16 +75,18 @@ class _PingRequest(types.Request[_PingParams, Literal["com.example/ping"]]):
     params: _PingParams
 
 
+async def _pong_handler(ctx: ServerRequestContext[Any, Any], params: _PingParams) -> _PingResult:
+    """The shared `com.example/ping` handler (dispatched by the reachability test)."""
+    return _PingResult(pong=True)
+
+
 class _MethodExt(Extension):
     """Override `methods()` to serve a new vendor request verb."""
 
     identifier = "com.example/method"
 
-    def methods(self):
-        async def handler(ctx: ServerRequestContext[Any, Any], params: _PingParams) -> _PingResult:
-            return _PingResult(pong=True)
-
-        return [MethodBinding("com.example/ping", _PingParams, handler)]
+    def methods(self) -> list[MethodBinding]:
+        return [MethodBinding("com.example/ping", _PingParams, _pong_handler)]
 
 
 class _ReplacingExt(Extension):
@@ -356,6 +359,91 @@ async def test_version_pinned_method_is_method_not_found_at_a_disallowed_version
             await client.session.send_request(cast("types.ClientRequest", request), _VersionPinnedResult)
 
     assert exc_info.value.code == METHOD_NOT_FOUND
+    assert exc_info.value.error.data == "com.example/pinned"
+
+
+@pytest.mark.parametrize(
+    "identifier",
+    [
+        "io.modelcontextprotocol/ui",
+        "com.example/my_ext",
+        "com.x-y.z2/n.a-b_c",
+        "example/x",
+        "a/b",
+        "com.example/9start",
+    ],
+)
+def test_grammar_conformant_extension_identifiers_are_accepted(identifier: str) -> None:
+    """Spec `_meta` key grammar: dot-separated labels (letter start, letter/digit end,
+    hyphens interior), a slash, then a name that starts and ends alphanumeric."""
+    validate_extension_identifier(identifier, owner="T")
+
+
+@pytest.mark.parametrize(
+    "identifier",
+    [
+        "noprefix",
+        "-foo/bar",
+        ".leading/x",
+        "a..b/x",
+        "foo-/x",
+        "9foo/x",
+        "foo/-bar",
+        "foo/bar-",
+        "foo/",
+        "/bar",
+        "foo/ba r",
+        "io.modelcontextprotocol/ui\n",
+        "",
+        None,
+        42,
+    ],
+)
+def test_malformed_extension_identifiers_are_rejected(identifier: Any) -> None:
+    """Spec `_meta` key grammar: malformed prefixes (bad label start/end, empty labels)
+    and malformed names are rejected, as are non-strings."""
+    with pytest.raises(TypeError):
+        validate_extension_identifier(identifier, owner="T")
+
+
+@pytest.mark.parametrize("method", ["tools/list", "completion/complete"])
+def test_method_binding_rejects_spec_methods(method: str) -> None:
+    """SDK-defined: extension methods are additive — binding a spec-defined request method
+    would silently shadow (or be shadowed by) the server's own handler, so it is rejected
+    when the binding is constructed."""
+    with pytest.raises(ValueError):
+        MethodBinding(method, _PingParams, _pong_handler)
+
+
+def test_method_binding_rejects_empty_protocol_versions() -> None:
+    """SDK-defined: an empty `protocol_versions` set would make the method unreachable at
+    every version; `None` is the universal-version spelling."""
+    with pytest.raises(ValueError) as exc_info:
+        MethodBinding("com.example/dead", _PingParams, _pong_handler, frozenset())
+    assert str(exc_info.value) == snapshot(
+        "MethodBinding for 'com.example/dead' has an empty protocol_versions set, so it could "
+        "never be served; use None to admit every version"
+    )
+
+
+class _OtherMethodExt(Extension):
+    """A second extension binding the same verb as `_MethodExt`."""
+
+    identifier = "com.example/other-method"
+
+    def methods(self) -> list[MethodBinding]:
+        return [MethodBinding("com.example/ping", _PingParams, _pong_handler)]
+
+
+def test_colliding_extension_methods_are_rejected_at_registration() -> None:
+    """SDK-defined: two extensions binding the same method would silently last-write-win;
+    the collision is rejected when the second extension is applied."""
+    with pytest.raises(ValueError) as exc_info:
+        MCPServer("test", extensions=[_MethodExt(), _OtherMethodExt()])
+    assert str(exc_info.value) == snapshot(
+        "Extension 'com.example/other-method' binds method 'com.example/ping', which is already "
+        "registered; extension methods are additive and cannot replace another handler"
+    )
 
 
 _NEEDS_EXT = "com.example/needed"