Cleanup MCP error naming and usage.

Author: fennb

pydantic_ai_slim/pydantic_ai/exceptions.py

@@ -24,7 +24,7 @@
     'UsageLimitExceeded',
     'ModelHTTPError',
     'MCPError',
-    'ServerCapabilitiesError',
+    'MCPServerCapabilitiesError',
     'MCPServerError',
     'FallbackExceptionGroup',
 )
@@ -175,7 +175,7 @@ def __str__(self) -> str:
         return self.message
 
 
-class ServerCapabilitiesError(MCPError):
+class MCPServerCapabilitiesError(MCPError):
     """Raised when attempting to access server capabilities that aren't present."""
 
 

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -31,8 +31,8 @@
     from mcp.client.sse import sse_client
     from mcp.client.stdio import StdioServerParameters, stdio_client
     from mcp.client.streamable_http import GetSessionIdCallback, streamablehttp_client
+    from mcp.shared import exceptions as mcp_exceptions
     from mcp.shared.context import RequestContext
-    from mcp.shared.exceptions import McpError
     from mcp.shared.message import SessionMessage
 except ImportError as _import_error:
     raise ImportError(
@@ -42,6 +42,7 @@
 
 # after mcp imports so any import error maps to this file, not _mcp.py
 from . import _mcp, _utils, exceptions, messages, models
+from .exceptions import MCPServerCapabilitiesError, MCPServerError
 
 __all__ = 'MCPServer', 'MCPServerStdio', 'MCPServerHTTP', 'MCPServerSSE', 'MCPServerStreamableHTTP', 'load_mcp_servers'
 
@@ -246,7 +247,7 @@ async def direct_call_tool(
                     ),
                     mcp_types.CallToolResult,
                 )
-            except McpError as e:
+            except mcp_exceptions.McpError as e:
                 raise exceptions.ModelRetry(e.error.message)
 
         if result.isError:
@@ -321,32 +322,32 @@ async def list_resources(self) -> list[_mcp.Resource]:
         - We also don't subscribe to resource changes to avoid complexity.
 
         Raises:
-            ServerCapabilitiesError: If the server does not support resources.
+            MCPServerCapabilitiesError: 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')
+                raise MCPServerCapabilitiesError('Server does not support resources capability')
             try:
                 result = await self._client.list_resources()
-            except McpError as e:
-                raise exceptions.MCPServerError.from_mcp_sdk_error(e) from e
+            except mcp_exceptions.McpError as e:
+                raise 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.
+            MCPServerCapabilitiesError: 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')
+                raise MCPServerCapabilitiesError('Server does not support resources capability')
             try:
                 result = await self._client.list_resource_templates()
-            except McpError as e:
-                raise exceptions.MCPServerError.from_mcp_sdk_error(e) from e
+            except mcp_exceptions.McpError as e:
+                raise MCPServerError.from_mcp_sdk_error(e) from e
         return [_mcp.map_from_mcp_resource_template(t) for t in result.resourceTemplates]
 
     @overload
@@ -370,17 +371,17 @@ async def read_resource(
             If the resource has multiple content items, returns a list of items.
 
         Raises:
-            ServerCapabilitiesError: If the server does not support resources.
+            MCPServerCapabilitiesError: 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')
+                raise MCPServerCapabilitiesError('Server does not support resources capability')
             try:
                 result = await self._client.read_resource(AnyUrl(resource_uri))
-            except McpError as e:
-                raise exceptions.MCPServerError.from_mcp_sdk_error(e) from e
+            except mcp_exceptions.McpError as e:
+                raise MCPServerError.from_mcp_sdk_error(e) from e
         return (
             self._get_content(result.contents[0])
             if len(result.contents) == 1

tests/test_mcp.py

@@ -26,9 +26,9 @@
 from pydantic_ai._mcp import Resource, ServerCapabilities
 from pydantic_ai.agent import Agent
 from pydantic_ai.exceptions import (
+    MCPServerCapabilitiesError,
     MCPServerError,
     ModelRetry,
-    ServerCapabilitiesError,
     UnexpectedModelBehavior,
     UserError,
 )
@@ -1603,16 +1603,16 @@ async def test_capabilities(mcp_server: MCPServerStdio) -> None:
 
 
 async def test_resource_methods_without_capability(mcp_server: MCPServerStdio) -> None:
-    """Test that resource methods raise ServerCapabilitiesError when resources capability is not available."""
+    """Test that resource methods raise MCPServerCapabilitiesError when resources capability is not available."""
     async with mcp_server:
         # Mock the capabilities to not support resources
         mock_capabilities = ServerCapabilities(resources=False)
         with patch.object(mcp_server, '_server_capabilities', mock_capabilities):
-            with pytest.raises(ServerCapabilitiesError, match='Server does not support resources capability'):
+            with pytest.raises(MCPServerCapabilitiesError, match='Server does not support resources capability'):
                 await mcp_server.list_resources()
 
-            with pytest.raises(ServerCapabilitiesError, match='Server does not support resources capability'):
+            with pytest.raises(MCPServerCapabilitiesError, match='Server does not support resources capability'):
                 await mcp_server.list_resource_templates()
 
-            with pytest.raises(ServerCapabilitiesError, match='Server does not support resources capability'):
+            with pytest.raises(MCPServerCapabilitiesError, match='Server does not support resources capability'):
                 await mcp_server.read_resource('resource://test')