Let handler-raised MCPError keep its code and data in the prompt and resource pipelines

tools/call already re-raises MCPError so a handler can answer with a typed
protocol error (e.g. a missing-client-capability rejection with
data.requiredCapabilities); the prompt and resource pipelines wrapped it
into generic internal errors, destroying the code and data. Add the same
carve-out at the five wrap sites (Prompt.render, MCPServer.get_prompt,
ResourceTemplate.create_resource, FunctionResource.read,
MCPServer.read_resource) — this matters now that prompt and template
functions participate in the multi-round-trip flow and must be able to
reject a request themselves.

Also document that a tool whose dependencies elicit owns its request_state
channel, so handlers should not forward another result's InputRequiredResult
from such a tool.

Author: maxisbey

docs/migration.md

@@ -36,7 +36,9 @@ resource functions never return one). `Prompt.render()` and
 `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.
+`MCPServer.read_resource(uri, context)` directly — but not from a tool whose
+dependencies elicit via `Resolve(...)`: the resolver owns that tool's
+`request_state` channel, and a forwarded result's state would clobber it.
 
 ### `MCPError` raised from an `@mcp.tool()` handler now surfaces as a JSON-RPC error
 

src/mcp/server/mcpserver/context.py

@@ -105,7 +105,10 @@ async def read_resource(self, uri: str | AnyUrl) -> Iterable[ReadResourceContent
         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.
+        own result calls `MCPServer.read_resource(uri, context)` instead —
+        but not from a tool whose dependencies elicit via `Resolve(...)`:
+        the resolver owns that tool's `request_state` channel, and a
+        forwarded result's state would clobber it.
 
         Args:
             uri: Resource URI to read

src/mcp/server/mcpserver/prompts/base.py

@@ -14,6 +14,7 @@
 from mcp.server.mcpserver.utilities.context_injection import find_context_parameter, inject_context
 from mcp.server.mcpserver.utilities.func_metadata import func_metadata
 from mcp.shared._callable_inspection import is_async_callable
+from mcp.shared.exceptions import MCPError
 
 if TYPE_CHECKING:
     from mcp.server.context import LifespanContextT, RequestT
@@ -193,5 +194,7 @@ async def render(
                     raise ValueError(f"Could not convert prompt result to message: {msg}")
 
             return messages
+        except MCPError:
+            raise
         except Exception as e:
             raise ValueError(f"Error rendering prompt {self.name}: {e}")

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

@@ -17,6 +17,7 @@
 from mcp.server.mcpserver.utilities.func_metadata import func_metadata
 from mcp.server.mcpserver.utilities.logging import get_logger
 from mcp.shared._callable_inspection import is_async_callable
+from mcp.shared.exceptions import MCPError
 from mcp.shared.path_security import contains_path_traversal, is_absolute_path
 from mcp.shared.uri_template import UriTemplate
 
@@ -243,7 +244,7 @@ async def create_resource(
                 meta=self.meta,
                 fn=lambda: result,  # Capture result in closure
             )
-        except ResourceError:
+        except (ResourceError, MCPError):
             raise
         except Exception as exc:
             logger.exception(f"Error creating resource from template {uri}")

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

@@ -17,6 +17,7 @@
 
 from mcp.server.mcpserver.resources.base import Resource
 from mcp.shared._callable_inspection import is_async_callable
+from mcp.shared.exceptions import MCPError
 
 
 class TextResource(Resource):
@@ -79,6 +80,8 @@ async def read(self) -> str | bytes:
                 return result
             else:
                 return pydantic_core.to_json(result, fallback=str, indent=2).decode()
+        except MCPError:
+            raise
         except Exception as e:
             raise ValueError(f"Error reading resource {self.uri}: {e}")
 

src/mcp/server/mcpserver/server.py

@@ -519,6 +519,8 @@ async def read_resource(
         try:
             content = await resource.read()
             return [ReadResourceContents(content=content, mime_type=resource.mime_type, meta=resource.meta)]
+        except MCPError:
+            raise
         except Exception as exc:
             logger.exception(f"Error getting resource {uri}")
             # If an exception happens when reading the resource, we should not leak the exception to the client.
@@ -1232,6 +1234,8 @@ async def get_prompt(
                 description=prompt.description,
                 messages=pydantic_core.to_jsonable_python(rendered),
             )
+        except MCPError:
+            raise
         except Exception as e:
             logger.exception(f"Error getting prompt {name}")
             raise ValueError(str(e)) from e

tests/server/mcpserver/test_server.py

@@ -10,6 +10,7 @@
 from mcp_types import (
     INTERNAL_ERROR,
     INVALID_PARAMS,
+    MISSING_REQUIRED_CLIENT_CAPABILITY,
     AudioContent,
     BlobResourceContents,
     CallToolResult,
@@ -2104,6 +2105,69 @@ async def ask(topic: str, ctx: Context) -> str | InputRequiredResult:
     assert result is sentinel
 
 
+async def test_prompt_raising_mcp_error_surfaces_code_and_data_to_client():
+    """A handler-raised MCPError keeps its code and data through the prompt pipeline —
+    the same parity tools/call has, needed for self-service capability rejection."""
+    mcp = MCPServer()
+
+    @mcp.prompt()
+    async def briefing(ctx: Context) -> str:
+        raise MCPError(
+            code=MISSING_REQUIRED_CLIENT_CAPABILITY,
+            message="needs elicitation",
+            data={"requiredCapabilities": ["elicitation"]},
+        )
+
+    async with Client(mcp) as client:
+        with pytest.raises(MCPError) as exc:
+            await client.get_prompt("briefing")
+    assert exc.value.error.code == MISSING_REQUIRED_CLIENT_CAPABILITY
+    assert exc.value.error.message == "needs elicitation"
+    assert exc.value.error.data == {"requiredCapabilities": ["elicitation"]}
+
+
+async def test_resource_template_raising_mcp_error_surfaces_code_and_data_to_client():
+    """A handler-raised MCPError keeps its code and data through the resource template
+    pipeline instead of being wrapped into a generic ResourceError."""
+    mcp = MCPServer()
+
+    @mcp.resource("ask://{topic}")
+    async def ask(topic: str, ctx: Context) -> str:
+        raise MCPError(
+            code=MISSING_REQUIRED_CLIENT_CAPABILITY,
+            message="needs elicitation",
+            data={"requiredCapabilities": ["elicitation"]},
+        )
+
+    async with Client(mcp) as client:
+        with pytest.raises(MCPError) as exc:
+            await client.read_resource("ask://databases")
+    assert exc.value.error.code == MISSING_REQUIRED_CLIENT_CAPABILITY
+    assert exc.value.error.message == "needs elicitation"
+    assert exc.value.error.data == {"requiredCapabilities": ["elicitation"]}
+
+
+async def test_static_resource_raising_mcp_error_surfaces_code_and_data_to_client():
+    """A handler-raised MCPError keeps its code and data through the static resource
+    read path too — parity with the template path above."""
+    mcp = MCPServer()
+
+    @mcp.resource("static://thing")
+    def thing() -> str:
+        raise MCPError(
+            code=MISSING_REQUIRED_CLIENT_CAPABILITY,
+            message="needs elicitation",
+            data={"requiredCapabilities": ["elicitation"]},
+        )
+
+    async with Client(mcp) as client:
+        with pytest.raises(MCPError) as exc:
+            await client.read_resource("static://thing")
+    assert exc.value.error.code == MISSING_REQUIRED_CLIENT_CAPABILITY
+    assert exc.value.error.message == "needs elicitation"
+    assert exc.value.error.data == {"requiredCapabilities": ["elicitation"]}
+
+
 async def test_context_exposes_client_capabilities_from_connection():
     mcp = MCPServer()
     seen: list[ClientCapabilities | None] = []