Allow ToolError to carry arbitrary content for isError=True results

Previously there was no way to return non-text content (e.g. images,
embedded resources) with isError=True. A plain ToolError("msg") only
produced a text error. Now ToolError accepts an optional `content`
keyword argument with a list of ContentBlock items. When present,
_handle_call_tool uses that content in the CallToolResult instead
of wrapping the message as TextContent.

A plain `raise ToolError("message")` still works exactly as before.
ToolError is now re-exported from mcp.server.mcpserver for easier
imports.

Fixes #348

Author: Sachin

src/mcp/server/mcpserver/__init__.py

@@ -13,6 +13,7 @@
 )
 
 from .context import Context
+from .exceptions import ToolError
 from .prompts.base import AssistantMessage, Message, UserMessage
 from .resolve import (
     AcceptedElicitation,
@@ -31,6 +32,7 @@
 __all__ = [
     "MCPServer",
     "Context",
+    "ToolError",
     "Image",
     "Audio",
     "Message",

src/mcp/server/mcpserver/exceptions.py

@@ -1,5 +1,12 @@
 """Custom exceptions for MCPServer."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcp_types import ContentBlock
+
 
 class MCPServerError(Exception):
     """Base error for MCPServer."""
@@ -19,7 +26,29 @@ class ResourceNotFoundError(ResourceError):
 
 
 class ToolError(MCPServerError):
-    """Error in tool operations."""
+    """Error in tool operations.
+
+    Raise this from a tool function to signal an execution error that
+    the LLM should see (``CallToolResult(is_error=True)``).
+
+    A plain ``ToolError("message")`` produces a text-only error result.
+    To return arbitrary content (images, embedded resources, etc.)
+    alongside the error flag, pass a ``content`` list::
+
+        raise ToolError(
+            "screenshot shows the failure",
+            content=[
+                TextContent(type="text", text="see attached"),
+                ImageContent(type="image", data=b64, mime_type="image/png"),
+            ],
+        )
+    """
+
+    content: list[ContentBlock] | None
+
+    def __init__(self, message: str = "", *, content: list[ContentBlock] | None = None) -> None:
+        super().__init__(message)
+        self.content = content
 
 
 class InvalidSignature(Exception):

src/mcp/server/mcpserver/server.py

@@ -71,7 +71,7 @@
 from mcp.server.lowlevel.server import LifespanResultT, Server
 from mcp.server.lowlevel.server import lifespan as default_lifespan
 from mcp.server.mcpserver.context import Context
-from mcp.server.mcpserver.exceptions import ResourceError, ResourceNotFoundError
+from mcp.server.mcpserver.exceptions import ResourceError, ResourceNotFoundError, ToolError
 from mcp.server.mcpserver.prompts import Prompt, PromptManager
 from mcp.server.mcpserver.resources import (
     DEFAULT_RESOURCE_SECURITY,
@@ -421,6 +421,11 @@ async def _handle_call_tool(
             return await self.call_tool(params.name, params.arguments or {}, context)
         except MCPError:
             raise
+        except ToolError as e:
+            logger.exception(f"Error calling tool {params.name}")
+            if e.content is not None:
+                return CallToolResult(content=e.content, is_error=True)
+            return CallToolResult(content=[TextContent(type="text", text=str(e))], is_error=True)
         except Exception as e:
             return CallToolResult(content=[TextContent(type="text", text=str(e))], is_error=True)