Errors

Domain-specific exception types for the MCP server. All exceptions are defined in arcade_mcp_server.exceptions.

MCP exception hierarchy

MCPError (base)
├── MCPRuntimeError
│   ├── ServerError
│   │   ├── SessionError
│   │   ├── RequestError
│   │   │   └── ServerRequestError
│   │   ├── ResponseError
│   │   └── LifespanError
│   ├── TransportError
│   └── ProtocolError
└── MCPContextError
    ├── NotFoundError
    ├── AuthorizationError
    ├── PromptError
    └── ResourceError

MCPError

Bases: Exception

Base error for all MCP-related exceptions.

MCPRuntimeError

Bases: MCPError

Runtime error for MCP operations.

MCPContextError

Bases: MCPError

Error in context management.

ServerError

Bases: MCPRuntimeError

Error in server operations.

SessionError

Bases: ServerError

Error in session management.

RequestError

Bases: ServerError

Error in request processing from client to server.

ResponseError

Bases: ServerError

Error in response processing from server to client.

ServerRequestError

Bases: RequestError

Error in sending a request from the server to the client (server-initiated).

LifespanError

Bases: ServerError

Error in lifespan management (startup/shutdown hooks).

NotFoundError

Bases: MCPContextError

Requested entity (tool, resource, prompt) not found.

AuthorizationError

Bases: MCPContextError

Authorization failure.

PromptError

Bases: MCPContextError

Error in prompt management.

ResourceError

Bases: MCPContextError

Error in resource management.

TransportError

Bases: MCPRuntimeError

Error in the transport layer (stdio, HTTP).

ProtocolError

Bases: MCPRuntimeError

Error in MCP protocol handling.

Re-exported from arcade-core

The following exceptions are re-exported from arcade_core.errors for convenience. Import them from arcade_mcp_server.exceptions.

ToolRuntimeError

General runtime error during tool execution.

ToolExecutionError

Error during tool execution (wraps the underlying exception).

FatalToolError

A fatal error that should not be retried.

RetryableToolError

An error that the caller may retry.

UpstreamError

Error from an upstream service the tool depends on.

UpstreamRateLimitError

Rate limit error from an upstream service.

ContextRequiredToolError

Error raised when a tool requires a context that was not provided.

ErrorKind

An enum classifying error types (for example, ErrorKind.FATAL, ErrorKind.RETRYABLE).

Examples

Handling errors in tool code

from arcade_mcp_server.exceptions import (
    NotFoundError,
    ToolRuntimeError,
)
 
 
async def read_resource_or_fail(uri: str) -> str:
    resource = await lookup(uri)
    if resource is None:
        raise NotFoundError(f"Resource not found: {uri}")
    return resource
 
 
async def call_external_api() -> dict:
    try:
        return await fetch_data()
    except Exception as e:
        raise ToolRuntimeError(f"External API call failed: {e}") from e

Catching specific error types

from arcade_mcp_server.exceptions import (
    MCPError,
    NotFoundError,
    TransportError,
)
 
try:
    result = await server.handle_message(message, session=session)
except NotFoundError:
    print("Entity not found")
except TransportError:
    print("Transport layer error")
except MCPError:
    print("General MCP error")