Surface the SEP-2133 extensions capability map

Thread an `extensions` argument through the low-level `Server.get_capabilities`
and `create_initialization_options` (mirroring `experimental`), backed by a
`Server.extensions` attribute so the streamable-HTTP `server/discover` path
advertises it too. Add an `extensions` branch to `Connection.check_capability`
(presence-of-identifier, since settings are negotiated per-extension) and let a
client advertise its own support via `Client(extensions=...)` /
`ClientSession(extensions=...)`, mirrored into `ClientCapabilities.extensions`.

Author: Kludex

docs/migration.md

@@ -407,6 +407,38 @@ On `ClientSession`, `call_tool` / `get_prompt` / `read_resource` still return th
 
 For protocol 2026-07-28 over Streamable HTTP, a tool's input-schema property may carry an `x-mcp-header` annotation. When a tool the client has listed is called, each annotated argument is mirrored into an `Mcp-Param-<name>` request header (string verbatim, integer as decimal, boolean as `true`/`false`, base64-sentinel-wrapped when not header-safe; `null`/absent arguments are omitted). The argument is also left in the request body. `list_tools` caches a tool's annotations, so list a tool before calling it to enable mirroring; a tool the client never listed emits no `Mcp-Param-*` headers. Other transports ignore the annotation.
 
+### Server extensions API (SEP-2133)
+
+`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`
+and overrides only the contribution methods it needs: `tools()`/`resources()`/`methods()`
+(additive) and `intercept_tool_call()` (wraps `tools/call`). Pass instances at
+construction, or register later with `add_extension`:
+
+```python
+from mcp.server.mcpserver import MCPServer
+from mcp.server.apps import Apps
+from mcp.server.tasks import Tasks
+
+mcp = MCPServer("demo", extensions=[Apps(), Tasks()])
+# or: mcp.add_extension(Apps())
+```
+
+Two reference extensions ship in their own modules:
+
+- `mcp.server.apps.Apps` (`io.modelcontextprotocol/ui`) — binds a tool to a
+  `ui://` UI resource via `_meta.ui.resourceUri`; `client_supports_apps(ctx)`
+  gates the SEP-2133 text-only fallback.
+- `mcp.server.tasks.Tasks` (`io.modelcontextprotocol/tasks`) — intercepts
+  task-augmented `tools/call` and serves the `tasks/*` methods.
+
+Clients advertise extension support with the new `Client(extensions=...)` /
+`ClientSession(extensions=...)` argument, mirrored into `ClientCapabilities.extensions`.
+The extensions capability map is negotiated over `server/discover` (modern path);
+a legacy `initialize` handshake does not carry it. Extensions are off by default
+and never alter behaviour unless registered.
+
 ### `McpError` renamed to `MCPError`
 
 The `McpError` exception class has been renamed to `MCPError` for consistent naming with the MCP acronym style used throughout the SDK.

examples/stories/apps/README.md

@@ -1,14 +1,41 @@
 # apps
 
-MCP Apps: a tool result carries a `_meta.ui` reference to a `ui://` resource
-that the host renders as an interactive surface. The story will register a
-`@ui` resource and return it from a tool.
+MCP Apps: a tool carries a `_meta.ui.resourceUri` reference to a `ui://`
+resource that the host renders as an interactive surface. The server opts in via
+the `Apps` extension (`io.modelcontextprotocol/ui`); the client negotiates it by
+advertising the `text/html;profile=mcp-app` MIME type.
 
-**Status: not yet implemented** ([#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896)).
-The `extensions` capability map is not yet surfaced on `MCPServer`, so a server
-cannot advertise Apps support and a client cannot negotiate it.
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.apps.client
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it down
+uv run python -m stories.apps.client --http
+```
+
+## What to look at
+
+- `server.py` `Apps()` + `mcp.add_extension(apps)` — the extension advertises
+  `io.modelcontextprotocol/ui` under `ServerCapabilities.extensions` and
+  contributes the UI-bound tool and its `ui://` resource. `MCPServer` itself
+  never learns about "ui"; it applies a closed set of contributions.
+- `server.py` `@apps.tool(resource_uri=...)` — stamps `_meta.ui.resourceUri` on
+  the tool; `add_html_resource` registers the matching `ui://` resource at
+  `text/html;profile=mcp-app`.
+- `server.py` `client_supports_apps(ctx)` — SEP-2133 graceful degradation: a
+  client that did not negotiate Apps gets a text-only result.
+- `client.py` `Client(target, extensions={...})` — the client advertises Apps
+  support so the server returns the UI-enabled result, then reads the tool's
+  `_meta.ui.resourceUri` and fetches that resource.
 
 ## Spec
 
 [MCP Apps — extensions](https://modelcontextprotocol.io/specification/draft/extensions/apps)
 · [SEP-2133 — extensions capability](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2133)
+
+## See also
+
+`tasks/` (the interceptive half of the extension API),
+`custom_methods/` (registering a non-spec method without an extension).

examples/stories/manifest.toml

@@ -48,6 +48,21 @@ status = "deprecated"
 [story.custom_methods]
 lowlevel = false
 
+[story.apps]
+# Extension API is MCPServer-tier (Apps decorators + add_extension); no lowlevel variant.
+# The extensions capability map (SEP-2133) rides server/discover, a modern-only path, so
+# `main` pins "auto" (legacy initialize cannot carry it) and the leg is http-asgi.
+lowlevel   = false
+transports = ["in-memory", "http-asgi"]
+era        = "dual-in-body"
+
+[story.tasks]
+# Interceptive extension; the tasks/* methods drop to client.session like custom_methods.
+# extensions ride server/discover (modern-only), so the connection is pinned to "auto".
+lowlevel   = false
+transports = ["in-memory", "http-asgi"]
+era        = "dual-in-body"
+
 [story.schema_validators]
 
 [story.middleware]
@@ -142,7 +157,5 @@ fixed_port    = 8000                            # issuer/PRM metadata bake in :8
 [deferred]
 caching       = "client honouring + per-result override unlanded"
 subscriptions = "#2901 — Client.listen / ServerEventBus"
-tasks         = "extensions capability map + tasks runtime"
-apps          = "#2896 — extensions capability map"
 skills        = "#2896 — SEP-2640"
 events        = "#2901 + #2896"

examples/stories/tasks/README.md

@@ -1,16 +1,51 @@
 # tasks
 
-The `io.modelcontextprotocol/tasks` extension: long-running work registered
-with `@task`, polled via `tasks/get`, updated mid-flight, and cancelled with
-`tasks/cancel`. The story will show a task that outlives the request that
-started it.
+Task-augmented tool execution. A client sends `tools/call` with a `task` field;
+the server records the call under a task id and the client polls `tasks/get` /
+`tasks/result`. This is the *interceptive* half of the extension API — the
+`Tasks` extension (`io.modelcontextprotocol/tasks`) wraps `tools/call` rather
+than only adding tools.
 
-**Status: not yet implemented.** The extension types exist but the `extensions`
-capability map is not yet surfaced on `MCPServer`, and the runtime trails the
-release. The TypeScript SDK deliberately removed its tasks example pending the
-same work.
+## Run it
+
+```bash
+# stdio (default — the client spawns the server as a subprocess)
+uv run python -m stories.tasks.client
+
+# HTTP — the client self-hosts the server on a free port, runs, then tears it down
+uv run python -m stories.tasks.client --http
+```
+
+## What to look at
+
+- `server.py` `MCPServer(extensions=[Tasks()])` — opt in at construction. The
+  extension advertises `io.modelcontextprotocol/tasks` and serves `tasks/get`,
+  `tasks/result`, `tasks/cancel`, and `tasks/list`.
+- `mcp.server.tasks.Tasks.intercept_tool_call` — the interceptive seam: a plain
+  call passes through; a call with a `task` field is recorded and returned with
+  the task id in `_meta["io.modelcontextprotocol/related-task"]`.
+- `client.py` — sends a task-augmented `tools/call` via `client.session` (the
+  `task` field and `tasks/*` methods are outside the spec verbs `Client`
+  exposes), then drives the lifecycle through `tasks/get` and `tasks/result`.
+
+## Caveats
+
+This is a reference implementation for the extension API, not a production task
+runtime. The tool runs to completion inline (so a task is observed as
+`completed` immediately), and the augmented call returns a normal
+`CallToolResult` with the task id in `_meta` rather than the spec's
+`CreateTaskResult` — the `tools/call` result schema admits only
+`CallToolResult | InputRequiredResult` (see `TODO(L56)` in `mcp.server.runner`),
+so returning `CreateTaskResult` would require extending the methods-layer
+validation maps. The lifecycle runs through the dedicated `tasks/*` methods instead.
 
 ## Spec
 
-[Tasks — basic utilities](https://modelcontextprotocol.io/specification/draft/basic/utilities/tasks)
+[Tasks — extensions](https://modelcontextprotocol.io/specification/draft/extensions)
 · [SEP-2133 — extensions capability](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2133)
+
+## See also
+
+`apps/` (the additive half of the extension API),
+`custom_methods/` (a non-spec method without an extension),
+`middleware/` (the low-level `tools/call` wrapping the interceptor builds on).

src/mcp/client/client.py

@@ -217,6 +217,10 @@ async def main():
     `read_resource` give up. Use `client.session.<method>(..., allow_input_required=True)`
     to drive the loop manually instead."""
 
+    extensions: dict[str, dict[str, Any]] | None = None
+    """SEP-2133 extension support to advertise under `ClientCapabilities.extensions`
+    (identifier -> settings), e.g. `{"io.modelcontextprotocol/ui": {"mimeTypes": [...]}}`."""
+
     _entered: bool = field(init=False, default=False)
     _session: ClientSession | None = field(init=False, default=None)
     _exit_stack: AsyncExitStack | None = field(init=False, default=None)
@@ -255,6 +259,7 @@ async def _build_session(self, exit_stack: AsyncExitStack) -> ClientSession:
             message_handler=self.message_handler,
             client_info=self.client_info,
             elicitation_callback=self.elicitation_callback,
+            extensions=self.extensions,
         )
 
     async def __aenter__(self) -> Client:

src/mcp/client/session.py

@@ -224,12 +224,14 @@ def __init__(
         client_info: types.Implementation | None = None,
         *,
         sampling_capabilities: types.SamplingCapability | None = None,
+        extensions: dict[str, dict[str, Any]] | None = None,
         dispatcher: Dispatcher[Any] | None = None,
     ) -> None:
         self._session_read_timeout_seconds = read_timeout_seconds
         self._client_info = client_info or DEFAULT_CLIENT_INFO
         self._sampling_callback = sampling_callback or _default_sampling_callback
         self._sampling_capabilities = sampling_capabilities
+        self._extensions = extensions
         self._elicitation_callback = elicitation_callback or _default_elicitation_callback
         self._list_roots_callback = list_roots_callback or _default_list_roots_callback
         self._logging_callback = logging_callback or _default_logging_callback
@@ -369,7 +371,9 @@ def _build_capabilities(self) -> types.ClientCapabilities:
             if self._list_roots_callback is not _default_list_roots_callback
             else None
         )
-        return types.ClientCapabilities(sampling=sampling, elicitation=elicitation, experimental=None, roots=roots)
+        return types.ClientCapabilities(
+            sampling=sampling, elicitation=elicitation, experimental=None, extensions=self._extensions, roots=roots
+        )
 
     async def initialize(self) -> types.InitializeResult:
         if self._initialize_result is not None:

src/mcp/server/connection.py

@@ -345,4 +345,14 @@ def check_capability(self, capability: ClientCapabilities) -> bool:
             for k, v in capability.experimental.items():
                 if k not in have.experimental or have.experimental[k] != v:
                     return False
+        if capability.extensions is not None:
+            # SEP-2133: an extension is supported when the client declares its
+            # identifier. Settings are negotiated per-extension (the client may
+            # advertise more than the server asks for), so presence - not value
+            # equality - is the meaningful check.
+            if have.extensions is None:
+                return False
+            for identifier in capability.extensions:
+                if identifier not in have.extensions:
+                    return False
         return True

src/mcp/server/lowlevel/server.py

@@ -434,6 +434,10 @@ def __init__(
         # Context/middleware rework (covariant `Context[L]`, outbound seam) before
         # v2 final.
         self.middleware: list[ServerMiddleware[LifespanResultT]] = [OpenTelemetryMiddleware()]
+        # SEP-2133 extension settings advertised under `ServerCapabilities.extensions`
+        # (identifier -> settings). Higher layers (e.g. `MCPServer(extensions=...)`)
+        # populate it; `get_capabilities` reads it when no explicit map is passed.
+        self.extensions: dict[str, dict[str, Any]] = {}
         logger.debug("Initializing server %r", name)
 
         _spec_requests: list[tuple[str, type[BaseModel], RequestHandler[LifespanResultT, Any] | None]] = [
@@ -521,8 +525,15 @@ def create_initialization_options(
         self,
         notification_options: NotificationOptions | None = None,
         experimental_capabilities: dict[str, dict[str, Any]] | None = None,
+        extensions: dict[str, dict[str, Any]] | None = None,
     ) -> InitializationOptions:
-        """Create initialization options from this server instance."""
+        """Create initialization options from this server instance.
+
+        `extensions` advertises SEP-2133 extension support under
+        `ServerCapabilities.extensions`; keys are extension identifiers (e.g.
+        `io.modelcontextprotocol/ui`), values are per-extension settings.
+        Defaults to `self.extensions`, which higher layers populate.
+        """
         return InitializationOptions(
             server_name=self.name,
             server_version=self.version if self.version else _package_version("mcp"),
@@ -531,6 +542,7 @@ def create_initialization_options(
             capabilities=self.get_capabilities(
                 notification_options or NotificationOptions(),
                 experimental_capabilities or {},
+                extensions if extensions is not None else self.extensions,
             ),
             instructions=self.instructions,
             website_url=self.website_url,
@@ -541,8 +553,14 @@ def get_capabilities(
         self,
         notification_options: NotificationOptions | None = None,
         experimental_capabilities: dict[str, dict[str, Any]] | None = None,
+        extensions: dict[str, dict[str, Any]] | None = None,
     ) -> types.ServerCapabilities:
-        """Convert existing handlers to a ServerCapabilities object."""
+        """Convert existing handlers to a ServerCapabilities object.
+
+        `extensions` is the SEP-2133 extension map (identifier -> settings)
+        advertised under `ServerCapabilities.extensions`; it defaults to
+        `self.extensions`.
+        """
         notification_options = notification_options or NotificationOptions()
         prompts_capability = None
         resources_capability = None
@@ -579,6 +597,7 @@ def get_capabilities(
             tools=tools_capability,
             logging=logging_capability,
             experimental=experimental_capabilities,
+            extensions=extensions if extensions is not None else (self.extensions or None),
             completions=completions_capability,
         )
         return capabilities

src/mcp/server/mcpserver/__init__.py

@@ -3,7 +3,18 @@
 from mcp_types import Icon
 
 from .context import Context
+from .extension import Extension, MethodBinding, ResourceBinding, ToolBinding
 from .server import MCPServer
 from .utilities.types import Audio, Image
 
-__all__ = ["MCPServer", "Context", "Image", "Audio", "Icon"]
+__all__ = [
+    "MCPServer",
+    "Context",
+    "Image",
+    "Audio",
+    "Icon",
+    "Extension",
+    "ToolBinding",
+    "ResourceBinding",
+    "MethodBinding",
+]

src/mcp/server/mcpserver/resources/types.py

@@ -26,7 +26,7 @@ class TextResource(Resource):
 
     async def read(self) -> str:
         """Read the text content."""
-        return self.text  # pragma: no cover
+        return self.text
 
 
 class BinaryResource(Resource):