Cleanup + relocate MCP errors.

Author: fennb

pydantic_ai_slim/pydantic_ai/exceptions.py

@@ -23,8 +23,6 @@
     'UnexpectedModelBehavior',
     'UsageLimitExceeded',
     'ModelHTTPError',
-    'MCPError',
-    'MCPServerError',
     'IncompleteToolCall',
     'FallbackExceptionGroup',
 )
@@ -161,58 +159,6 @@ def __init__(self, status_code: int, model_name: str, body: object | None = None
         super().__init__(message)
 
 
-class MCPError(RuntimeError):
-    """Base class for errors occurring during interaction with an MCP server."""
-
-    message: str
-    """The error message."""
-
-    def __init__(self, message: str):
-        self.message = message
-        super().__init__(message)
-
-    def __str__(self) -> str:
-        return self.message
-
-
-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[Any]):
     """A group of exceptions that can be raised when all fallback models fail."""
 

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -42,9 +42,59 @@
 
 # after mcp imports so any import error maps to this file, not _mcp.py
 from . import _mcp, _utils, exceptions, messages, models
-from .exceptions import MCPServerError
 
-__all__ = 'MCPServer', 'MCPServerStdio', 'MCPServerHTTP', 'MCPServerSSE', 'MCPServerStreamableHTTP', 'load_mcp_servers'
+__all__ = (
+    'MCPServer',
+    'MCPServerStdio',
+    'MCPServerHTTP',
+    'MCPServerSSE',
+    'MCPServerStreamableHTTP',
+    'load_mcp_servers',
+    'MCPError',
+)
+
+
+class MCPError(RuntimeError):
+    """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.
+    """
+
+    message: str
+    """The error message."""
+
+    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):
+        self.message = message
+        self.code = code
+        self.data = data
+        super().__init__(message)
+
+    @classmethod
+    def from_mcp_sdk_error(cls, error: Any) -> MCPError:
+        """Create an MCPError from an MCP SDK McpError.
+
+        Args:
+            error: An McpError from the MCP SDK.
+
+        Returns:
+            A new MCPError 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})'
+
 
 TOOL_SCHEMA_VALIDATOR = pydantic_core.SchemaValidator(
     schema=pydantic_core.core_schema.dict_schema(
@@ -322,30 +372,30 @@ async def list_resources(self) -> list[_mcp.Resource]:
         - We also don't subscribe to resource changes to avoid complexity.
 
         Raises:
-            MCPServerError: If the server returns an error.
+            MCPError: If the server returns an error.
         """
         async with self:  # Ensure server is running
             if not self.capabilities.resources:
                 return []
             try:
                 result = await self._client.list_resources()
             except mcp_exceptions.McpError as e:
-                raise MCPServerError.from_mcp_sdk_error(e) from e
+                raise MCPError.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:
-            MCPServerError: If the server returns an error.
+            MCPError: If the server returns an error.
         """
         async with self:  # Ensure server is running
             if not self.capabilities.resources:
                 return []
             try:
                 result = await self._client.list_resource_templates()
             except mcp_exceptions.McpError as e:
-                raise MCPServerError.from_mcp_sdk_error(e) from e
+                raise MCPError.from_mcp_sdk_error(e) from e
         return [_mcp.map_from_mcp_resource_template(t) for t in result.resourceTemplates]
 
     @overload
@@ -372,7 +422,7 @@ async def read_resource(
             Returns `None` if the server does not support resources or the resource is not found.
 
         Raises:
-            MCPServerError: If the server returns an error other than resource not found.
+            MCPError: If the server returns an error other than resource not found.
         """
         resource_uri = uri if isinstance(uri, str) else uri.uri
         async with self:  # Ensure server is running
@@ -384,7 +434,7 @@ async def read_resource(
                 # As per https://modelcontextprotocol.io/specification/2025-06-18/server/resources#error-handling
                 if e.error.code == -32002:
                     return None
-                raise MCPServerError.from_mcp_sdk_error(e) from e
+                raise MCPError.from_mcp_sdk_error(e) from e
 
         if not result.contents:
             return None

tests/test_mcp.py

@@ -26,12 +26,11 @@
 from pydantic_ai._mcp import Resource, ServerCapabilities
 from pydantic_ai.agent import Agent
 from pydantic_ai.exceptions import (
-    MCPServerError,
     ModelRetry,
     UnexpectedModelBehavior,
     UserError,
 )
-from pydantic_ai.mcp import MCPServerStreamableHTTP, load_mcp_servers
+from pydantic_ai.mcp import MCPError, MCPServerStreamableHTTP, load_mcp_servers
 from pydantic_ai.models import Model
 from pydantic_ai.models.test import TestModel
 from pydantic_ai.tools import RunContext
@@ -1545,10 +1544,10 @@ async def test_read_resource_template(run_context: RunContext[int]):
 
 
 async def test_read_resource_not_found(mcp_server: MCPServerStdio) -> None:
-    """Test that read_resource raises MCPServerError for non-existent resources with non-standard error codes."""
+    """Test that read_resource raises MCPError for non-existent resources with non-standard error codes."""
     async with mcp_server:
         # FastMCP uses error code 0 instead of -32002, so it should raise
-        with pytest.raises(MCPServerError, match='Unknown resource: resource://does_not_exist') as exc_info:
+        with pytest.raises(MCPError, 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
@@ -1589,7 +1588,7 @@ async def test_read_resource_empty_contents(mcp_server: MCPServerStdio) -> None:
 
 
 async def test_list_resources_error(mcp_server: MCPServerStdio) -> None:
-    """Test that list_resources converts McpError to MCPServerError."""
+    """Test that list_resources converts McpError to MCPError."""
     mcp_error = McpError(
         error=ErrorData(code=-32603, message='Failed to list resources', data={'details': 'server overloaded'})
     )
@@ -1600,7 +1599,7 @@ async def test_list_resources_error(mcp_server: MCPServerStdio) -> None:
             'list_resources',
             new=AsyncMock(side_effect=mcp_error),
         ):
-            with pytest.raises(MCPServerError, match='Failed to list resources') as exc_info:
+            with pytest.raises(MCPError, match='Failed to list resources') as exc_info:
                 await mcp_server.list_resources()
 
             # Verify the exception has the expected attributes
@@ -1613,7 +1612,7 @@ async def test_list_resources_error(mcp_server: MCPServerStdio) -> None:
 
 
 async def test_list_resource_templates_error(mcp_server: MCPServerStdio) -> None:
-    """Test that list_resource_templates converts McpError to MCPServerError."""
+    """Test that list_resource_templates converts McpError to MCPError."""
     mcp_error = McpError(error=ErrorData(code=-32001, message='Service unavailable'))
 
     async with mcp_server:
@@ -1622,7 +1621,7 @@ async def test_list_resource_templates_error(mcp_server: MCPServerStdio) -> None
             'list_resource_templates',
             new=AsyncMock(side_effect=mcp_error),
         ):
-            with pytest.raises(MCPServerError, match='Service unavailable') as exc_info:
+            with pytest.raises(MCPError, match='Service unavailable') as exc_info:
                 await mcp_server.list_resource_templates()
 
             # Verify the exception has the expected attributes