Proposal: standardize operator-friendly tool failure metadata for common MCP cases #2930

I like the direction of keeping this lightweight rather than introducing a new error framework

one thing I would suggest is separating machine-readable classification from the human-readable error message. For example, a tool could return a stable error code like:

• auth_required
• permission_denied
• retryable_transient_error
• capability_unsupported
• user_action_required

alongside a descriptive message and optional metadata (retry delay, required capability, login URL, etc.)

that would let clients implement consistent behavior (retry, prompt for authentication, disable UI actions, etc.) without relying on parsing free-form text while still giving operators useful debugging information.

I also think starting as a best-practice recommendation is the right approach. If multiple MCP servers converge on the same conventions it would provide real implementation experience before considering a formal SEP.

one additional category that may be worth considering is something like resource_not_found or invalid_input, since those are common tool failures but aren't necessarily permission or capability related.

overall having a small recommended set of standardized classifications seems like it would improve interoperability without adding much complexity

Agree on keeping this best-practice-first and separating machine classification from the human message. One thing I'd add: the codes in @Mohataseem89's list actually span three groups that call for different client behavior, and a single flat list hides that. It may help to carry a small class alongside the granular code:

• capability — can't succeed as-is without an out-of-band change (auth_required, permission_denied, capability_unsupported, user_action_required). The client should stop and surface the required action; retrying is pointless.
• reliability — transient, retry is defined (retryable_transient_error, rate limits, upstream timeouts). The client retries with backoff; an optional retry_after belongs here.
• governance — the request was well-formed and the tool could run it, but a policy layer refused (default-deny gate, allowlist, approval-required).

I'd argue governance is the one worth making explicit, because it's the current gap. It isn't the same as permission_denied (that's about the caller's identity/authz); it's the action being disallowed by policy, and the right client response is different again — log it for audit and/or raise a human-approval prompt, not retry and not re-auth. As gated/policy-enforcing MCP servers become more common, a client that can't tell "policy refused this action" from "transport failed" can't behave correctly.

Concretely: keep the granular code for operators, and add a small stable class (capability / reliability / governance) for clients to switch on. Clients get consistent behavior from a tiny enum; servers keep room to add codes without breaking client logic. +1 on shipping as a recommendation first and letting convergence happen before any SEP.

Ganerate Proposal based [2025 05 12 Green Paper on Establishing a Somaliland Bar Association Law.docx](https://github.com/user-attachments/files/29873698/2025.05.12. into: advocacy grants:
Partners must demonstrate that proposed activities respond to an urgent and/or escalating threat to
freedoms of assembly, association, or expression and that those involved in the project face a high level
of risk when exercising these rights.
Examples of activities include, but are not limited to, the following:
• Advocacy meetings and workshops to respond to restrictive laws governing FoAAE and
influencing policymakers and key actors to amend restrictions or repeal these laws such as:
o Convening of working groups of local, regional and international civil society to address the
crisis; and/or
o National workshops to discuss and plan advocacy strategies, such as repealing restrictive
legislation.
• Actions responding to unexpected opportunities to raise concerns over restrictions such as:
o Technical assistance for the analysis of pending or existing repressive legislation.
• Opportunities to expand civic space and enabling conditions for civil society, or for specific
groups within the sector such as:
o Networking regionally with other civil societies under siege to exchange best practices and
share legal expertise.
• Conducting counter-narrative campaigns to respond to smear campaigns against civil society.
• Harnessing opportunities in multilateral fora, like the United Nations or regional bodies, to put
pressure on governments to uphold FoAAE such as:
o Supporting civil society representatives from the ground in advocacy at international and
regional forums.
o Regional and international advocacy campaigns directed at regional and international
bodies.
o Submissions of reports to the human rights monitoring bodies of regional and international
institutions.

Ganerate proposal

On your question about existing implementations: yes. I've been building this as a transparent proxy called mcp-fuse, and the metadata it converged on overlaps heavily with this thread.

Agree with @Mohataseem89 on separating machine classification from the human message, and with @HarperZ9 that the codes imply different client behaviors. In my schema that ended up as three fields doing distinct jobs:

category: a small closed enum (transient, rate_limit, timeout, auth, permission, invalid_input, not_found, resource_exhausted, permanent, unknown). Roughly your list plus the retry-relevant cases.

retryable plus an optional retry directive (strategy, "not before" timing, max attempts). This is where this thread meets #3188, which is asking about the timing half of the same problem; the two probably belong together.

agentGuidance: one short imperative sentence intended for the model, capped in length, never a stack trace. Raw diagnostics go in a separate detail field that clients shouldn't forward to the model at all. In agent contexts this split matters as much as the codes, because the error text itself is what burns context.

One implementation lesson worth folding into the convention: whether a client may auto-retry has to depend on the tool's declared idempotency (readOnlyHint / idempotentHint), not only on the error class. An ambiguous failure on a tool with side effects should never be silently replayed. A nice side effect of making that normative is that servers finally get a real incentive to annotate their tools correctly.

Schema draft with JSON Schema and examples: https://github.com/YoadElkayam/mcp-fuse/tree/main/spec. It runs in the wild as a proxy, so there's measured data as well (benchmarks show it keeping roughly 96 to 98 percent of error payload tokens out of model context). Happy to reshape any of it toward whatever convention this group lands on. Starting as documentation guidance before an SEP sounds right to me.