Wrap crashing validators, treat ResourceError in a tool as anticipated

A custom argument validator that raises something other than
ValidationError escaped Tool.run unwrapped, losing the "Error executing
tool" prefix and the UnexpectedToolError type. It is now wrapped as a
crash, and an MCPError raised there still passes through.

A ResourceError (usually ResourceNotFoundError from ctx.read_resource)
that escapes a tool body is now classified like a ToolError, since it is
the same anticipated outcome resources/read logs at INFO. An
UnexpectedResourceError escaping a tool stays a crash.

MCPServer.read_resource is now the single place a resource crash is
wrapped (plus create_resource for templates), so the built-in Resource
types let the original exception propagate to direct callers.

Also: trimmed raise-site comments in favour of the exception docstrings,
reworded the ToolError and ResourceError docstrings, documented the
FunctionResource/FileResource.read change in migration.md, corrected the
uri-templates tip and example, and pinned the new cases in tests
(including a wire test for ResourceNotFoundError from a static resource).

Author: maxisbey

docs/handlers/logging.md

@@ -49,6 +49,8 @@ The default is `"INFO"`.
 
 `logging.basicConfig()` never replaces handlers that already exist. If you configure logging yourself before creating the server, your configuration wins.
 
+You also don't need a `try`/`except` in every handler just to record failures. When a tool or resource function raises, the SDK logs it for you. **[Handling errors](../servers/handling-errors.md#what-the-server-logs)** explains what gets logged and at which level.
+
 ## Try it
 
 Run the server with the MCP Inspector:
@@ -70,8 +72,6 @@ went to standard error: the terminal, not the wire.
     don't want log lines, you want spans. Your server already emits them: the SDK traces every
     message with OpenTelemetry out of the box. See **[OpenTelemetry](../run/opentelemetry.md)**.
 
-You also don't need a `try`/`except` in every handler just to record failures. When a tool or resource function raises, the SDK logs it for you. **[Handling errors](../servers/handling-errors.md#what-the-server-logs)** explains what gets logged and at which level.
-
 ## Recap
 
 * The MCP protocol's logging capability is deprecated by the 2026-07-28 spec and not replaced. Don't build on it.

docs/migration.md

@@ -1018,7 +1018,7 @@ except MCPError as e:
 
 Reading a missing resource now returns JSON-RPC error code `-32602` (invalid params) with the requested URI in `error.data` (`{"uri": ...}`), per [SEP-2164](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2164). Previously the server returned code `0` with no `data`. Clients can now reliably distinguish not-found from other errors; a resource handler (static or template) that raises `ResourceNotFoundError` (from `mcp.server.mcpserver.exceptions`) produces this same response.
 
-The underlying lookups now raise typed exceptions instead of `ValueError`. `ResourceManager.get_resource()` raises `ResourceNotFoundError` when no resource or template matches the URI, and `ResourceTemplate.create_resource()` raises `ResourceError` when the template function fails. Neither subclasses `ValueError`, so callers catching `ValueError` should switch to `ResourceNotFoundError` / `ResourceError` (both importable from `mcp.server.mcpserver.exceptions`; `ResourceNotFoundError` subclasses `ResourceError`).
+The underlying lookups now raise typed exceptions instead of `ValueError`. `ResourceManager.get_resource()` raises `ResourceNotFoundError` when no resource or template matches the URI, and `ResourceTemplate.create_resource()` raises `ResourceError` when the template function fails. Neither subclasses `ValueError`, so callers catching `ValueError` should switch to `ResourceNotFoundError` / `ResourceError` (both importable from `mcp.server.mcpserver.exceptions`; `ResourceNotFoundError` subclasses `ResourceError`). Likewise, `FunctionResource.read()` and `FileResource.read()` no longer wrap failures in `ValueError`: called directly they raise whatever the function or file read raised, and through `MCPServer.read_resource()` that arrives as `UnexpectedResourceError` (a `ResourceError`) with the original as `__cause__`.
 
 ### `Resource` classes reject unknown keyword arguments
 

docs/servers/handling-errors.md

@@ -123,7 +123,7 @@ It means a whole class of `raise` statements you don't write: don't re-validate
 
 ## What the server logs
 
-The server also logs these failures, and how it logs them depends on whether you anticipated the failure.
+The server also logs tool and resource failures, and how it logs them depends on whether you anticipated the failure.
 
 `get_author` raised a plain `ValueError`. The model got the message, but the SDK can't tell that you raised it on purpose, so it treats the call as a crash and logs it at `ERROR` with the full traceback. That is what you want on the day the exception is a `KeyError` from deep inside a library and the result text says only `'id'`.
 
@@ -135,7 +135,7 @@ When the failure is one you planned for, say so with `ToolError`:
 
 `ToolError` comes from `mcp.server.mcpserver.exceptions`. The model reads exactly what it read before. The difference is in your log, where a `ToolError` is a single `INFO` line with no traceback, so a production log at `WARNING` stays quiet until something is actually broken. Bad arguments and unknown tool names are logged at `INFO` too, because those are the caller's mistakes rather than yours.
 
-Resources work the same way. A crashing resource handler is logged at `ERROR` with its traceback, which matters more here because the `-32603` the client receives names only the URI. `ResourceNotFoundError` is an `INFO` line.
+Resources work the same way. A crashing resource handler is logged at `ERROR` with its traceback, which matters more here because the `-32603` the client receives names only the URI. `ResourceNotFoundError` and `ResourceError` are the anticipated kind and are logged at `INFO`.
 
 ## Recap
 

docs/servers/uri-templates.md

@@ -159,7 +159,7 @@ The built-in checks stop the common cases but can't know your sandbox
 boundary. For filesystem access, use `safe_join` to resolve the path
 and verify it stays inside your base directory:
 
-```python title="server.py" hl_lines="4 14"
+```python title="server.py" hl_lines="5 15"
 --8<-- "docs_src/uri_templates/tutorial002.py"
 ```
 
@@ -200,9 +200,9 @@ These checks are a heuristic pre-filter; for filesystem access,
 
 !!! tip
     If your handler can't fulfil the request (the file doesn't exist, the id is unknown), raise
-    `ResourceNotFoundError` from `mcp.server.mcpserver.exceptions`. The client gets `-32602` with
-    your message and the URI. Any other exception is treated as a crash and the client gets a
-    generic `-32603`. See **[Handling errors](handling-errors.md#a-resource-that-doesnt-exist)**.
+    `ResourceNotFoundError` as `read_manual` does above. The client gets `-32602` with your message
+    and the URI. An unexpected exception becomes a generic `-32603` instead. See
+    **[Handling errors](handling-errors.md#a-resource-that-doesnt-exist)**.
 
 ## Resources on the low-level Server
 

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.
 
-If `<message>` alone doesn't tell you what broke, look in the **server's log**. Unless the tool raised `ToolError`, the exception is logged there at `ERROR` with its traceback, as `Tool '<name>' raised an unexpected exception`.
+If `<message>` alone doesn't tell you what broke and the tool crashed (rather than raising `ToolError`, being unknown, or rejecting an argument), 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/uri_templates/tutorial002.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ResourceNotFoundError
 from mcp.shared.path_security import safe_join
 
 mcp = MCPServer("Bookshop")
@@ -11,4 +12,7 @@
 @mcp.resource("manuals://{+path}")
 def read_manual(path: str) -> str:
     """A staff manual page, served from a directory on disk."""
-    return safe_join(DOCS_ROOT, path).read_text()
+    file = safe_join(DOCS_ROOT, path)
+    if not file.is_file():
+        raise ResourceNotFoundError(f"No manual at {path!r}.")
+    return file.read_text()

src/mcp/server/mcpserver/context.py

@@ -169,8 +169,12 @@ async def read_resource(self, uri: str | AnyUrl) -> Iterable[ReadResourceContent
             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.
+            ResourceNotFoundError: If no resource or template matches the URI, or the
+                handler raised it.
+            ResourceError: If the resource or template function raises `ResourceError`.
+            UnexpectedResourceError: If the resource or template function raises anything
+                else. `__cause__` is the original exception. Left uncaught in a tool, this
+                is logged as the tool's crash, while the two above are not.
             RuntimeError: If the resource returned an `InputRequiredResult`.
         """
         assert self._mcp_server is not None, "Context is not available outside of a request"

src/mcp/server/mcpserver/exceptions.py

@@ -6,10 +6,18 @@ class MCPServerError(Exception):
 
 
 class ResourceError(MCPServerError):
-    """Error in resource operations.
-
-    When a resource or resource template handler raises this, its message reaches
-    the client as a `-32603` protocol error.
+    """A resource failure you anticipated.
+
+    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.
+
+    The SDK raises it too, and `UnexpectedResourceError` subclasses it, so
+    `except ResourceError` around `MCPServer.read_resource()` catches every read
+    failure, crash or not.
     """
 
 
@@ -25,20 +33,22 @@ class ResourceNotFoundError(ResourceError):
 class UnexpectedResourceError(ResourceError):
     """A resource read failed with something other than `ResourceError` or `MCPError`.
 
-    MCPServer raises this itself, around a crash in a resource or resource
-    template handler or a failed file read. You never raise it. `__cause__` is
-    the original exception, which the server logs with its traceback. The
-    message names only the URI, so the original text is withheld from the client.
+    The SDK raises this itself, around a crash in a resource or resource template
+    handler. You never raise it. `__cause__` is the original exception, which the
+    server logs with its traceback. The message names only the URI, so the
+    original text is withheld from the client.
     """
 
 
 class ToolError(MCPServerError):
-    """A tool failure the model should read.
+    """A tool failure you anticipated.
 
-    Raise this from a tool (or a resolver) for a failure you anticipate: the
+    Raise this from a tool (or a resolver) for a failure you saw coming: the
     call returns `is_error=True` with the message in `content`, and the server
     logs it at INFO without a traceback. Any other exception reaches the model
     the same way but is treated as a crash and logged at ERROR with its traceback.
+    A `ResourceError` that escapes the tool (say from `ctx.read_resource()`) counts
+    as 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`
@@ -49,7 +59,7 @@ class ToolError(MCPServerError):
 class UnexpectedToolError(ToolError):
     """A tool call failed with something other than `ToolError` or `MCPError`.
 
-    MCPServer raises this itself, around a crash in the tool (or a resolver) or a
+    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. `__cause__` is
     the original exception, which the server logs with its traceback before
     returning the usual `is_error=True` result. Catch it around

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

@@ -246,6 +246,4 @@ async def create_resource(
         except (ResourceError, MCPError):
             raise
         except Exception as exc:
-            # Name only the URI: the original text is withheld from the client, and
-            # the server logs the traceback from `__cause__`.
             raise UnexpectedResourceError(f"Error creating resource from template {uri}") from exc

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

@@ -16,10 +16,8 @@
 from mcp_types import Annotations, Icon, InputRequiredResult
 from pydantic import Field, validate_call
 
-from mcp.server.mcpserver.exceptions import ResourceError, UnexpectedResourceError
 from mcp.server.mcpserver.resources.base import Resource
 from mcp.shared._callable_inspection import is_async_callable
-from mcp.shared.exceptions import MCPError
 
 # `application/*` types that are textual but predate the `+json`/`+xml`
 # structured-syntax suffixes, so the suffix rule below can't catch them.
@@ -80,41 +78,29 @@ class FunctionResource(Resource):
     fn: Callable[[], Any] = Field(exclude=True)
 
     async def read(self) -> str | bytes:
-        """Read the resource by calling the wrapped function.
-
-        Raises:
-            UnexpectedResourceError: If the function raises anything other than
-                `ResourceError` or `MCPError`. `__cause__` is the original exception.
-        """
-        try:
-            fn = self.fn
-            if is_async_callable(fn):
-                result = await fn()
-            else:
-                result = await anyio.to_thread.run_sync(self.fn)
-
-            if isinstance(result, InputRequiredResult):
-                # A static resource function can never read the retry's
-                # input_responses (it takes no Context), so this can only be a
-                # mistake — reject it instead of JSON-dumping it as content.
-                raise ValueError(
-                    "static resources cannot return InputRequiredResult; only resource "
-                    "template functions participate in the multi-round-trip flow"
-                )
-            if isinstance(result, Resource):  # pragma: no cover
-                return await result.read()
-            elif isinstance(result, bytes):
-                return result
-            elif isinstance(result, str):
-                return result
-            else:
-                return pydantic_core.to_json(result, fallback=str, indent=2).decode()
-        except (MCPError, ResourceError):
-            raise
-        except Exception as exc:
-            # Name only the URI: the original text is withheld from the client, and
-            # the server logs the traceback from `__cause__`.
-            raise UnexpectedResourceError(f"Error reading resource {self.uri}") from exc
+        """Read the resource by calling the wrapped function."""
+        fn = self.fn
+        if is_async_callable(fn):
+            result = await fn()
+        else:
+            result = await anyio.to_thread.run_sync(self.fn)
+
+        if isinstance(result, InputRequiredResult):
+            # A static resource function can never read the retry's
+            # input_responses (it takes no Context), so this can only be a
+            # mistake — reject it instead of JSON-dumping it as content.
+            raise ValueError(
+                "static resources cannot return InputRequiredResult; only resource "
+                "template functions participate in the multi-round-trip flow"
+            )
+        if isinstance(result, Resource):  # pragma: no cover
+            return await result.read()
+        elif isinstance(result, bytes):
+            return result
+        elif isinstance(result, str):
+            return result
+        else:
+            return pydantic_core.to_json(result, fallback=str, indent=2).decode()
 
     @classmethod
     def from_function(
@@ -191,12 +177,9 @@ def validate_text_encoding(cls, encoding: str | None) -> str | None:
 
     async def read(self) -> str | bytes:
         """Read the file content."""
-        try:
-            if self.encoding is None:
-                return await anyio.to_thread.run_sync(self.path.read_bytes)
-            return await anyio.to_thread.run_sync(partial(self.path.read_text, encoding=self.encoding))
-        except Exception as exc:
-            raise UnexpectedResourceError(f"Error reading resource {self.uri}") from exc
+        if self.encoding is None:
+            return await anyio.to_thread.run_sync(self.path.read_bytes)
+        return await anyio.to_thread.run_sync(partial(self.path.read_text, encoding=self.encoding))
 
 
 class HttpResource(Resource):
@@ -236,18 +219,12 @@ def list_files(self) -> list[Path]:  # pragma: no cover
         if not self.path.is_dir():
             raise NotADirectoryError(f"Not a directory: {self.path}")
 
-        try:
-            if self.pattern:
-                return list(self.path.glob(self.pattern)) if not self.recursive else list(self.path.rglob(self.pattern))
-            return list(self.path.glob("*")) if not self.recursive else list(self.path.rglob("*"))
-        except Exception as exc:
-            raise ValueError(f"Error listing directory {self.path}: {exc}") from exc
+        if self.pattern:
+            return list(self.path.glob(self.pattern)) if not self.recursive else list(self.path.rglob(self.pattern))
+        return list(self.path.glob("*")) if not self.recursive else list(self.path.rglob("*"))
 
     async def read(self) -> str:  # Always returns JSON string  # pragma: no cover
         """Read the directory listing."""
-        try:
-            files = await anyio.to_thread.run_sync(self.list_files)
-            file_list = [str(f.relative_to(self.path)) for f in files if f.is_file()]
-            return json.dumps({"files": file_list}, indent=2)
-        except Exception as exc:
-            raise UnexpectedResourceError(f"Error reading resource {self.uri}") from exc
+        files = await anyio.to_thread.run_sync(self.list_files)
+        file_list = [str(f.relative_to(self.path)) for f in files if f.is_file()]
+        return json.dumps({"files": file_list}, indent=2)