MCP Server Error Handling

A good server distinguishes expected business failures from unexpected protocol or internal failures.

Expected tool errors

Examples include “order not found,” “insufficient permission,” or “deployment already running.” Return concise, actionable information the model can reason about.

Unexpected exceptions

Log the detailed stack trace to your observability system, but return a sanitized error to the client. Do not expose database connection strings, raw tokens, filesystem paths, or internal tracebacks.

Low-level server behavior

The current Python SDK documents that exceptions in low-level handlers become protocol errors, while readable tool failures can be returned as tool results marked as errors. High-level SDK helpers handle much of this for you.

Retry classification

Mark transient failures differently from permanent validation errors in your application logic so the agent runtime can make sensible retry decisions.