Extensions intercept tools/call at the handler layer

A short-circuiting Extension.intercept_tool_call previously returned from
the middleware chain, above the runner's outbound envelope pass, so its
result skipped the per-version result sieve and the 2026-era serverInfo
_meta stamp - and extension authors had no way to add the stamp themselves.
Compose the interceptor chain around the tools/call handler instead of
appending a middleware: a short-circuited result is now serialized exactly
like a handler result, and call_next hands interceptors the handler's
domain result rather than the wire dict.

Also: pin version="2.0.0" on the lowlevel structured-output tutorial server
so the page's fenced result is reproducible (and prove the fence verbatim
in its test), document middleware envelope ownership in the middleware and
migration pages, and update two stale docstrings from the envelope
refactor.

Author: maxisbey

docs/advanced/middleware.md

@@ -63,6 +63,10 @@ In increasing order of how much you should hesitate:
   `initialize`: the result the client gets back is built from your rewritten params, but the
   server commits its connection state from the original wire params. The two sides can finish
   the handshake disagreeing about what they negotiated.
+* **Answer.** Return a result without calling `call_next(ctx)` and it goes to the client as
+  your response. `call_next` hands you the finished wire form, and the pipeline never patches
+  what you return, so the whole envelope is yours: on a 2026-era connection that includes the
+  `serverInfo` `_meta` stamp, which the SDK adds to handler results but not to yours.
 
 !!! check
     `initialize` is one of the things middleware wraps, and it is the *only* hook you get

docs/migration.md

@@ -486,7 +486,8 @@ What changed in the SDK:
   so on). Pass `include_server_info=False` to `Server(...)` or `MCPServer(...)`
   to turn it off. A `serverInfo` value your handler already set in `_meta` is
   never overwritten. Handshake-era responses are unchanged, and notifications
-  and error responses are never stamped.
+  and error responses are never stamped. A middleware that answers a request
+  itself (without `call_next`) owns its result envelope, stamp included.
 - `client.server_info` and `session.server_info` are `Implementation | None`
   on 2026-era connections: identity is optional on the wire, so a server that
   does not stamp it reads as `None`. Handshake-era connections still always

docs_src/lowlevel/tutorial003.py

@@ -38,4 +38,4 @@ async def call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) ->
     )
 
 
-server = Server("Bookshop", on_list_tools=list_tools, on_call_tool=call_tool)
+server = Server("Bookshop", version="2.0.0", on_list_tools=list_tools, on_call_tool=call_tool)

src/mcp/server/extension.py

@@ -27,7 +27,7 @@
 from mcp_types.methods import SPEC_CLIENT_METHODS
 from pydantic import BaseModel
 
-from mcp.server.context import CallNext, HandlerResult, ServerMiddleware, ServerRequestContext
+from mcp.server.context import CallNext, HandlerResult, ServerRequestContext
 
 # Re-exported from `mcp.shared.extension` (shared with the client surface) for existing importers.
 from mcp.shared.extension import validate_extension_identifier as validate_extension_identifier
@@ -144,30 +144,34 @@ async def intercept_tool_call(
 
         Override to short-circuit (return a result without calling `call_next`)
         or to observe the call. `params` is the validated `tools/call` params;
-        `call_next(ctx)` runs the rest of the chain and the real handler.
+        `call_next(ctx)` runs the rest of the chain and the real handler, and
+        returns the handler's domain result. Interceptors run at the handler
+        layer: whatever they return is serialized like any handler result,
+        including the 2026-era `serverInfo` `_meta` stamp.
         """
         return await call_next(ctx)
 
 
-def compose_tool_call_interceptor(extensions: Sequence[Extension]) -> ServerMiddleware[Any]:
-    """Fold every extension's `intercept_tool_call` into one `ServerMiddleware`.
+def compose_tool_call_handler(extensions: Sequence[Extension], handler: RequestHandler) -> RequestHandler:
+    """Fold every extension's `intercept_tool_call` around the `tools/call` handler.
 
-    The returned middleware nests the interceptors (first extension outermost)
-    and is a no-op for any method other than `tools/call`. It validates the
-    `tools/call` params once and threads them to each interceptor.
+    The returned handler nests the interceptors (first extension outermost) and
+    replaces the plain `tools/call` registration. Interception happens at the
+    handler layer, below the runner's outbound envelope pass, so a
+    short-circuiting interceptor's result is sieved and stamped exactly like
+    the wrapped handler's would be.
     """
 
-    async def middleware(ctx: ServerRequestContext[Any, Any], call_next: CallNext) -> HandlerResult:
-        if ctx.method != "tools/call":
-            return await call_next(ctx)
-        params = CallToolRequestParams.model_validate({} if ctx.params is None else ctx.params, by_name=False)
+    async def wrapped(ctx: ServerRequestContext[Any, Any], params: CallToolRequestParams) -> HandlerResult:
+        async def innermost(inner_ctx: ServerRequestContext[Any, Any]) -> HandlerResult:
+            return await handler(inner_ctx, params)
 
-        chain = call_next
+        chain: CallNext = innermost
         for extension in reversed(extensions):
             chain = _bind_interceptor(extension, params, chain)
         return await chain(ctx)
 
-    return middleware
+    return wrapped
 
 
 def _bind_interceptor(extension: Extension, params: CallToolRequestParams, call_next: CallNext) -> CallNext:

src/mcp/server/mcpserver/server.py

@@ -64,7 +64,7 @@
     Extension,
     MethodBinding,
     RequestHandler,
-    compose_tool_call_interceptor,
+    compose_tool_call_handler,
     validate_extension_identifier,
 )
 from mcp.server.lowlevel.helper_types import ReadResourceContents
@@ -230,8 +230,9 @@ def __init__(
             # We need to create a Lifespan type that is a generic on the server type, like Starlette does.
             lifespan=(lifespan_wrapper(self, self.settings.lifespan) if self.settings.lifespan else default_lifespan),  # type: ignore
         )
-        # Ordering: inside OpenTelemetry (spans record the sealed wire form),
-        # outside extension interceptors (extensions see plaintext).
+        # Ordering: inside OpenTelemetry (spans record the sealed wire form).
+        # Extension interceptors run at the handler layer, inside this
+        # boundary, so they see plaintext.
         if request_state_security is None:
             security = RequestStateSecurity.ephemeral()
         else:
@@ -336,13 +337,20 @@ def _apply_extension(self, extension: Extension) -> None:
         self._lowlevel_server.extensions[extension.identifier] = extension.settings()
 
     def _install_extension_interceptor(self) -> None:
-        """Compose every extension's `tools/call` interceptor into one middleware.
+        """Wrap the `tools/call` handler with every extension's interceptor.
 
         Installed only when at least one extension overrides `intercept_tool_call`,
-        so a server with purely additive extensions adds no middleware.
+        so a server with purely additive extensions keeps the bare handler. The
+        chain wraps the handler itself, below the runner's outbound envelope
+        pass, so a short-circuiting interceptor's result is sieved and stamped
+        exactly like a handler result.
         """
         if any(type(e).intercept_tool_call is not Extension.intercept_tool_call for e in self._extensions):
-            self._lowlevel_server.middleware.append(compose_tool_call_interceptor(self._extensions))
+            self._lowlevel_server.add_request_handler(
+                "tools/call",
+                CallToolRequestParams,
+                compose_tool_call_handler(self._extensions, self._handle_call_tool),
+            )
 
     @overload
     def run(self, transport: Literal["stdio"] = ...) -> None: ...

src/mcp/server/runner.py

@@ -370,8 +370,9 @@ def _stamp_server_info(self, version: str, result: dict[str, Any]) -> dict[str,
 
         A handler-authored value wins, a non-mapping `_meta` is the handler's
         to own, and handshake-era results are never stamped. `result` is
-        pipeline-owned (`_dump_result` copies), but `_meta` may still be the
-        handler's object, so the stamp replaces it rather than writing into it.
+        pipeline-owned (`_dump_result` copies dicts; the spec-method sieve
+        re-dumps), but `_meta` may still be the handler's object, so the stamp
+        replaces it rather than writing into it.
         """
         if not self.server.include_server_info or version not in MODERN_PROTOCOL_VERSIONS:
             return result

tests/docs_src/test_lowlevel.py

@@ -87,8 +87,17 @@ async def test_output_schema_and_structured_content_are_both_yours_to_build() ->
             }
         )
         result = await client.call_tool("search_books", {"query": "dune", "limit": 5})
-        assert result.content == [TextContent(type="text", text="Found 3 books matching 'dune'.")]
-        assert result.structured_content == {"matches": 3, "query": "dune"}
+        # The page shows this exact payload; tutorial003 pins `version="2.0.0"` so
+        # the identity stamp is deterministic and the fence is proved verbatim.
+        assert result.model_dump(by_alias=True, exclude_none=True) == snapshot(
+            {
+                "_meta": {"io.modelcontextprotocol/serverInfo": {"name": "Bookshop", "version": "2.0.0"}},
+                "content": [{"type": "text", "text": "Found 3 books matching 'dune'."}],
+                "structuredContent": {"matches": 3, "query": "dune"},
+                "isError": False,
+                "resultType": "complete",
+            }
+        )
 
 
 async def test_the_client_checks_the_schema_you_promised() -> None:

tests/server/mcpserver/test_extension.py

@@ -2,18 +2,19 @@
 
 These exercise the closed set of extension contribution kinds - tools,
 resources, request methods, and the single `tools/call` interceptor - through
-the highest-level public surface (in-memory `Client`), plus the
-`compose_tool_call_interceptor` helper directly.
+the highest-level public surface (in-memory `Client`).
 """
 
-from typing import Any, Literal, cast
+from importlib.metadata import version
+from typing import Any, Literal
 
 import mcp_types as types
 import pytest
 from inline_snapshot import snapshot
 from mcp_types import (
     METHOD_NOT_FOUND,
     MISSING_REQUIRED_CLIENT_CAPABILITY,
+    SERVER_INFO_META_KEY,
     CallToolResult,
     TextContent,
 )
@@ -26,7 +27,6 @@
     MethodBinding,
     ResourceBinding,
     ToolBinding,
-    compose_tool_call_interceptor,
 )
 from mcp.server.mcpserver import Context, MCPServer, require_client_extension
 from mcp.server.mcpserver.resources import TextResource
@@ -222,23 +222,28 @@ async def test_short_circuiting_interceptor_replaces_tool_result() -> None:
     assert result == snapshot(CallToolResult(content=[TextContent(text="intercepted")]))
 
 
-def test_plain_extension_installs_no_tool_call_interceptor() -> None:
-    """SDK-defined: an extension that does not override `intercept_tool_call` adds no
-    middleware - the composed interceptor exists only when at least one extension
-    overrides it."""
-    baseline = len(MCPServer("test")._lowlevel_server.middleware)
+def test_plain_extension_leaves_the_tool_call_handler_bare() -> None:
+    """SDK-defined: an extension that does not override `intercept_tool_call` leaves
+    `tools/call` registered as the server's own handler - the interceptor chain is
+    composed only when at least one extension overrides it."""
     server = MCPServer("test", extensions=[_AdditiveExt()])
 
-    assert len(server._lowlevel_server.middleware) == baseline
+    entry = server._lowlevel_server.get_request_handler("tools/call")
+    assert entry is not None
+    assert entry.handler == server._handle_call_tool
 
 
-def test_overriding_extension_installs_one_tool_call_interceptor() -> None:
-    """SDK-defined: an extension that overrides `intercept_tool_call` composes exactly
-    one additional `tools/call` middleware."""
+def test_overriding_extension_wraps_the_tool_call_handler() -> None:
+    """SDK-defined: an extension that overrides `intercept_tool_call` re-registers
+    `tools/call` with the interceptor chain wrapped around the server's own handler,
+    and installs no middleware."""
     baseline = len(MCPServer("test")._lowlevel_server.middleware)
     server = MCPServer("test", extensions=[_ReplacingExt()])
 
-    assert len(server._lowlevel_server.middleware) == baseline + 1
+    entry = server._lowlevel_server.get_request_handler("tools/call")
+    assert entry is not None
+    assert entry.handler != server._handle_call_tool
+    assert len(server._lowlevel_server.middleware) == baseline
 
 
 async def test_default_interceptor_passes_through_alongside_an_overriding_one() -> None:
@@ -255,7 +260,7 @@ async def test_default_interceptor_passes_through_alongside_an_overriding_one()
 
 
 async def test_interceptors_run_in_registration_order_with_threaded_params() -> None:
-    """SDK-defined: `compose_tool_call_interceptor` nests extensions first-outermost, so
+    """SDK-defined: `compose_tool_call_handler` nests extensions first-outermost, so
     two passing-through interceptors record in registration order, each seeing the
     validated `tools/call` params (the real tool name)."""
     log: list[tuple[str, str]] = []
@@ -271,26 +276,18 @@ async def test_interceptors_run_in_registration_order_with_threaded_params() ->
     assert log == [("com.example/first", "echo"), ("com.example/second", "echo")]
 
 
-async def test_compose_tool_call_interceptor_passes_through_non_tools_call() -> None:
-    """SDK-defined: the composed middleware is a no-op for any method other than
-    `tools/call` - it forwards to `call_next` without touching the interceptors."""
-    sentinel = types.EmptyResult()
-
-    async def call_next(ctx: ServerRequestContext[Any, Any]) -> HandlerResult:
-        return sentinel
-
-    middleware = compose_tool_call_interceptor([_ReplacingExt()])
-    ctx = ServerRequestContext(
-        session=cast("Any", None),
-        lifespan_context={},
-        protocol_version="2026-07-28",
-        method="tasks/get",
-        params={"taskId": "t-1"},
-    )
+async def test_short_circuited_interceptor_result_carries_the_server_info_stamp() -> None:
+    """Spec-mandated (2026-07-28, #3002): an interceptor that answers without running
+    the tool still produces a stamped result - interception happens at the handler
+    layer, below the runner's outbound envelope pass."""
+    server = MCPServer("test", extensions=[_ReplacingExt()])
+    server.tool(name="echo", structured_output=False)(_echo)
 
-    result = await middleware(ctx, call_next)
+    async with Client(server) as client:
+        result = await client.call_tool("echo", {"value": "hi"})
 
-    assert result is sentinel
+    assert result.content == [TextContent(text="intercepted")]
+    assert result.meta == {SERVER_INFO_META_KEY: {"name": "test", "version": version("mcp")}}
 
 
 def test_extension_subclass_without_prefixed_identifier_is_rejected_at_definition() -> None:

tests/server/test_runner.py

@@ -1042,9 +1042,9 @@ async def custom(ctx: Ctx, params: RequestParams) -> dict[str, Any]:
 
 @pytest.mark.anyio
 async def test_stamping_never_mutates_a_handler_retained_result_dict(server: SrvT):
-    """SDK-defined: the stamp lands on a shallow copy at the runner's exit, so
-    a dict the handler retains (module-level, cached, shared) is never mutated
-    underneath it."""
+    """SDK-defined: the outbound pass dumps the handler's dict to a copy
+    (`_dump_result`) and the stamp writes into that copy, so a dict the handler
+    retains (module-level, cached, shared) is never mutated underneath it."""
 
     retained: dict[str, Any] = {"ok": True}