Error Hierarchy
All MCP errors inherit fromMCPError:
Handling Connection Errors
Handling Tool Errors
Handling Server Not Found
Automatic Reconnection
By default, MCP connections automatically reconnect on failure:MCPConnectionError is raised.
Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Handle connection failures, timeouts, and protocol errors.
MCPError:
| Exception | Reason |
|---|---|
MCPConnectionError | Failed to connect to server |
MCPTimeoutError | Request or connection timed out |
MCPProtocolError | Invalid JSON-RPC or protocol violation |
MCPToolNotFoundError | Requested tool does not exist |
MCPServerNotFoundError | Server name not in configuration |
MCPResourceNotFoundError | Resource URI not found |
MCPPromptNotFoundError | Prompt name not found |
from definable.mcp import MCPToolkit, MCPConfig, MCPServerConfig
from definable.mcp.errors import MCPConnectionError, MCPTimeoutError
config = MCPConfig(servers=[
MCPServerConfig(name="my-server", transport="stdio", command="my-mcp-server"),
])
try:
async with MCPToolkit(config=config) as toolkit:
agent = Agent(model=model, toolkits=[toolkit])
output = await agent.arun("Do something")
except MCPConnectionError as e:
print(f"Could not connect to MCP server: {e}")
except MCPTimeoutError as e:
print(f"Connection timed out: {e}")
from definable.mcp.errors import MCPToolNotFoundError
try:
result = await client.call_tool("my-server", "nonexistent_tool", {})
except MCPToolNotFoundError as e:
print(f"Tool not found: {e}")
from definable.mcp.errors import MCPServerNotFoundError
try:
tools = await client.list_tools("unknown-server")
except MCPServerNotFoundError as e:
print(f"Server not configured: {e}")
MCPServerConfig(
name="my-server",
transport="stdio",
command="my-mcp-server",
reconnect_on_failure=True, # Default
max_reconnect_attempts=3, # Default
)
MCPConnectionError is raised.
MCPServerConfig(
name="slow-server",
transport="http",
url="https://mcp.example.com/mcp",
connect_timeout=60.0, # Time to establish connection
request_timeout=120.0, # Time for each request
)
config = MCPConfig(servers=[
MCPServerConfig(name="primary", transport="stdio", command="server-a"),
MCPServerConfig(name="fallback", transport="stdio", command="server-b"),
])
client = MCPClient(config)
await client.connect()
# Connect to servers individually for resilience
for server_name in ["primary", "fallback"]:
try:
await client.connect_server(server_name)
print(f"Connected to {server_name}")
except MCPConnectionError:
print(f"Failed to connect to {server_name}, skipping")
from definable.mcp.errors import MCPProtocolError
try:
result = await client.call_tool("server", "tool", {"arg": "value"})
except MCPProtocolError as e:
print(f"Protocol error: {e}")
# This usually means the server returned an invalid JSON-RPC response
MCPProtocolError consistently, check that the MCP server is using a compatible version of the protocol and that the transport type matches the server’s expectations.