Add the MCP Apps extension (io.modelcontextprotocol/ui)

`Apps` is an additive `Extension`: `@apps.tool(resource_uri=...)` binds a tool to a
`ui://` UI resource via `_meta.ui.resourceUri`, `add_html_resource()` serves the
HTML at `text/html;profile=mcp-app`, and `client_supports_apps(ctx)` gates the
SEP-2133 text-only fallback. Drop the now-exercised `# pragma: no cover` on
`TextResource.read()` (the Apps resource path covers it).

Author: Kludex

src/mcp/server/apps.py

@@ -0,0 +1,138 @@
+"""MCP Apps extension (`io.modelcontextprotocol/ui`).
+
+MCP Apps lets a tool carry a reference to an interactive UI: the tool's
+`_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.
+
+This is a self-contained, additive `Extension`: it contributes tools and
+resources and advertises the capability, but does not intercept any core method.
+A server opts in by passing an `Apps` instance to `MCPServer(extensions=[...])`.
+
+    apps = Apps()
+
+    @apps.tool(resource_uri="ui://clock/app.html", description="Current time")
+    def get_time(ctx: Context) -> str:
+        return datetime.now(timezone.utc).isoformat()
+
+    apps.add_html_resource("ui://clock/app.html", CLOCK_HTML)
+
+    mcp = MCPServer("clock", extensions=[apps])
+
+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.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
+
+from mcp.server.context import ServerRequestContext
+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"
+"""The MCP Apps extension identifier (the shipped TS/C# constant)."""
+
+APP_MIME_TYPE = "text/html;profile=mcp-app"
+"""MIME type for a `ui://` app resource."""
+
+_CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
+
+
+class Apps(Extension):
+    """The MCP Apps extension: bind tools to `ui://` UI resources.
+
+    Register UI-bound tools with `@apps.tool(resource_uri=...)` and their HTML
+    with `add_html_resource(...)`, then pass the instance to
+    `MCPServer(extensions=[apps])`.
+    """
+
+    identifier = EXTENSION_ID
+
+    def __init__(self) -> None:
+        self._tools: list[ToolBinding] = []
+        self._resources: list[ResourceBinding] = []
+
+    def tool(self, *, resource_uri: str, **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, ...).
+
+        Args:
+            resource_uri: The `ui://` URI of the UI resource this tool renders.
+
+        Raises:
+            ValueError: If `resource_uri` does not use the `ui://` scheme.
+        """
+        _require_ui_scheme(resource_uri)
+
+        def decorator(fn: _CallableT) -> _CallableT:
+            meta = {"ui": {"resourceUri": resource_uri}}
+            self._tools.append(ToolBinding(fn=fn, meta=meta, kwargs=tool_kwargs))
+            return fn
+
+        return decorator
+
+    def add_html_resource(
+        self,
+        uri: str,
+        html: str,
+        *,
+        name: str | None = None,
+        title: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        """Register a `ui://` HTML resource served as `text/html;profile=mcp-app`.
+
+        Args:
+            uri: The `ui://` URI; a tool references it via `resource_uri`.
+            html: The HTML document the host renders.
+
+        Raises:
+            ValueError: If `uri` does not use the `ui://` scheme.
+        """
+        _require_ui_scheme(uri)
+        resource = TextResource(
+            uri=uri,
+            name=name or uri,
+            title=title,
+            description=description,
+            mime_type=APP_MIME_TYPE,
+            text=html,
+        )
+        self._resources.append(ResourceBinding(resource=resource))
+
+    def tools(self) -> Sequence[ToolBinding]:
+        return self._tools
+
+    def resources(self) -> Sequence[ResourceBinding]:
+        return self._resources
+
+
+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.
+    """
+    capabilities = _client_capabilities(ctx)
+    extensions = capabilities.extensions if capabilities else None
+    return bool(extensions and EXTENSION_ID in extensions)
+
+
+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
+
+
+def _require_ui_scheme(uri: str) -> None:
+    if not uri.startswith("ui://"):
+        raise ValueError(f"MCP Apps URIs must use the ui:// scheme, got {uri!r}")

tests/server/test_apps.py

@@ -0,0 +1,135 @@
+"""Tests for the MCP Apps extension (`io.modelcontextprotocol/ui`, SEP-2133).
+
+The headline property is SEP-2133 graceful degradation: a UI-bound tool returns
+rich output to a client that negotiated Apps and text-only output to one that did
+not. The remaining tests pin SDK-defined wiring (the `_meta.ui.resourceUri` stamp,
+the `ui://` resource MIME type, capability advertisement, and `ui://`-scheme
+validation).
+"""
+
+import mcp_types as types
+import pytest
+from inline_snapshot import snapshot
+from mcp_types import CallToolResult, ReadResourceResult, TextContent, TextResourceContents
+
+from mcp.client.client import Client
+from mcp.server import Server, ServerRequestContext
+from mcp.server.apps import APP_MIME_TYPE, EXTENSION_ID, Apps, client_supports_apps
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.context import Context
+
+pytestmark = pytest.mark.anyio
+
+
+def _clock_server() -> MCPServer:
+    apps = Apps()
+
+    @apps.tool(resource_uri="ui://clock/app.html", title="Get Time", description="Return the current time.")
+    def get_time(ctx: Context) -> str:
+        if not client_supports_apps(ctx):
+            return "The time is 2026-06-26T00:00:00Z."
+        return "2026-06-26T00:00:00Z"
+
+    apps.add_html_resource("ui://clock/app.html", "<title>Clock</title>", title="Clock")
+    return MCPServer("clock", extensions=[apps])
+
+
+async def test_apps_tool_stamps_ui_resource_uri_on_tool_meta() -> None:
+    """SDK-defined: `@apps.tool(resource_uri=...)` stamps `_meta.ui.resourceUri` on the
+    advertised tool, observed end-to-end through `list_tools`."""
+    async with Client(_clock_server()) as client:
+        result = await client.list_tools()
+    assert [(t.name, t.meta) for t in result.tools] == snapshot(
+        [("get_time", {"ui": {"resourceUri": "ui://clock/app.html"}})]
+    )
+
+
+async def test_add_html_resource_serves_ui_resource_at_app_mime_type() -> None:
+    """SDK-defined: `add_html_resource` registers the `ui://` resource served as
+    `text/html;profile=mcp-app`, observed through `read_resource`."""
+    async with Client(_clock_server()) as client:
+        result = await client.read_resource("ui://clock/app.html")
+    assert result == snapshot(
+        ReadResourceResult(
+            contents=[
+                TextResourceContents(
+                    uri="ui://clock/app.html",
+                    mime_type="text/html;profile=mcp-app",
+                    text="<title>Clock</title>",
+                )
+            ]
+        )
+    )
+    assert isinstance(result.contents[0], TextResourceContents)
+    assert result.contents[0].mime_type == APP_MIME_TYPE
+
+
+async def test_auto_mode_carries_apps_extension_under_server_capabilities() -> None:
+    """SDK-defined: the Apps extension rides `server/discover`, so a `mode='auto'` client
+    sees `EXTENSION_ID` under `server_capabilities.extensions`."""
+    async with Client(_clock_server(), mode="auto") as client:
+        assert client.server_capabilities.extensions == snapshot({"io.modelcontextprotocol/ui": {}})
+
+
+async def test_legacy_handshake_drops_apps_extension_from_capabilities() -> None:
+    """Pinned gap: the 2025 `ServerCapabilities` wire schema has no `extensions` field,
+    so a `mode='legacy'` handshake cannot carry the Apps capability -- only `mode='auto'`
+    (server/discover) does. This pins the divergence rather than fixing it."""
+    async with Client(_clock_server(), mode="legacy") as client:
+        assert client.server_capabilities.extensions is None
+
+
+async def test_apps_tool_returns_rich_output_when_client_negotiated_apps() -> None:
+    """SEP-2133 graceful degradation: a client that advertised `EXTENSION_ID` gets the
+    rich (UI) path, while one that did not gets the text-only fallback. The same tool,
+    branching on `client_supports_apps(ctx)`, drives both halves."""
+    server = _clock_server()
+
+    async with Client(server, extensions={EXTENSION_ID: {"mimeTypes": [APP_MIME_TYPE]}}) as supports:
+        rich = await supports.call_tool("get_time", {})
+    async with Client(server) as plain:
+        fallback = await plain.call_tool("get_time", {})
+
+    assert rich.content == snapshot([TextContent(text="2026-06-26T00:00:00Z")])
+    assert fallback.content == snapshot([TextContent(text="The time is 2026-06-26T00:00:00Z.")])
+
+
+async def test_client_supports_apps_reads_lowlevel_request_context() -> None:
+    """SDK-defined: `client_supports_apps` accepts a lowlevel `ServerRequestContext` too,
+    reading the client's advertised extensions off `session.client_params`."""
+    observed: list[bool] = []
+
+    async def list_tools(
+        ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+    ) -> types.ListToolsResult:
+        return types.ListToolsResult(tools=[types.Tool(name="probe", input_schema={"type": "object"})])
+
+    async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:
+        assert params.name == "probe"
+        observed.append(client_supports_apps(ctx))
+        return CallToolResult(content=[TextContent(text="ok")])
+
+    server = Server("probe", on_list_tools=list_tools, on_call_tool=call_tool)
+
+    async with Client(server, extensions={EXTENSION_ID: {"mimeTypes": [APP_MIME_TYPE]}}) as supports:
+        await supports.call_tool("probe", {})
+    async with Client(server) as plain:
+        await plain.call_tool("probe", {})
+
+    assert observed == [True, False]
+
+
+def test_apps_tool_rejects_non_ui_resource_uri() -> None:
+    """SDK-defined: `@apps.tool` accepts only `ui://` URIs; any other scheme is a
+    programmer error raised at decoration time."""
+    apps = Apps()
+    with pytest.raises(ValueError):
+        apps.tool(resource_uri="https://example.com/app.html")
+
+
+def test_add_html_resource_rejects_non_ui_resource_uri() -> None:
+    """SDK-defined: `add_html_resource` accepts only `ui://` URIs; any other scheme is
+    a programmer error raised at registration time."""
+    apps = Apps()
+    with pytest.raises(ValueError):
+        apps.add_html_resource("https://example.com/app.html", "<title>x</title>")