Add MCPServerError and use it appropriately upon upstream resource errors.

Author: fennb

pydantic_ai_slim/pydantic_ai/exceptions.py

@@ -25,6 +25,7 @@
     'ModelHTTPError',
     'MCPError',
     'ServerCapabilitiesError',
+    'MCPServerError',
     'FallbackExceptionGroup',
 )
 
@@ -178,6 +179,44 @@ class ServerCapabilitiesError(MCPError):
     """Raised when attempting to access server capabilities that aren't present."""
 
 
+class MCPServerError(MCPError):
+    """Raised when an MCP server returns an error response.
+
+    This exception wraps error responses from MCP servers, following the ErrorData schema
+    from the MCP specification.
+    """
+
+    code: int
+    """The error code returned by the server."""
+
+    data: Any | None
+    """Additional information about the error, if provided by the server."""
+
+    def __init__(self, message: str, code: int, data: Any | None = None):
+        super().__init__(message)
+        self.code = code
+        self.data = data
+
+    @classmethod
+    def from_mcp_sdk_error(cls, error: Any) -> MCPServerError:
+        """Create an MCPServerError from an MCP SDK McpError.
+
+        Args:
+            error: An McpError from the MCP SDK.
+
+        Returns:
+            A new MCPServerError instance with the error data.
+        """
+        # Extract error data from the McpError.error attribute
+        error_data = error.error
+        return cls(message=error_data.message, code=error_data.code, data=error_data.data)
+
+    def __str__(self) -> str:
+        if self.data:
+            return f'{self.message} (code: {self.code}, data: {self.data})'
+        return f'{self.message} (code: {self.code})'
+
+
 class FallbackExceptionGroup(ExceptionGroup):
     """A group of exceptions that can be raised when all fallback models fail."""
 

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -322,23 +322,31 @@ async def list_resources(self) -> list[_mcp.Resource]:
 
         Raises:
             ServerCapabilitiesError: If the server does not support resources.
+            MCPServerError: If the server returns an error.
         """
         async with self:  # Ensure server is running
             if not self.capabilities.resources:
                 raise exceptions.ServerCapabilitiesError('Server does not support resources capability')
-            result = await self._client.list_resources()
+            try:
+                result = await self._client.list_resources()
+            except McpError as e:
+                raise exceptions.MCPServerError.from_mcp_sdk_error(e) from e
         return [_mcp.map_from_mcp_resource(r) for r in result.resources]
 
     async def list_resource_templates(self) -> list[_mcp.ResourceTemplate]:
         """Retrieve resource templates that are currently present on the server.
 
         Raises:
             ServerCapabilitiesError: If the server does not support resources.
+            MCPServerError: If the server returns an error.
         """
         async with self:  # Ensure server is running
             if not self.capabilities.resources:
                 raise exceptions.ServerCapabilitiesError('Server does not support resources capability')
-            result = await self._client.list_resource_templates()
+            try:
+                result = await self._client.list_resource_templates()
+            except McpError as e:
+                raise exceptions.MCPServerError.from_mcp_sdk_error(e) from e
         return [_mcp.map_from_mcp_resource_template(t) for t in result.resourceTemplates]
 
     @overload
@@ -363,12 +371,16 @@ async def read_resource(
 
         Raises:
             ServerCapabilitiesError: If the server does not support resources.
+            MCPServerError: If the server returns an error (e.g., resource not found).
         """
         resource_uri = uri if isinstance(uri, str) else uri.uri
         async with self:  # Ensure server is running
             if not self.capabilities.resources:
                 raise exceptions.ServerCapabilitiesError('Server does not support resources capability')
-            result = await self._client.read_resource(AnyUrl(resource_uri))
+            try:
+                result = await self._client.read_resource(AnyUrl(resource_uri))
+            except McpError as e:
+                raise exceptions.MCPServerError.from_mcp_sdk_error(e) from e
         return (
             self._get_content(result.contents[0])
             if len(result.contents) == 1

tests/test_mcp.py

@@ -25,7 +25,13 @@
 )
 from pydantic_ai._mcp import Resource, ServerCapabilities
 from pydantic_ai.agent import Agent
-from pydantic_ai.exceptions import ModelRetry, ServerCapabilitiesError, UnexpectedModelBehavior, UserError
+from pydantic_ai.exceptions import (
+    MCPServerError,
+    ModelRetry,
+    ServerCapabilitiesError,
+    UnexpectedModelBehavior,
+    UserError,
+)
 from pydantic_ai.mcp import MCPServerStreamableHTTP, load_mcp_servers
 from pydantic_ai.models import Model
 from pydantic_ai.models.test import TestModel
@@ -1539,6 +1545,17 @@ async def test_read_resource_template(run_context: RunContext[int]):
         assert content == snapshot('Hello, Alice!')
 
 
+async def test_read_resource_not_found(mcp_server: MCPServerStdio) -> None:
+    """Test that read_resource raises MCPServerError for non-existent resources."""
+    async with mcp_server:
+        with pytest.raises(MCPServerError, match='Unknown resource: resource://does_not_exist') as exc_info:
+            await mcp_server.read_resource('resource://does_not_exist')
+
+        # Verify the exception has the expected attributes
+        assert exc_info.value.code == 0
+        assert exc_info.value.message == 'Unknown resource: resource://does_not_exist'
+
+
 def test_load_mcp_servers(tmp_path: Path):
     config = tmp_path / 'mcp.json'