mcp.client.exceptions ===================== .. py:module:: mcp.client.exceptions .. autoapi-nested-parse:: MCP Client Exception Classes. This module defines all exception types used by the MCP client implementation. These exceptions follow the MCP protocol error specifications and provide detailed error information for debugging and error handling. Exceptions ---------- .. autoapisummary:: mcp.client.exceptions.MCPAuthenticationError mcp.client.exceptions.MCPCapabilityError mcp.client.exceptions.MCPConnectionError mcp.client.exceptions.MCPError mcp.client.exceptions.MCPProtocolError mcp.client.exceptions.MCPTimeoutError mcp.client.exceptions.MCPToolError mcp.client.exceptions.MCPTransportError Module Contents --------------- .. py:exception:: MCPAuthenticationError(message: str, error_code: Optional[int] = None, details: Optional[Dict[str, Any]] = None) Bases: :py:obj:`MCPError` Authentication failure with MCP server. Raised when authentication is required but fails, or when authorization is denied for a specific operation. This includes token validation failures and permission issues. .. rubric:: Examples Invalid token:: raise MCPAuthenticationError( "Invalid authentication token", error_code=401 ) Insufficient permissions:: raise MCPAuthenticationError( "Insufficient permissions for tool execution", details={"tool": "sensitive_operation", "required_scope": "admin"} ) .. py:exception:: MCPCapabilityError(message: str, error_code: Optional[int] = None, details: Optional[Dict[str, Any]] = None) Bases: :py:obj:`MCPProtocolError` Error related to MCP capabilities. Raised when there are issues with capability negotiation, unsupported capabilities, or capability validation failures. This indicates a mismatch between client requirements and server capabilities. .. rubric:: Examples Unsupported capability:: raise MCPCapabilityError( "Server doesn't support required capability", details={"required": "tools", "supported": ["logging"]} ) .. py:exception:: MCPConnectionError(message: str, error_code: Optional[int] = None, details: Optional[Dict[str, Any]] = None) Bases: :py:obj:`MCPError` Error during MCP connection establishment or management. Raised when there are issues connecting to, maintaining, or disconnecting from an MCP server. This includes transport-level failures, timeout issues, and connection state problems. .. rubric:: Examples Connection timeout:: raise MCPConnectionError("Connection timeout after 30s") Transport failure:: raise MCPConnectionError( "Failed to start server process", details={"command": ["npx", "server"], "exit_code": 1} ) .. py:exception:: MCPError(message: str, error_code: Optional[int] = None, details: Optional[Dict[str, Any]] = None) Bases: :py:obj:`Exception` Base exception for all MCP-related errors. This is the root exception class for all MCP client errors. It provides a consistent interface for error handling and includes optional error details and context information. :param message: Human-readable error description :param error_code: MCP protocol error code (if applicable) :param details: Additional error details or context .. rubric:: Examples Basic error:: raise MCPError("Connection failed") With error code:: raise MCPError("Invalid request", error_code=-32600) With details:: raise MCPError( "Tool execution failed", details={"tool": "filesystem", "args": {...}} ) .. py:method:: __str__() -> str Return formatted error message. .. py:attribute:: details .. py:attribute:: error_code :value: None .. py:attribute:: message .. py:exception:: MCPProtocolError(message: str, error_code: Optional[int] = None, details: Optional[Dict[str, Any]] = None) Bases: :py:obj:`MCPError` Error in MCP protocol communication. Raised when there are protocol-level issues such as invalid messages, unsupported protocol versions, or malformed responses. This indicates a problem with the MCP protocol implementation or server compliance. .. rubric:: Examples Protocol version mismatch:: raise MCPProtocolError( "Unsupported protocol version", details={"client": "1.0", "server": "0.9"} ) Invalid message format:: raise MCPProtocolError( "Malformed JSON-RPC message", error_code=-32700, details={"raw_message": "invalid json"} ) .. py:exception:: MCPTimeoutError(message: str, error_code: Optional[int] = None, details: Optional[Dict[str, Any]] = None) Bases: :py:obj:`MCPConnectionError` Timeout during MCP operation. Raised when an MCP operation (connection, tool call, etc.) exceeds the configured timeout period. This is a specialized connection error that specifically indicates timing issues. :param operation: Name of the operation that timed out :param timeout: Timeout value that was exceeded .. rubric:: Examples Tool execution timeout:: raise MCPTimeoutError( "Tool call timed out", details={"operation": "call_tool", "timeout": 30.0} ) .. py:exception:: MCPToolError(message: str, error_code: Optional[int] = None, details: Optional[Dict[str, Any]] = None) Bases: :py:obj:`MCPError` Error during tool execution. Raised when there are issues executing tools on the MCP server. This includes tool not found errors, invalid arguments, and execution failures. .. rubric:: Examples Tool not found:: raise MCPToolError( "Tool not found", details={"tool_name": "nonexistent_tool"} ) Invalid arguments:: raise MCPToolError( "Invalid tool arguments", details={"tool": "read_file", "error": "path is required"} ) .. py:exception:: MCPTransportError(message: str, error_code: Optional[int] = None, details: Optional[Dict[str, Any]] = None) Bases: :py:obj:`MCPConnectionError` Error in the transport layer. Raised when there are issues with the underlying transport mechanism (STDIO, HTTP, WebSocket, etc.). This includes process management failures, network issues, and transport-specific problems. .. rubric:: Examples Process died unexpectedly:: raise MCPTransportError( "Server process died", details={"pid": 12345, "exit_code": -9} ) Network error:: raise MCPTransportError( "HTTP connection failed", details={"url": "http://localhost:8080", "status": 500} )