Make Context.read_resource raise-only on InputRequiredResult

Drop the allow_input_required overloads: ctx.read_resource is a content
reader, so an InputRequiredResult from a resource template always raises,
with the error pointing at the forwarding path. A handler that wants to
receive and forward the result as its own calls
MCPServer.read_resource(uri, context) directly, which carries the union.

Author: maxisbey

docs/migration.md

@@ -33,10 +33,10 @@ methods directly, narrow with `isinstance` (or
 resource functions never return one). `Prompt.render()` and
 `ResourceTemplate.create_resource()` carry the same union.
 
-`ctx.read_resource()` inside a handler is unchanged by default: it still
-returns content and raises `RuntimeError` if the resource requests input; pass
-`allow_input_required=True` to receive the `InputRequiredResult` and forward it
-as the handler's own result.
+`ctx.read_resource()` inside a handler is unchanged: it still returns content,
+and raises `RuntimeError` if the resource requests input. A handler that wants
+to receive the `InputRequiredResult` and forward it as its own result calls
+`MCPServer.read_resource(uri, context)` directly.
 
 ### `MCPError` raised from an `@mcp.tool()` handler now surfaces as a JSON-RPC error
 

src/mcp/server/mcpserver/context.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterable, Mapping
-from typing import TYPE_CHECKING, Any, Generic, Literal, cast, overload
+from typing import TYPE_CHECKING, Any, Generic, cast
 
 from mcp_types import ClientCapabilities, InputRequiredResult, InputResponseRequestParams, InputResponses, LoggingLevel
 from pydantic import AnyUrl, BaseModel
@@ -99,47 +99,31 @@ async def report_progress(self, progress: float, total: float | None = None, mes
         """
         await self.request_context.session.report_progress(progress, total, message)
 
-    @overload
-    async def read_resource(
-        self, uri: str | AnyUrl, *, allow_input_required: Literal[False] = False
-    ) -> Iterable[ReadResourceContents]: ...
-
-    @overload
-    async def read_resource(
-        self, uri: str | AnyUrl, *, allow_input_required: bool
-    ) -> Iterable[ReadResourceContents] | InputRequiredResult: ...
-
-    async def read_resource(
-        self, uri: str | AnyUrl, *, allow_input_required: bool = False
-    ) -> Iterable[ReadResourceContents] | InputRequiredResult:
+    async def read_resource(self, uri: str | AnyUrl) -> Iterable[ReadResourceContents]:
         """Read a resource by URI.
 
+        This is a content reader: an `InputRequiredResult` returned by a
+        resource template function (the 2026-07-28 multi-round-trip flow)
+        raises here. A handler that wants to receive and forward one as its
+        own result calls `MCPServer.read_resource(uri, context)` instead.
+
         Args:
             uri: Resource URI to read
-            allow_input_required: When `False` (default), an
-                `InputRequiredResult` returned by a resource template function
-                (the 2026-07-28 multi-round-trip flow) raises instead of being
-                returned. Pass `True` to receive it — a handler may forward it
-                as its own result; the retry's answers then arrive on
-                `ctx.input_responses`.
 
         Returns:
-            The resource content as either text or bytes, or — only with
-            `allow_input_required=True` — the `InputRequiredResult` the
-            resource template function returned.
+            The resource content as either text or bytes
 
         Raises:
             ResourceNotFoundError: If no resource or template matches the URI.
             ResourceError: If template creation or resource reading fails.
-            RuntimeError: If the resource returned an `InputRequiredResult`
-                and `allow_input_required` is `False`.
+            RuntimeError: If the resource returned an `InputRequiredResult`.
         """
         assert self._mcp_server is not None, "Context is not available outside of a request"
         result = await self._mcp_server.read_resource(uri, self)
-        if isinstance(result, InputRequiredResult) and not allow_input_required:
+        if isinstance(result, InputRequiredResult):
             raise RuntimeError(
-                "Resource returned InputRequiredResult; pass allow_input_required=True to "
-                "receive it and forward it as this handler's result."
+                "Resource returned InputRequiredResult; ctx.read_resource() only returns "
+                "content — use MCPServer.read_resource(uri, context) to receive and forward it."
             )
         return result
 

tests/server/mcpserver/test_server.py

@@ -2071,9 +2071,9 @@ async def ask(topic: str, ctx: Context) -> str | InputRequiredResult:
     assert contents.text == "databases notes for Alice"
 
 
-async def test_context_read_resource_raises_on_input_required_result_by_default():
+async def test_context_read_resource_raises_on_input_required_result():
     """ctx.read_resource is a content reader: an InputRequiredResult from the template
-    raises with the opt-in hint instead of widening every caller (mirrors ClientSession)."""
+    raises with a pointer at the forwarding path instead of widening every caller."""
     mcp = MCPServer()
 
     @mcp.resource("ask://{topic}")
@@ -2084,14 +2084,14 @@ async def ask(topic: str, ctx: Context) -> str | InputRequiredResult:
     with pytest.raises(RuntimeError) as exc:
         await context.read_resource("ask://databases")
     assert str(exc.value) == snapshot(
-        "Resource returned InputRequiredResult; pass allow_input_required=True to receive it "
-        "and forward it as this handler's result."
+        "Resource returned InputRequiredResult; ctx.read_resource() only returns "
+        "content — use MCPServer.read_resource(uri, context) to receive and forward it."
     )
 
 
-async def test_context_read_resource_with_allow_input_required_forwards_the_result():
-    """With allow_input_required=True the handler receives the template's
-    InputRequiredResult unchanged and may forward it as its own result."""
+async def test_mcpserver_read_resource_returns_input_required_result_for_handler_forwarding():
+    """MCPServer.read_resource hands the template's InputRequiredResult to a direct caller
+    unchanged — the composition path for a handler that forwards it as its own result."""
     mcp = MCPServer()
     sentinel = InputRequiredResult(input_requests={"who": _ask_who()})
 
@@ -2100,7 +2100,7 @@ async def ask(topic: str, ctx: Context) -> str | InputRequiredResult:
         return sentinel
 
     context = Context(mcp_server=mcp)
-    result = await context.read_resource("ask://databases", allow_input_required=True)
+    result = await mcp.read_resource("ask://databases", context)
     assert result is sentinel