Whatever message this page gives is out now! Go check it out!
Tool-level errors
Last update:
May 18, 2026
Tool-level errors occur after a successful JSON-RPC call when the MCP server invokes a tool, but the tool fails to complete its operation.
Overview
Once a JSON-RPC request such as
tools/call succeeds and the MCP server accepts the request, any failure that occurs within the tool implementation itself is considered a tool-level error. These errors indicate that the MCP server was reachable and the protocol exchange was valid, but the tool could not successfully complete its work.
Common causes
- Validation failures (missing required arguments or invalid value formats)
- Business logic errors (resource not found, unsupported operation, insufficient permissions)
- Backend dependency issues (downstream API failures or database errors)
- Unhandled internal exceptions thrown by the tool implementation
How tool-level errors surface
Tool-level errors are typically returned as part of the
tools/call result. - The response may contain
isError: trueand error content instead of normal output. - Some MCP servers return a standardized error structure, such as
error_code,error_message, orerror_category.
Recommended response
- Treat tool-level errors as normal and expected application conditions.
- Display clear, user-friendly error messages.
- Provide corrective guidance, such as fixing parameters, selecting another resource, or trying again later.
- Respect error categories provided by the MCP server when available:
client_erroror validation errors: Do not retry; correct the input.external_erroror backend failures: Retry may be appropriate with backoff.server_error: Log the issue, alert as needed, and consider a limited retry strategy.
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
