Errors

Domain-specific error types raised by the server and components.

`arcade_mcp_server.exceptions`

Exception Hierarchy

Provides domain-specific exceptions for better error handling and debugging.

`MCPError`

Bases: Exception

Base error for all -related exceptions.

`MCPRuntimeError`

Bases: MCPError

Runtime error for all -related exceptions.

`MCPContextError`

Bases: MCPError

Error in management.

`ServerError`

Bases: MCPRuntimeError

Error in server operations.

`AuthorizationError`

Bases: MCPContextError

Authorization failure.

`LifespanError`

Bases: ServerError

Error in lifespan management.

`NotFoundError`

Bases: MCPContextError

Requested entity not found.

`PromptError`

Bases: MCPContextError

Error in prompt management.

`ProtocolError`

Bases: MCPRuntimeError

Error in protocol handling.

`RequestError`

Bases: ServerError

Error in request processing from client to server.

`ResourceError`

Bases: MCPContextError

Error in resource management.

`ResponseError`

Bases: ServerError

Error in request processing from server to client.

`ServerRequestError`

Bases: RequestError

Error in sending request from server to client initiated by the server.

`SessionError`

Bases: ServerError

Error in session management.

`TransportError`

Bases: MCPRuntimeError

Error in transport layer (stdio, HTTP, etc).

`arcade_core.errors`

errors with retry semantics. Re-exported via arcade_mcp_server.exceptions.

`RetryableToolError`

Bases: ToolExecutionError

The operation failed but can be retried.

Python


from arcade_mcp_server.exceptions import RetryableToolError
 
# Simple retry
raise RetryableToolError("Service temporarily unavailable")
 
# With retry delay
raise RetryableToolError(
    "Rate limited",
    retry_after_ms=5000
)
 
# With guidance for the AI
raise RetryableToolError(
    "Search returned no results",
    additional_prompt_content="Try broader search terms or check spelling."
)

`FatalToolError`

Bases: ToolExecutionError

Unrecoverable error — the AI should not retry.

Python


from arcade_mcp_server.exceptions import FatalToolError
 
raise FatalToolError("Account has been permanently deleted")
 
# With developer-only details
raise FatalToolError(
    "Configuration error",
    developer_message="Missing required API key in environment"
)

`ContextRequiredToolError`

Bases: ToolExecutionError

The operation needs additional from the before it can proceed.

Python


from arcade_mcp_server.exceptions import ContextRequiredToolError
 
raise ContextRequiredToolError(
    "Multiple users found matching 'John'",
    additional_prompt_content="Please specify: John Smith (john@work.com) or John Doe (john@home.com)"
)

`UpstreamError`

Bases: ToolExecutionError

Error from an external API or service.

Python


from arcade_mcp_server.exceptions import UpstreamError
 
raise UpstreamError(
    "Slack API error: channel_not_found",
    status_code=404
)

`UpstreamRateLimitError`

Bases: UpstreamError

Rate limit from an external API. Includes retry information.

Python


from arcade_mcp_server.exceptions import UpstreamRateLimitError
 
raise UpstreamRateLimitError(
    "Rate limited by Slack",
    retry_after_ms=60_000
)

You rarely throw UpstreamError manually. Use error adapters to automatically translate SDK errors.

Error Hierarchy

TEXT


MCPError (base)
├── MCPContextError (user/input caused the error)
│   ├── AuthorizationError
│   ├── NotFoundError
│   ├── PromptError
│   └── ResourceError
└── MCPRuntimeError (server/infrastructure caused the error)
    ├── ProtocolError
    ├── TransportError
    └── ServerError
        ├── RequestError
        │   └── ServerRequestError
        ├── ResponseError
        ├── SessionError
        └── LifespanError

ToolkitError (base for tool errors)
└── ToolError
    └── ToolRuntimeError
        └── ToolExecutionError
            ├── RetryableToolError (can retry)
            ├── FatalToolError (do not retry)
            ├── ContextRequiredToolError (needs user input)
            └── UpstreamError (external API failure)
                └── UpstreamRateLimitError

Examples

Raising exceptions for common error scenarios

Python


from arcade_mcp_server.exceptions import (
    NotFoundError,
    RetryableToolError,
    FatalToolError,
)
 
# Resource not found
async def read_resource_or_fail(uri: str) -> str:
    if not await exists(uri):
        raise NotFoundError(f"Resource not found: {uri}")
    return await read(uri)
 
# Retryable failure
async def fetch_data(url: str):
    try:
        return await http_client.get(url)
    except ConnectionError as e:
        raise RetryableToolError(
            "Failed to connect. Please try again.",
            developer_message=str(e)
        )
 
# Unrecoverable failure
def validate_config(config: dict):
    if "api_key" not in config:
        raise FatalToolError("Missing required configuration: api_key")