Address review: keep three anticipated failures out of the crash path, docs sweep

- pre_parse_json leaves a string alone when json.loads refuses it with
  something other than JSONDecodeError (over-long integer, deep nesting),
  so validation rejects it as a bad argument instead of it surfacing as a
  crash with a traceback per request.
- convert_result skips output-schema validation for a returned
  CallToolResult(is_error=True); an error result has no structured content
  to check, and the author's message now reaches the client as written.
- read_resource checks that Resource.read() returned str or bytes, so a
  mistyped custom resource is logged as a crash and answered with -32603
  rather than "Invalid request parameters" with no log record.
- Docs and examples that still said "raise any exception and the model
  reads it" now say ToolError; deprecated.md lists the deprecated
  FuncMetadata helper; docstrings spell out the MCPError carve-out and the
  nested-crash __cause__.
- Two tests tightened: the prompt argument-validation test proves the body
  never ran, and the invalid-types check asserts on validate_arguments.

Author: maxisbey

docs/deprecated.md

@@ -1,6 +1,6 @@
 # Deprecated features
 
-The 2026-07-28 spec retires five things. The SDK still implements every one of them, and every one of them now carries a **deprecation warning**.
+The 2026-07-28 spec retires five things. The SDK still implements every one of them, and every one of them now carries a **deprecation warning**. One SDK helper is deprecated on its own account and is listed [at the end](#deprecated-sdk-helpers).
 
 The table below names each deprecated feature, why it is going away, and the replacement to build on.
 
@@ -129,13 +129,22 @@ That is the whole API. There is no per-method switch, and you don't want one: th
     One line of pytest configuration, and a deprecated call can never sneak back into your
     codebase without failing a test.
 
+## Deprecated SDK helpers
+
+These are not spec changes, only SDK internals with a better replacement. They warn with the same `MCPDeprecationWarning` and will be removed in 3.0.
+
+| Deprecated | What you do instead |
+|---|---|
+| `FuncMetadata.call_fn_with_arg_validation()` | `FuncMetadata.validate_arguments()` and then `FuncMetadata.call_fn()`. Only code that drives `FuncMetadata` directly (a custom `Tool` subclass, say) ever called it. |
+
 ## Recap
 
 * The 2026-07-28 spec deprecates **roots**, server-initiated **sampling**, and protocol **logging** (all [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)), restricts **progress** to server-to-client, and removes **`ping`**.
 * The replacement column points you onward: **[Multi-round-trip requests](handlers/multi-round-trip.md)** for sampling and roots, **[Logging](handlers/logging.md)** for logging, **[Progress](handlers/progress.md)** for progress. `ping` needs nothing at all.
 * Deprecated is advisory: no wire changes, everything keeps working against pre-2026 sessions, and you get a visible `MCPDeprecationWarning` (a `UserWarning`, so it is on by default).
 * Sampling and roots additionally need a back-channel that a 2026-07-28 session does not have. On a modern connection they warn and then they raise.
 * `warnings.filterwarnings("ignore", category=MCPDeprecationWarning)` silences the whole category; `"error::mcp.MCPDeprecationWarning"` in pytest turns it into a test failure.
+* One SDK helper, `FuncMetadata.call_fn_with_arg_validation()`, is deprecated separately for removal in 3.0.
 * New code should not be built on any of these.
 
 Every other page in these docs teaches the current API.

docs/get-started/real-host.md

@@ -6,7 +6,7 @@ Which means connecting to a host is one act: you tell it **the command that star
 
 ## One server, every host
 
-```python title="server.py" hl_lines="3 33-34"
+```python title="server.py" hl_lines="4 34-35"
 --8<-- "docs_src/real_host/tutorial001.py"
 ```
 

docs/get-started/testing.md

@@ -79,8 +79,8 @@ There you go! You can now extend your tests to cover more scenarios.
 Two different things can go wrong, and this flag only touches one of them.
 
 An exception inside one of **your tools** is not a protocol failure. It becomes a normal result with
-`is_error=True`, and the model reads the message. `raise_exceptions` doesn't change that: with or
-without it, `call_tool` returns the same `is_error=True` result. There's a whole page on it:
+`is_error=True` (and if it was a `ToolError`, the model reads your message). `raise_exceptions` doesn't
+change that: with or without it, `call_tool` returns the same `is_error=True` result. There's a whole page on it:
 **[Handling errors](../servers/handling-errors.md)**.
 
 A failure **outside** a tool body is different. On the connection `Client(mcp)` gives you, the

docs/migration.md

@@ -992,8 +992,8 @@ its behavior is unchanged.
 `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.
+calling LLM should see and react to, raise `ToolError` or return
+`CallToolResult(is_error=True, ...)` directly.
 
 The client sees this change too. `Client.call_tool()` and
 `ClientSession.call_tool()` raise on a JSON-RPC error response, so a tool that

docs/troubleshooting.md

@@ -92,7 +92,7 @@ result.structured_content  # None
 
 The fix is in your client: **check `result.is_error`**. A `try/except` around `call_tool` catches none of these, because there is nothing to catch. This is deliberate, and it is the single most useful thing on this page to internalise: the *model* chose the call, so the model gets the message and a chance to try again. **[Handling errors](servers/handling-errors.md)** is the whole story, including the `MCPError` path that *does* raise.
 
-The bare form, `Error executing tool <name>` with no message, means the tool **crashed**: something other than `ToolError` was raised while running it (or its return value failed the output schema), and that exception's text is kept off the wire. The traceback is in the **server's log** at `ERROR`, as `Tool '<name>' raised an unexpected exception`.
+The bare form, `Error executing tool <name>` with no message, means the tool **crashed**: an exception it didn't anticipate escaped it (or its return value failed the output schema), and that exception's text is kept off the wire. The traceback is in the **server's log** at `ERROR`, as `Tool '<name>' raised an unexpected exception`.
 
 ## `TypeError: The @tool decorator was used incorrectly. Did you forget to call it? Use @tool() instead of @tool`
 

docs_src/real_host/tutorial001.py

@@ -1,4 +1,5 @@
 from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
 
 mcp = MCPServer("Bookshop")
 
@@ -20,7 +21,7 @@ def search_books(query: str) -> list[str]:
 def get_author(title: str) -> str:
     """Look up the author of a book in the catalog."""
     if title not in CATALOG:
-        raise ValueError(f"No book titled {title!r} in the catalog.")
+        raise ToolError(f"No book titled {title!r} in the catalog.")
     return CATALOG[title]
 
 

examples/servers/everything-server/mcp_everything_server/server.py

@@ -13,6 +13,7 @@
 import click
 from mcp.server import ServerRequestContext
 from mcp.server.mcpserver import Context, MCPServer, RequestStateSecurity
+from mcp.server.mcpserver.exceptions import ToolError
 from mcp.server.mcpserver.prompts.base import Prompt, UserMessage
 from mcp.server.streamable_http import EventCallback, EventMessage, EventStore
 from mcp.shared.exceptions import MCPError
@@ -328,7 +329,7 @@ async def test_elicitation_sep1330_enums(ctx: Context) -> str:
 @mcp.tool()
 def test_error_handling() -> str:
     """Tests error response handling"""
-    raise RuntimeError("This tool intentionally returns an error for testing")
+    raise ToolError("This tool intentionally returns an error for testing")
 
 
 @mcp.tool()

src/mcp/server/mcpserver/exceptions.py

@@ -11,9 +11,9 @@ class ResourceError(MCPServerError):
     Raise this from a resource or resource template handler for a failure you saw
     coming: the client receives a `-32603` protocol error carrying your message
     (`ResourceNotFoundError` below is the `-32602` variant), and the server logs it
-    at INFO without a traceback. Any other exception is treated as a crash: the
-    client gets a generic message naming only the URI, and the server logs the
-    traceback at ERROR.
+    at INFO without a traceback. Any other exception (bar `MCPError`, which is a
+    protocol error) is treated as a crash: the client gets a generic message naming
+    only the URI, and the server logs the traceback at ERROR.
 
     The SDK raises it too, and `UnexpectedResourceError` subclasses it, so
     `except ResourceError` around `MCPServer.read_resource()` catches every read
@@ -45,11 +45,12 @@ class ToolError(MCPServerError):
 
     Raise this from a tool (or a resolver) for a failure you saw coming: the
     call returns `is_error=True` with your message in `content` for the model to
-    read, and the server logs it at INFO without a traceback. Any other exception
-    (bar `MCPError`, which is a protocol error) is treated as a crash: the model
-    sees only `Error executing tool <name>`, and the server logs the traceback at
-    ERROR. A `ResourceError` that escapes the tool (say from `ctx.read_resource()`)
-    counts as anticipated too.
+    read, and the server logs it at INFO without a traceback. A `ResourceError`
+    that escapes the tool (say from `ctx.read_resource()`) counts the same. Any
+    other exception bar `MCPError` (a protocol error) is treated as a crash: the
+    model sees only `Error executing tool <name>`, and the server logs the
+    traceback at ERROR. Inside a pydantic validator, raise `ValueError` as pydantic
+    expects; it arrives as an argument-validation failure, which is anticipated too.
 
     The SDK raises it too, for an unknown tool name and for arguments that fail
     the input schema, and `UnexpectedToolError` subclasses it, so `except ToolError`
@@ -58,13 +59,14 @@ class ToolError(MCPServerError):
 
 
 class UnexpectedToolError(ToolError):
-    """A tool call failed with something other than `ToolError` or `MCPError`.
+    """A tool call failed with something other than `ToolError`, `ResourceError`, or `MCPError`.
 
     The SDK raises this itself, around a crash in the tool (or a resolver) or a
     return value that fails output conversion. You never raise it. The message is
     only `Error executing tool <name>` (followed by the same for a nested tool or
     resource that crashed), so nothing from the original reaches the client.
-    `__cause__` is the original exception, which the server logs with its
+    `__cause__` is the original exception (or, for a nested tool or resource
+    crash, its `Unexpected...Error` wrapper), which the server logs with its
     traceback before returning the `is_error=True` result. Catch it around
     `MCPServer.call_tool()` to tell a crash from a deliberate `ToolError`.
     """

src/mcp/server/mcpserver/server.py

@@ -6,7 +6,7 @@
 import inspect
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
-from typing import Any, Generic, Literal, TypeVar, overload
+from typing import Any, Generic, Literal, TypeVar, cast, overload
 
 import anyio
 import pydantic_core
@@ -524,7 +524,8 @@ async def call_tool(
                 tool (or a resolver) raises `ToolError` or `ResourceError`.
             UnexpectedToolError: If the tool (or a resolver) raises anything else, or
                 its return value fails output conversion. `__cause__` is the original
-                exception.
+                exception (or, for a nested tool or resource crash, its wrapper).
+            MCPError: Raised by the tool or a resolver; passed through unchanged.
         """
         if context is None:
             context = Context(mcp_server=self, subscriptions=self._subscriptions)
@@ -580,14 +581,18 @@ async def read_resource(
             UnexpectedResourceError: If reading the resource (or creating it from a
                 template) raises anything other than `ResourceError` or `MCPError`.
                 `__cause__` is the original exception.
+            MCPError: Raised by the resource or template function; passed through unchanged.
         """
         if context is None:
             context = Context(mcp_server=self, subscriptions=self._subscriptions)
         try:
             resource = await self._resource_manager.get_resource(uri, context)
             if isinstance(resource, InputRequiredResult):
                 return resource
-            content = await resource.read()
+            # Checked at runtime because a Resource subclass may not honour the annotation.
+            content = cast(object, await resource.read())
+            if not isinstance(content, str | bytes):
+                raise TypeError(f"Resource.read() must return str or bytes, not {type(content).__name__}")
             return [ReadResourceContents(content=content, mime_type=resource.mime_type, meta=resource.meta)]
         except (MCPError, ResourceError):
             raise

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -182,7 +182,7 @@ def convert_result(self, result: Any) -> CallToolResult | InputRequiredResult:
         # A schema published without a model (hand-built metadata) is advertised but not validated here.
         output_model = self.output_model if self.output_schema is not None else None
         if isinstance(result, CallToolResult):
-            if output_model is not None:
+            if output_model is not None and not result.is_error:
                 self._output_adapter(output_model).validate_python(result.structured_content)
             return result
 
@@ -234,8 +234,10 @@ def pre_parse_json(self, data: dict[str, Any]) -> dict[str, Any]:
             if isinstance(data_value, str) and field_info.annotation is not str:
                 try:
                     pre_parsed = json.loads(data_value)
-                except json.JSONDecodeError:
-                    continue  # Not JSON - skip
+                except (ValueError, RecursionError):
+                    # Not JSON, or JSON the parser refuses (over-long integers, deep
+                    # nesting): leave the string for validation to accept or reject.
+                    continue
                 if isinstance(pre_parsed, str | int | float):
                     # This is likely that the raw value is e.g. `"hello"` which we
                     # Should really be parsed as '"hello"' in Python - but if we parse