Better MCP tools/call Error Responses: Help Your AI Recover Gracefully

Building MCP servers requires focusing on more than just successful tool executions; error handling is critical for AI recovery. There are two main error types in MCP: protocol-level errors and tool/call errors. Protocol-level errors, like timeouts or malformed requests, trigger standard JSON-RPC error responses. Tool/call errors, however, occur during tool execution and should be returned as successful MCP responses with an "isError: true" flag in the result payload. Unlike protocol errors that are often discarded by the client, tool/call errors are fed back into the AI's context window. This allows the AI to learn from and potentially recover from these errors without human intervention. Generic tool error messages hinder AI capabilities; instead, providing detailed, contextual error responses is crucial for improving model task completion rates. Effective error messages can offer tool ordering guidance, helping the AI understand necessary state changes before using a tool. Refined validation messages provide specific feedback when JSON schema is insufficient, correcting user input for tools. Smart unknown error handling offers retry strategies and fallback instructions, guiding the AI on how to proceed when specific causes are unclear. By treating error responses as contextual guidance, MCP servers can facilitate AI self-correction and enhance user experience.