Repository navigation
MCP: Return useful errors when tool setup fails #2628
Description
A tool can fail while looking up a keyspace, building its request context, or setting up a provider. Those failures should return useful Data API errors through MCP instead of an unexplained framework failure. Authentication and protocol failures must keep their own HTTP and protocol responses.
This is an independent follow-up under #2408. Coordinate with #2629 because both touch the tool execution boundary. #2627 handles how completed results are displayed.
This ticket is done when focused tests cover setup failures and a valid call still succeeds after a denied or failed call. Errors must preserve actionable codes and messages without exposing protected data or credentials.
Status on October 23, 2026
PR #2653 fixes this. Request, schema and provider setup failures now go through one shared boundary. Known Data API errors keep their codes and messages, and unexpected failures return a generic error. It sits in the MCP stack above #2652, so it has no CI run yet. Authentication failures keep their existing handling and remain in #2642.
Implementation requirements and source references
Tracking issue: #2408.
Tracking correspondence: Related changelog IDs are listed below. This is an independent follow-up, outside the launch milestone unless promoted for a demonstrated release blocker. Shared requirement IDs remain stable across the delivery plan and #2408.
Why
A tool can fail before its command reaches normal Data API error handling. For example, resolving a keyspace or constructing a provider can fail while the tool is being set up. Some paths return a Data API error, while others can escape as a generic framework error that gives the caller little help.
This is an existing application-error handling issue, not a new requirement of Quarkiverse 2.0.3.
Work
- Bring request/context construction into the asynchronous execution path so its failures can be handled consistently.
- Use the existing Data API error mapping at a shared MCP boundary for database, keyspace, and collection/table tools.
- Keep malformed protocol messages and unknown RPC methods as protocol errors. Follow the tools contract for unknown tools and invalid tool arguments.
- Preserve the OAuth boundary: missing/invalid tokens remain HTTP 401 and insufficient scopes/permissions remain HTTP 403. Do not wrap resource-server authorization failures in a successful tool result or leak protected schema/data in setup errors.
Done when
Focused tests cover identifier, context, schema, authorization, and provider-setup failures. Application failures return actionable Data API codes and messages through MCP. HTTP behavior is unchanged.
Coordinate with #2629 because both touch the execution boundary. #2627 separately adds readable content to completed tool results. Reuse suitable work from #2503/#2591 and coordinate argument-error behavior with #2601.
Modern protocol and OAuth acceptance details
Use final reserved protocol errors where applicable and do not allocate Data API custom errors in -32020 through -32099. Exercise denied calls followed by valid calls to catch context leakage. Keep application error normalization separate from protocol parsing and OAuth resource-server decisions.
Changelog traceability
- m12 Use final protocol error codes, lines 61–67 — Required.
Normative detail: Streamable HTTP, authorization, caching.
Required base protocol/schema behavior remains owned by #2625 and verified by #2626. This follow-up owns only its stated enhancement or proven gap.
Activity
[-]Normalize MCP application failures outside command processing[/-][+]MCP: Normalize application failures outside command processing[/+][-]MCP: Normalize application failures outside command processing[/-][+]MCP: Return useful errors when tool setup fails[/+]