Re-raise MCPError from @mcp.tool() handlers as a top-level JSON-RPC error

The tool wrapper at Tool.run() was catching MCPError along with all other
exceptions and re-wrapping it as ToolError, which _handle_call_tool then
flattens into CallToolResult(isError=True). This discards the JSON-RPC
error code and structured data, so a tool raising e.g.
MISSING_REQUIRED_CLIENT_CAPABILITY couldn't produce a protocol-level
error response.

UrlElicitationRequiredError was already special-cased; since it subclasses
MCPError, generalising the re-raise to MCPError covers both and any future
protocol-error subclass.

Author: maxisbey

docs/migration.md

@@ -19,6 +19,20 @@ If you call `MCPServer.call_tool()` directly, read `.content` and
 `.structured_content` off the returned `CallToolResult` instead of branching on
 the result type.
 
+### `MCPError` raised from an `@mcp.tool()` handler now surfaces as a JSON-RPC error
+
+Raising `MCPError` (or a subclass such as `UrlElicitationRequiredError`) inside
+an `@mcp.tool()` handler now produces a top-level JSON-RPC error response with
+the raised `code`, `message`, and `data` intact. Previously the tool wrapper
+caught it like any other exception and returned `CallToolResult(isError=True)`,
+which discarded the error code and structured `data`.
+
+`MCPError` carries `ErrorData` and is the SDK's protocol-error type — raise it
+when the request itself should be rejected (missing client capability,
+elicitation required, invalid parameters). For tool *execution* failures the
+calling LLM should see and react to, raise any other exception or return
+`CallToolResult(is_error=True, ...)` directly; that path is unchanged.
+
 ### `streamablehttp_client` removed
 
 The deprecated `streamablehttp_client` function has been removed. Use `streamable_http_client` instead.

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

@@ -10,7 +10,7 @@
 from mcp.server.mcpserver.utilities.context_injection import find_context_parameter
 from mcp.server.mcpserver.utilities.func_metadata import FuncMetadata, func_metadata
 from mcp.shared._callable_inspection import is_async_callable
-from mcp.shared.exceptions import UrlElicitationRequiredError
+from mcp.shared.exceptions import MCPError
 from mcp.shared.tool_name_validation import validate_and_warn_tool_name
 from mcp.types import Icon, ToolAnnotations
 
@@ -111,9 +111,12 @@ async def run(
                 result = self.fn_metadata.convert_result(result)
 
             return result
-        except UrlElicitationRequiredError:
-            # Re-raise UrlElicitationRequiredError so it can be properly handled
-            # as an MCP error response with code -32042
+        except MCPError:
+            # `MCPError` (and subclasses such as `UrlElicitationRequiredError`)
+            # carries a JSON-RPC `ErrorData(code, message, data)` and means
+            # "respond with a protocol error" - re-raise so the kernel surfaces
+            # it as a top-level JSON-RPC error rather than wrapping it as a
+            # `CallToolResult(isError=True)` execution failure.
             raise
         except Exception as e:
             raise ToolError(f"Error executing tool {self.name}: {e}") from e

tests/server/mcpserver/tools/test_base.py

@@ -1,5 +1,9 @@
-from mcp.server.mcpserver import Context
+import pytest
+
+from mcp import Client, types
+from mcp.server.mcpserver import Context, MCPServer
 from mcp.server.mcpserver.tools.base import Tool
+from mcp.shared.exceptions import MCPError
 
 
 def test_context_detected_in_union_annotation():
@@ -8,3 +12,45 @@ def my_tool(x: int, ctx: Context | None) -> str:
 
     tool = Tool.from_function(my_tool)
     assert tool.context_kwarg == "ctx"
+
+
+@pytest.mark.anyio
+async def test_mcperror_raised_from_a_tool_surfaces_as_a_top_level_jsonrpc_error_with_code_and_data_intact():
+    """SDK-defined: ``MCPError`` carries JSON-RPC ``ErrorData(code, message, data)``
+    and means "respond with a protocol error". The tool wrapper re-raises it so
+    the kernel writes a top-level JSON-RPC error - ``code`` and ``data`` survive
+    the round-trip rather than being flattened into ``CallToolResult(isError=True)``."""
+    mcp = MCPServer(name="srv")
+
+    @mcp.tool()
+    async def needs_sampling() -> str:
+        raise MCPError(
+            types.MISSING_REQUIRED_CLIENT_CAPABILITY,
+            "sampling capability required",
+            data={"requiredCapabilities": ["sampling"]},
+        )
+
+    async with Client(mcp) as client:
+        with pytest.raises(MCPError) as exc_info:
+            await client.call_tool("needs_sampling", {})
+
+    assert exc_info.value.error.code == types.MISSING_REQUIRED_CLIENT_CAPABILITY
+    assert exc_info.value.error.data == {"requiredCapabilities": ["sampling"]}
+
+
+@pytest.mark.anyio
+async def test_non_mcperror_exception_raised_from_a_tool_is_wrapped_as_an_is_error_result():
+    """SDK-defined: ordinary exceptions from a tool body are execution failures
+    the LLM should see, so they become ``CallToolResult(isError=True)`` rather
+    than a protocol-level JSON-RPC error. Pins the other arm of the same branch."""
+    mcp = MCPServer(name="srv")
+
+    @mcp.tool()
+    async def boom() -> str:
+        raise RuntimeError("execution failure")
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("boom", {})
+
+    assert isinstance(result, types.CallToolResult)
+    assert result.is_error is True