Improve MCP Error Detection

[EmanueleDeRossi1]

Summary

Introduce structured MCP error handling across the SDK, Agent, and Backend to improve reliability and provide clearer, more consistent error messages to both developers and end users.

Problem / Opportunity

Error handling currently returns generic 500 or 422 responses whenever the agent output doesn’t match the expected schema, rather than providing meaningful errors. This results in unclear failures, poor debugging experience, and confusing messages shown to users.

Proposal

Add a small set of structured MCP exception classes in the SDK, update ToolExecutor and MCPAgent to raise them appropriately and provide simplified error responses to the frontend.

Example Internal Messages (developer-facing)

• Authentication failed: invalid API key
• Failed to parse agent output: expected JSON
• Connection error: timeout calling tool
• Resource not found: tool returned no results

Example Frontend Messages (user-facing)

• Authentication failed. Please check your credentials.
• No results found.
• The system couldn’t process the response.
• The service timed out. Please try again.

Non-Goals / Out of Scope

• No UI redesign or new error surfaces on the frontend.
• No changes to tool configuration or credential storage.

Acceptance Criteria

• SDK defines a small, consistent set of MCP exception classes.
• ToolExecutor raises typed errors only for API/tool-level issues.
• MCPAgent raises typed errors for semantic/formatting issues.
• Backend no longer uses keyword-based parsing.
• Router maps MCP exceptions to proper HTTP status codes.
• Frontend receives simplified, non-technical error messages.
• Empty-but-successful results still return 200 with [].