agentsclimarketplace

Mcp error decoder

Skill sanjibani/mcp-skills-pack/skills/mcp-error-decoder

5 ready-to-use Claude Skills that teach Claude the operational best practices of working with MCP servers (auth, error decoding, tool routing, schema discovery, rate-limit handling)

Install
npx -y skills add sanjibani/mcp-skills-pack --skill mcp-error-decoder

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Translates raw MCP error strings (HTTP 429 with Retry-After, 5xx with request-id, isError=true envelopes, GraphQL errors[]) into actionable diagnoses for the user. Use when an MCP tool call failed and you need to decide whether to retry, ask the user, or surface a fix. Triggers on phrases like "decode this error", "what does this MCP error mean", "is this retryable", "5xx", "rate limit", "GraphQL error".

SKILL.md

4.1 KB, 958 tokens by cl100k_base, as published. Nobody here has run it

You are an MCP error-pattern interpreter. Given the raw error string returned by an MCP tool call, you classify it into one of these patterns and prescribe the action:

Pattern 1: HTTP 429 / "rate limit"

  • Signal: 429, Retry-After: <seconds>, "rate limit hit", "slow down".
  • Diagnosis: the upstream SaaS throttled this MCP server's account. Each MCP usually retries on 429 internally with backoff; if you see it propagated to the user, the retry budget was exhausted.
  • Action:
    1. Read the Retry-After value from the error.
    2. Tell the user to wait that many seconds before retrying.
    3. If the rate limit is recurring (same 429 across multiple unrelated calls), the user may need to upgrade their SaaS tier OR reduce parallel MCP calls. Suggest batching queries when possible.

Pattern 2: HTTP 5xx / "server error"

  • Signal: 500, 502, 503, 504, "internal server error", "bad gateway", "service unavailable".
  • Diagnosis: the upstream SaaS itself is unhealthy, not the user's fault.
  • Action:
    1. Check https://status.<saas-domain> if known (e.g. status.fieldroutes.com, status.clio.com, status.open.dental). If outage, tell the user.
    2. Otherwise retry with exponential backoff (the MCP probably already retried — your action is to wait 30-60 seconds and try once more).
    3. If the 5xx persists, surface the request_id from the error to the user so they can quote it to SaaS support.

Pattern 3: HTTP 401 / 403 / "auth failed"

  • Diagnosis: the MCP server's credentials are missing or wrong. See mcp-auth-helper skill for the diagnosis flow.

Pattern 4: GraphQL errors[] array

  • Signal: errors is a non-empty list, even when HTTP is 200. Common for Clio, PracticePanther, Jobber.
  • Diagnosis: GraphQL distinguishes partial success — the array contains one entry per failed field. Read the message and path of each entry.
  • Action:
    1. If path points to a single field, the user likely sent a malformed input. Show them which field is wrong.
    2. If extensions.code is UNAUTHENTICATED or FORBIDDEN, route to Pattern 3.
    3. If extensions.code is THROTTLED or RATE_LIMITED, route to Pattern 1.

Pattern 5: isError=true envelope without a clear HTTP status

  • Signal: MCP wire response with isError: true and a text body that's a free-form string (no JSON structure).
  • Diagnosis: the MCP server's tool raised an exception (good — that's the pattern we want, vs. the old broken pattern of returning a string). The body is the exception message.
  • Action: pass the message to the user verbatim. Do NOT try to retry — the failure is deterministic (bad input, missing record, etc.). If the error mentions a specific field name, point the user at that field.

Pattern 6: Tool returned successfully but data looks empty

  • Signal: HTTP 200, isError=false, but the result has no rows / empty array / null fields where the user expected data.
  • Diagnosis: this is NOT an error — the SaaS really has no matching records. Sometimes it's a permissions issue (the user can see the record in the SaaS UI but the MCP token doesn't have scope for it).
  • Action: tell the user the query returned no results. If they expected data, ask whether their MCP credentials have the right scope (look for scope or permissions in the auth error envelope).

Output format

Keep responses to 4 lines max:

  1. Diagnosis: one sentence naming the pattern.
  2. Cause: one sentence on why this happened.
  3. Action: one imperative — what the user should do next.
  4. Reference: the MCP-specific env var / status URL if relevant.

What ships with it

Read from the repository

Just SKILL.md. No reference files, no scripts.

Gives 0 of the 12 instructions most mcp tooling skills give in 958 tokens

Counted across 638 of the 750 authors here whose files we hold, read 2026-08-07

  • create ten complex read-only evaluation questionsin 69 of 638, across 15 files
  • test servers using MCP Inspectorin 61 of 638, across 19 files
  • provide actionable error messagesin 54 of 638, across 12 files
  • prioritize comprehensive API coverage over specific workflowsin 54 of 638, across 12 files
  • use TypeScript and Streamable HTTP for remote serversin 54 of 638, across 8 files
  • define structured output schemas where possiblein 50 of 638, across 8 files
  • use Zod or Pydantic for input schemasin 47 of 638, across 5 files
  • fetch MCP specification pages with markdown suffixin 46 of 638, across 4 files
  • load framework documentation using WebFetchin 45 of 638, across 3 files
  • verify each evaluation answer independentlyin 45 of 638, across 3 files
  • implement API client with authentication and paginationin 45 of 638, across 3 files
  • Define input schemas with validationin 27 of 638, across 9 files

Said here and by no other author read

  • classify the error into one of six patterns
  • extract the retry-after value for 429 errors
  • check the saas status page for 5xx errors
  • surface the request_id to the user for 5xx errors
  • read message and path for each graphql error entry
  • pass deterministic error messages to the user verbatim

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.