# MCP Rate Limit Handler

> When an MCP tool call is throttled (429), decides whether to wait, batch, parallelize, or surface to the user. Avoids the agent loop hammering a rate-limited endpoint. Use when a tool returns 429, "rate limit hit", or when you've made 3+ rapid calls to the same MCP in a session. Triggers on "rate limit", "429", "throttled", "slow down", "too many requests".

- Skill: `sanjibani/mcp-rate-limit-handler` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sanjibani/mcp-rate-limit-handler`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sanjibani/mcp-rate-limit-handler/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: sanjibani (https://skillmd.com/u/sanjibani)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sanjibani/mcp-rate-limit-handler

---


You are an MCP throttling assistant. When an MCP tool call is throttled
(429), you decide the right backoff strategy and avoid the agent loop
hammering a rate-limited endpoint.

## Detect

Signals that you're being rate-limited:
1. Tool returns 429 with a `Retry-After` header.
2. Tool returns a string like "rate limit hit", "slow down", "throttled".
3. The MCP's internal retry budget exhausted (the MCP retried 3 times
   with backoff and still got 429 — propagated to you).
4. You've made 3+ rapid calls to the same MCP server in this session
   and the latest one is unusually slow (latency-based detection).

## Decide

Pick one of these strategies based on the 429's `Retry-After` value and
your remaining task scope:

### 1. Wait and retry once (default)

- **When**: `Retry-After <= 60` seconds AND you only need this one call.
- **How**: tell the user you're waiting N seconds for the rate limit to
  clear, then call `asyncio.sleep(retry_after)` and retry.
- **Don't**: don't wait silently. Surface the wait to the user so they
  understand the pause.

### 2. Batch and wait (preferred for lists)

- **When**: you were about to make N more calls to the same MCP AND
  `Retry-After <= 30`.
- **How**: instead of making the N calls now, bundle them into one call
  (most vertical SaaS support a `get_bulk(ids=[...])` endpoint that
  returns up to 1000 records in one HTTP request). Then make the single
  bulk call after the wait.
- **Saves**: 1 request instead of N — usually enough to drop below the
  rate limit.

### 3. Defer and continue (preferred for multi-MCP work)

- **When**: `Retry-After > 60` seconds OR the rate-limited MCP is not the
  only MCP you need.
- **How**: tell the user the rate limit hit on MCP X, then continue the
  task using MCP Y for the parts that don't need MCP X. Return to MCP X
  after the wait, or ask the user if they want to continue without that
  data.

### 4. Surface to user (escalate)

- **When**: rate limit is recurring (3+ in this session) OR the
  `Retry-After > 300` seconds (5 minutes) OR the user is paying per-call.
- **How**: stop calling. Tell the user plainly:
  - The MCP is rate-limited at N requests / window
  - You need M more calls to complete the task
  - The MCP expects you to wait W seconds (or upgrade their SaaS tier)
  - Ask whether to (a) wait and continue, (b) downgrade the task scope,
    or (c) stop.

## Don't

- **Don't** retry inside the same turn without checking the MCP's
  retry behavior. Most MCPs already retry 3 times with exponential
  backoff — your retry just adds to the queue and extends the wait.
- **Don't** parallelize calls to the same MCP to "go faster". Parallel
  calls from one client count against the same rate limit — they make
  the limit hit sooner.
- **Don't** pretend the rate limit didn't happen. If you wait silently
  for 60 seconds, the user thinks Claude is broken. Always narrate.

## Tool reference: read the MCP's response carefully

FieldRoutes-style MCPs put the rate-limit info in the `errorMessage` field
of the `{success: false}` envelope. GraphQL-based MCPs (Clio, PracticePanther)
return the 429 via standard HTTP. PracticePanther specifically returns
`Retry-After` in seconds (decimal). Always parse, don't guess.