Inline handler logging and trim the docs

Log at the two handler sites directly instead of through a shared
helper: the tool site checks for ToolError, the resource site only has
to ask whether it caught an UnexpectedResourceError.

Drop the three transport-matrix logging tests and their requirement
ids from the interaction suite, which is for wire behaviour; the same
properties are covered next to MCPServer in test_server.py.

Shorten the logging docs to a pointer, reword the handling-errors
section plainly, and drop the recap bullet and prompt caveats.

Author: maxisbey

docs/handlers/logging.md

@@ -70,7 +70,7 @@ 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 don't have to log your own handlers' crashes either. When a tool or resource function raises something unexpected, the SDK writes the `ERROR` record with the traceback for you, on its own `mcp.*` loggers; a failure you raised deliberately (`ToolError`, `ResourceNotFoundError`) is an `INFO` line instead. A prompt function that raises is an `ERROR` record too, whatever it raised. **[Handling errors](../servers/handling-errors.md#what-lands-in-your-log)** has the split. (In a test using `Client(mcp, raise_exceptions=True)`, a prompt failure is handed to your test as the exception rather than logged.)
+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
 

docs/servers/handling-errors.md

@@ -118,26 +118,24 @@ It means a whole class of `raise` statements you don't write: don't re-validate
     Everything so far is what a **client** sees, and the in-memory `Client` you'll write tests
     with sees exactly the same thing. Even `raise_exceptions=True` doesn't hand a failing tool's
     exception back to the caller: by the time that flag could act, your exception is already the
-    `is_error=True` result. Assert on the result; the traceback is in the server's log (next
-    section), which pytest's `caplog` captures. **[Testing](../get-started/testing.md)** covers the pattern.
+    `is_error=True` result. Assert on the result. If you need the traceback, it is in the server's
+    log (next section), and pytest's `caplog` captures it. **[Testing](../get-started/testing.md)** covers the pattern.
 
-## What lands in your log
+## What the server logs
 
-Your server keeps its own record of these failures, and it draws one more line: between a failure you anticipated and one you didn't.
+The server also logs these 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 know you *meant* that exception, so it assumes you didn't: the call is logged at `ERROR` with the full traceback. That is exactly what you want on the day the exception is a `KeyError` from three libraries down and the result text says only `'id'`.
+`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'`.
 
 When the failure is one you planned for, say so with `ToolError`:
 
 ```python title="server.py" hl_lines="2 12-13"
 --8<-- "docs_src/handling_errors/tutorial004.py"
 ```
 
-The model reads precisely what it read before. The difference is on your side: a `ToolError` is logged as one `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 `INFO` lines too; those are the caller's mistakes, not yours.
+`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 draw the same line. The `-32603` from a crashing resource handler names only the URI, so the `ERROR` record in your log is the one place the cause and its traceback exist. `ResourceNotFoundError`, including the SDK's own `Unknown resource`, is an `INFO` line. (A template parameter that fails its type annotation, `books://{id}` read with an `id` that isn't an `int`, currently counts as a crash.)
-
-Prompts aren't split yet: any failure in a prompt function, including an unknown name or a missing argument, is one `ERROR` record with its traceback, written by the transport layer that turns it into the JSON-RPC error.
+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.
 
 ## Recap
 
@@ -146,8 +144,7 @@ Prompts aren't split yet: any failure in a prompt function, including an unknown
 * The deciding question: *could a smarter model have avoided this?* Yes -> exception. No -> `MCPError`.
 * `ResourceNotFoundError` from a resource handler -> the protocol's `-32602`, with the URI in `data`.
 * Bad arguments are rejected against the schema before your function runs; you don't `raise` for those.
-* In your log: an exception you didn't raise as `ToolError` is an `ERROR` record with its traceback; `ToolError`, bad tool arguments, unknown tool names, and `ResourceNotFoundError` are one `INFO` line each.
-* `from mcp import MCPError`; `ToolError` and `ResourceNotFoundError` come from `mcp.server.mcpserver.exceptions`; the error-code constants come from `mcp.types`.
+* `from mcp import MCPError`; the error-code constants come from `mcp.types`.
 
 Errors handled. That is everything a server *exposes*. What every handler can read, and do back to the client while it runs, is the next section: **[Inside your handler](../handlers/index.md)**.
 

docs/servers/uri-templates.md

@@ -201,9 +201,8 @@ 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, and your log gets one `INFO` line; any other exception is treated as
-    a crash (`-32603`, and an `ERROR` record with the traceback). See
-    **[Handling errors](handling-errors.md#a-resource-that-doesnt-exist)**.
+    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)**.
 
 ## 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, the traceback is in the **server's log**: an exception the tool didn't raise as `ToolError` is logged there at `ERROR`, as `Tool '<name>' raised an unexpected exception`.
+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`.
 
 ## `TypeError: The @tool decorator was used incorrectly. Did you forget to call it? Use @tool() instead of @tool`
 

src/mcp/server/mcpserver/exceptions.py

@@ -16,8 +16,8 @@ class ResourceError(MCPServerError):
 class ResourceNotFoundError(ResourceError):
     """Resource does not exist.
 
-    Raise this from a resource handler to signal that the requested instance does not exist;
-    clients receive `-32602` (invalid params) per
+    Raise this from a resource handler to signal that the requested instance does not exist.
+    Clients receive `-32602` (invalid params) per
     [SEP-2164](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2164).
     """
 
@@ -26,7 +26,7 @@ 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
+    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.
     """
@@ -50,7 +50,7 @@ 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
-    return value that fails output conversion; you never raise it. `__cause__` is
+    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
     `MCPServer.call_tool()` to tell a crash from a deliberate `ToolError`.

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

@@ -217,7 +217,7 @@ async def create_resource(
         Raises:
             ResourceError: If the template function raises `ResourceError`.
             UnexpectedResourceError: If the template function raises anything other
-                than `ResourceError` or `MCPError`; `__cause__` is the original.
+                than `ResourceError` or `MCPError`. `__cause__` is the original exception.
         """
         try:
             # Add context to params if needed

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

@@ -84,7 +84,7 @@ async def read(self) -> str | bytes:
 
         Raises:
             UnexpectedResourceError: If the function raises anything other than
-                `ResourceError` or `MCPError`; `__cause__` is the original.
+                `ResourceError` or `MCPError`. `__cause__` is the original exception.
         """
         try:
             fn = self.fn

src/mcp/server/mcpserver/server.py

@@ -427,7 +427,14 @@ async def _handle_call_tool(
         except MCPError:
             raise
         except Exception as exc:
-            _log_handler_exception("Tool", params.name, exc)
+            # A ToolError (deliberate, unknown tool, rejected arguments) is an outcome
+            # the model already reads in full, so it is one INFO record, repr-quoted to
+            # keep peer-supplied text on one line. Anything else is a crash in the
+            # tool: log the traceback that the result text doesn't carry.
+            if isinstance(exc, ToolError) and not isinstance(exc, UnexpectedToolError):
+                logger.info("Tool %r failed: %r", params.name, str(exc))
+            else:
+                logger.exception("Tool %r raised an unexpected exception", params.name)
             return CallToolResult(content=[TextContent(type="text", text=str(exc))], is_error=True)
 
     async def _handle_list_resources(
@@ -442,7 +449,13 @@ async def _handle_read_resource(
         try:
             results = await self.read_resource(params.uri, context)
         except ResourceError as err:
-            _log_handler_exception("Resource", str(params.uri), err)
+            # UnexpectedResourceError wraps a crash whose text is withheld from the
+            # client, so the traceback goes to the log. Any other ResourceError was
+            # raised on purpose (or is the SDK's "Unknown resource") and is one INFO record.
+            if isinstance(err, UnexpectedResourceError):
+                logger.exception("Resource %r raised an unexpected exception", str(params.uri))
+            else:
+                logger.info("Resource %r failed: %r", str(params.uri), str(err))
             code = INVALID_PARAMS if isinstance(err, ResourceNotFoundError) else INTERNAL_ERROR
             raise MCPError(code=code, message=str(err), data={"uri": str(params.uri)})
         if isinstance(results, InputRequiredResult):
@@ -511,8 +524,8 @@ async def call_tool(
             ToolError: If the tool is unknown, the arguments fail validation, or the
                 tool (or a resolver) raises `ToolError`.
             UnexpectedToolError: If the tool (or a resolver) raises anything other than
-                `ToolError` or `MCPError`, or its return value fails output conversion;
-                `__cause__` is the original.
+                `ToolError` or `MCPError`, or its return value fails output conversion.
+                `__cause__` is the original exception.
         """
         if context is None:
             context = Context(mcp_server=self, subscriptions=self._subscriptions)
@@ -566,8 +579,8 @@ async def read_resource(
             ResourceNotFoundError: If no resource or template matches the URI.
             ResourceError: If the resource or template function raises `ResourceError`.
             UnexpectedResourceError: If reading the resource (or creating it from a
-                template) raises anything other than `ResourceError` or `MCPError`;
-                `__cause__` is the original.
+                template) raises anything other than `ResourceError` or `MCPError`.
+                `__cause__` is the original exception.
         """
         if context is None:
             context = Context(mcp_server=self, subscriptions=self._subscriptions)
@@ -1320,25 +1333,6 @@ async def get_prompt(
             raise ValueError(str(e)) from e
 
 
-def _log_handler_exception(kind: Literal["Tool", "Resource"], name: str, exc: Exception) -> None:
-    """Record a tool or resource handler failure; the one place MCPServer logs them.
-
-    Called from the `except` block that turns the failure into a response. A
-    `ToolError` or `ResourceError` (deliberate, an unknown name, arguments that
-    failed validation, `ResourceNotFoundError`) is an anticipated outcome the
-    client already receives in full: one INFO record, no traceback, the text
-    repr-quoted so peer-supplied names and newlines stay on one line. Anything
-    else, including the `Unexpected*` wrappers whose `__cause__` is what the
-    handler actually raised, is a crash in user code: ERROR with the traceback.
-    """
-    if isinstance(exc, ToolError | ResourceError) and not isinstance(
-        exc, UnexpectedToolError | UnexpectedResourceError
-    ):
-        logger.info("%s %r failed: %r", kind, name, str(exc))
-    else:
-        logger.exception("%s %r raised an unexpected exception", kind, name, exc_info=exc)
-
-
 def _version_gated(method: MethodBinding) -> RequestHandler:
     """Wrap a method handler so a request at a disallowed protocol version is rejected.
 

tests/docs_src/test_handling_errors.py

@@ -90,7 +90,7 @@ async def test_a_title_the_template_knows_reads_normally() -> None:
 
 
 async def test_a_plain_exception_is_logged_as_a_crash_with_its_traceback(caplog: pytest.LogCaptureFixture) -> None:
-    """tutorial001, "What lands in your log": the `ValueError` is one ERROR record carrying the traceback."""
+    """tutorial001, "What the server logs": the `ValueError` is one ERROR record carrying the traceback."""
     caplog.set_level(logging.INFO)
     async with Client(tutorial001.mcp) as client:
         await client.call_tool("get_author", {"title": "Nothing"})
@@ -99,7 +99,6 @@ async def test_a_plain_exception_is_logged_as_a_crash_with_its_traceback(caplog:
     assert record.exc_info is not None
     logged = record.exc_info[1]
     assert logged is not None and isinstance(logged.__cause__, ValueError)
-    assert str(logged.__cause__) == "No book titled 'Nothing' in the catalog."
 
 
 async def test_tool_error_reads_the_same_to_the_model_and_logs_one_info_line(
@@ -119,7 +118,7 @@ async def test_tool_error_reads_the_same_to_the_model_and_logs_one_info_line(
 
 
 async def test_a_bad_argument_is_an_info_line_not_a_crash(caplog: pytest.LogCaptureFixture) -> None:
-    """ "What lands in your log": schema rejection of the arguments is logged at INFO with no traceback."""
+    """ "What the server logs": schema rejection of the arguments is logged at INFO with no traceback."""
     caplog.set_level(logging.INFO)
     async with Client(tutorial001.mcp) as client:
         result = await client.call_tool("get_author", {"title": 42})

tests/interaction/_requirements.py

@@ -1020,14 +1020,6 @@ def __post_init__(self) -> None:
             "tool result with isError true and the failure text in content; it does not become a JSON-RPC error."
         ),
     ),
-    "mcpserver:tool:handler-throws:logged": Requirement(
-        source="sdk",
-        behavior=(
-            "An exception other than ToolError raised by a tool function is logged server-side exactly once, "
-            "at ERROR with its traceback, before the isError result is returned; the transport does not change "
-            "how many records are written."
-        ),
-    ),
     "mcpserver:tool:input-validation": Requirement(
         source=f"{SPEC_BASE_URL}/server/tools#error-handling",
         behavior=(
@@ -1319,13 +1311,6 @@ def __post_init__(self) -> None:
             "(-32603 Internal error), with the original exception text withheld."
         ),
     ),
-    "mcpserver:resource:read-throws:logged": Requirement(
-        source="sdk",
-        behavior=(
-            "The exception withheld from the -32603 response is logged server-side exactly once, at ERROR "
-            "with its traceback; the transport does not change how many records are written."
-        ),
-    ),
     "mcpserver:resource:static": Requirement(
         source="sdk",
         behavior=(
@@ -1442,14 +1427,6 @@ def __post_init__(self) -> None:
         source="sdk",
         behavior="A prompt with optional arguments can be fetched without supplying them.",
     ),
-    "mcpserver:prompt:render-throws:logged": Requirement(
-        source="sdk",
-        behavior=(
-            "An exception raised by a prompt function is logged server-side exactly once, at ERROR with its "
-            "traceback, by whichever layer turns it into the JSON-RPC error; the transport does not change how "
-            "many records are written."
-        ),
-    ),
     "mcpserver:prompt:unknown-name": Requirement(
         source=f"{SPEC_BASE_URL}/server/prompts#error-handling",
         behavior="prompts/get for a name that was never registered returns JSON-RPC error -32602 (Invalid params).",