Back every docs code block with a tested docs_src file

The extensions and MCP Apps pages had inline Python fragments that CI
never executed. Every block now includes a docs_src module: the client
programs are async main()s run by tests/docs_src, the identifier and
usage fragments are real files, and the FileResource example serves a
checked-in report.html. Pages re-include the same file with different
hl_lines instead of repeating code.

Author: maxisbey

docs/advanced/apps.md

@@ -20,7 +20,7 @@ then come back.
 
 ## A clock with a face
 
-```python title="server.py" hl_lines="17 20 23-24 28 30"
+```python title="server.py" hl_lines="18 21 29 31"
 --8<-- "docs_src/apps/tutorial001.py"
 ```
 
@@ -49,37 +49,23 @@ Not every client renders apps. The spec is blunt about what that means for you:
 
 The model reads `content`; the iframe is for humans. A UI-capable host still feeds
 the text result to the model, and a text-only client gets *only* that. So the
-canonical pattern is one tool, two answers:
-
-```python
-@apps.tool(resource_uri="ui://clock/app.html")
-def get_time(ctx: Context) -> str:
-    now = current_time()
-    if not client_supports_apps(ctx):
-        return f"The time is {now}."   # a sentence for humans without the UI
-    return now                          # raw data the app renders
+canonical pattern is one tool, two answers. Look at `get_time` again:
+
+```python title="server.py" hl_lines="22-26"
+--8<-- "docs_src/apps/tutorial001.py"
 ```
 
 `client_supports_apps(ctx)` is `True` only when the client declared the
 `io.modelcontextprotocol/ui` extension **and** listed `text/html;profile=mcp-app`
 in its `mimeTypes` settings. The field is required, so a client that omits it
-does not count.
+does not count. That is exactly what `main()` in the same file declares: the
+client half of the negotiation, and the rich answer comes back.
 
 !!! warning
     Never return a placeholder like `"[Rendered UI]"` as the only content. If the
     fallback text is useless, the tool is useless to every text-only client and to
     the model itself. Write the sentence.
 
-A client declares support like any extension capability:
-
-```python
-from mcp import Client
-from mcp.server.apps import APP_MIME_TYPE, EXTENSION_ID
-
-async with Client(target, extensions={EXTENSION_ID: {"mimeTypes": [APP_MIME_TYPE]}}) as client:
-    ...
-```
-
 ## Locking the iframe down
 
 The resource side carries the security metadata: what the iframe may load, which
@@ -149,10 +135,8 @@ rather you find out before a host does.
 `add_html_resource` covers the common case: a string of HTML. For anything else,
 HTML on disk or generated content, build the resource yourself and hand it over:
 
-```python
-from mcp.server.mcpserver.resources import FileResource
-
-apps.add_resource(FileResource(uri="ui://report/app.html", name="report", path=html_path))
+```python title="server.py" hl_lines="12 18"
+--8<-- "docs_src/apps/tutorial003.py"
 ```
 
 `add_resource` fills in the `text/html;profile=mcp-app` MIME type when the resource

docs/advanced/extensions.md

@@ -11,11 +11,8 @@ it has one golden rule: **extensions are off by default**.
 
 Pass instances at construction:
 
-```python
-from mcp.server.apps import Apps
-from mcp.server.mcpserver import MCPServer
-
-mcp = MCPServer("demo", extensions=[Apps()])
+```python title="server.py"
+--8<-- "docs_src/extensions/tutorial001.py"
 ```
 
 Done. The server now advertises `io.modelcontextprotocol/ui` under
@@ -39,8 +36,7 @@ Subclass `Extension` and override only what you need. Every method has a default
 ### The identifier
 
 ```python
-class Stamps(Extension):
-    identifier = "com.example/stamps"
+--8<-- "docs_src/extensions/tutorial002.py"
 ```
 
 The identifier is a `vendor-prefix/name` string following the spec's `_meta` key
@@ -60,8 +56,8 @@ specified by the MCP project itself.
 
 The smallest useful extension is one tool and a settings map:
 
-```python title="server.py" hl_lines="16 18-19 21-22 25"
---8<-- "docs_src/extensions/tutorial001.py"
+```python title="server.py" hl_lines="17 19-20 22-23 26"
+--8<-- "docs_src/extensions/tutorial003.py"
 ```
 
 * `tools()` returns `ToolBinding`s. The server registers each one exactly as if you
@@ -72,27 +68,19 @@ The smallest useful extension is one tool and a settings map:
 * The extension never receives the server. It declares contributions as data;
   `MCPServer` consumes them. There is no `self.server` to mutate.
 
-#### Try it
+And `main()` is the proof, an in-memory client straight against `mcp`:
 
-```python
-from mcp import Client
-
-
-async def main() -> None:
-    async with Client(mcp) as client:
-        print(client.server_capabilities.extensions)
-        # {'com.example/stamps': {'sealed': True}}
-        result = await client.call_tool("stamp", {"text": "hello"})
-        # [stamped] hello
+```python title="server.py" hl_lines="29-34"
+--8<-- "docs_src/extensions/tutorial003.py"
 ```
 
 ### Serving your own methods
 
 An extension can register **new request methods**: its own verbs, served next to the
 spec's:
 
-```python title="server.py" hl_lines="14-20 24 33-41"
---8<-- "docs_src/extensions/tutorial002.py"
+```python title="server.py" hl_lines="15-21 30 39-47"
+--8<-- "docs_src/extensions/tutorial004.py"
 ```
 
 * `SearchParams` subclasses `RequestParams`, so the 2026 `_meta` envelope parses
@@ -116,18 +104,31 @@ runtime:
 * An empty `protocol_versions` set raises too: a method that can never be served
   is a bug, not a configuration.
 
-!!! tip
-    Calling a vendor method from the client goes through `client.session.send_request(...)`
-    today; `Client` only grows first-class methods for spec verbs. The
-    `custom_methods` story in `examples/stories/` shows the full round trip.
+### The client side
+
+The same file's `main()` is the whole client story, both halves of it:
+
+```python title="server.py" hl_lines="53-57"
+--8<-- "docs_src/extensions/tutorial004.py"
+```
+
+* `Client(..., extensions={EXTENSION_ID: {}})` declares the extension. That map
+  becomes `ClientCapabilities.extensions`: on a 2026-07-28 connection it travels in
+  the per-request `_meta` envelope, so the server sees it on **every** request; on
+  a legacy connection it rides the `initialize` handshake. Server code doesn't care
+  which: `require_client_extension(ctx, ...)` and
+  `ctx.session.check_client_capability(...)` read the right source on both paths.
+* Vendor methods drop one layer to `client.session.send_request(...)`; `Client`
+  only grows first-class methods for spec verbs. The `cast` is there because
+  `send_request` is typed against the spec's closed request union.
 
 ### Intercepting `tools/call`
 
 The one interceptive hook. Override `intercept_tool_call` to observe, short-circuit,
 or veto a tool call:
 
 ```python title="server.py" hl_lines="18-25"
---8<-- "docs_src/extensions/tutorial003.py"
+--8<-- "docs_src/extensions/tutorial005.py"
 ```
 
 * `params` is the validated `CallToolRequestParams`: you get `params.name` and
@@ -143,23 +144,6 @@ or veto a tool call:
 The hook wraps `tools/call` and nothing else. For every-message concerns, use
 [Middleware](middleware.md). That is what it is for.
 
-## The client side
-
-A client declares the extensions it supports the same way the server does:
-
-```python
-from mcp import Client
-
-async with Client(target, extensions={"com.example/search": {}}) as client:
-    ...
-```
-
-That map becomes `ClientCapabilities.extensions`. On a 2026-07-28 connection it
-travels in the per-request `_meta` envelope, so the server sees it on **every**
-request; on a legacy connection it rides the `initialize` handshake. Server code
-doesn't care which: `require_client_extension(ctx, ...)` and
-`ctx.session.check_client_capability(...)` read the right source on both paths.
-
 ## What an extension cannot do
 
 The contribution surface is **closed** on purpose: settings, tools, resources,

docs_src/apps/report.html

@@ -0,0 +1,3 @@
+<!doctype html>
+<title>Report</title>
+<p>Quarterly numbers render here.</p>

docs_src/apps/tutorial001.py

@@ -1,4 +1,5 @@
-from mcp.server.apps import Apps, client_supports_apps
+from mcp import Client
+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
 
@@ -28,3 +29,10 @@ def get_time(ctx: Context) -> str:
 apps.add_html_resource("ui://clock/app.html", CLOCK_HTML, title="Clock")
 
 mcp = MCPServer("clock", extensions=[apps])
+
+
+async def main() -> None:
+    async with Client(mcp, extensions={EXTENSION_ID: {"mimeTypes": [APP_MIME_TYPE]}}) as client:
+        result = await client.call_tool("get_time", {})
+        print(result.content)
+        # [TextContent(text='2026-06-26T12:00:00Z')]

docs_src/apps/tutorial003.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+from mcp.server.apps import Apps
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.resources import FileResource
+
+REPORT_HTML = Path(__file__).parent / "report.html"
+
+apps = Apps()
+
+
+@apps.tool(resource_uri="ui://report/app.html")
+def refresh_report() -> str:
+    """Refresh the report data."""
+    return "report refreshed"
+
+
+apps.add_resource(FileResource(uri="ui://report/app.html", name="report", path=REPORT_HTML))
+
+mcp = MCPServer("report", extensions=[apps])

docs_src/extensions/tutorial001.py

@@ -1,25 +1,4 @@
-from collections.abc import Sequence
-from typing import Any
-
-from mcp.server.extension import Extension, ToolBinding
+from mcp.server.apps import Apps
 from mcp.server.mcpserver import MCPServer
 
-
-def stamp(text: str) -> str:
-    """Stamp a message with the office seal."""
-    return f"[stamped] {text}"
-
-
-class Stamps(Extension):
-    """A purely additive extension: one tool, one capability entry."""
-
-    identifier = "com.example/stamps"
-
-    def settings(self) -> dict[str, Any]:
-        return {"sealed": True}
-
-    def tools(self) -> Sequence[ToolBinding]:
-        return [ToolBinding(fn=stamp)]
-
-
-mcp = MCPServer("post-office", extensions=[Stamps()])
+mcp = MCPServer("demo", extensions=[Apps()])

docs_src/extensions/tutorial002.py

@@ -1,44 +1,5 @@
-from collections.abc import Sequence
-from typing import Any
+from mcp.server.extension import Extension
 
-import mcp_types as types
-from pydantic import Field
 
-from mcp.server.context import ServerRequestContext
-from mcp.server.extension import Extension, MethodBinding
-from mcp.server.mcpserver import MCPServer, require_client_extension
-
-EXTENSION_ID = "com.example/search"
-
-
-class SearchParams(types.RequestParams):
-    query: str
-    limit: int = Field(default=10, ge=1, le=100)
-
-
-class SearchResult(types.Result):
-    items: list[str]
-
-
-async def search(ctx: ServerRequestContext[Any, Any], params: SearchParams) -> SearchResult:
-    require_client_extension(ctx, EXTENSION_ID)
-    return SearchResult(items=[f"{params.query}-{n}" for n in range(params.limit)])
-
-
-class Search(Extension):
-    """An extension that serves its own request method."""
-
-    identifier = EXTENSION_ID
-
-    def methods(self) -> Sequence[MethodBinding]:
-        return [
-            MethodBinding(
-                "com.example/search",
-                SearchParams,
-                search,
-                protocol_versions=frozenset({"2026-07-28"}),
-            )
-        ]
-
-
-mcp = MCPServer("catalog", extensions=[Search()])
+class Stamps(Extension):
+    identifier = "com.example/stamps"

docs_src/extensions/tutorial003.py

@@ -1,34 +1,35 @@
-import logging
+from collections.abc import Sequence
 from typing import Any
 
-from mcp_types import CallToolRequestParams
-
-from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
-from mcp.server.extension import Extension
+from mcp import Client
+from mcp.server.extension import Extension, ToolBinding
 from mcp.server.mcpserver import MCPServer
 
-logger = logging.getLogger(__name__)
 
+def stamp(text: str) -> str:
+    """Stamp a message with the office seal."""
+    return f"[stamped] {text}"
+
+
+class Stamps(Extension):
+    """A purely additive extension: one tool, one capability entry."""
 
-class AuditLog(Extension):
-    """Observe every tools/call without touching its result."""
+    identifier = "com.example/stamps"
 
-    identifier = "com.example/audit"
+    def settings(self) -> dict[str, Any]:
+        return {"sealed": True}
 
-    async def intercept_tool_call(
-        self,
-        params: CallToolRequestParams,
-        ctx: ServerRequestContext[Any, Any],
-        call_next: CallNext,
-    ) -> HandlerResult:
-        logger.info("tool %r called", params.name)
-        return await call_next(ctx)
+    def tools(self) -> Sequence[ToolBinding]:
+        return [ToolBinding(fn=stamp)]
 
 
-mcp = MCPServer("audited", extensions=[AuditLog()])
+mcp = MCPServer("post-office", extensions=[Stamps()])
 
 
-@mcp.tool()
-def add(a: int, b: int) -> int:
-    """Add two numbers."""
-    return a + b
+async def main() -> None:
+    async with Client(mcp) as client:
+        print(client.server_capabilities.extensions)
+        # {'com.example/stamps': {'sealed': True}}
+        result = await client.call_tool("stamp", {"text": "hello"})
+        print(result.content)
+        # [TextContent(text='[stamped] hello')]