# How Claude Plugins Handle Rate Limiting with Third-Party Services

> Discover how Claude plugins manage rate limiting with third-party services using MCP error handling, exponential back-off, and default retries for seamless integration.

- Repository: [Anthropic/claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
- Tags: how-to-guide
- Published: 2026-03-13

---

**Claude plugins handle rate limiting with third-party services through a built-in MCP (Model-Context-Protocol) error-handling flow that detects HTTP 429 errors, applies configurable exponential back-off with up to 3 retry attempts by default, and returns user-friendly messages when quotas are exceeded.**

Claude plugins in the `anthropics/claude-plugins-official` repository interact with external APIs through MCP (Model-Context-Protocol) tools, which include robust mechanisms for handling rate limits imposed by third-party services. When a tool call encounters a rate limit, the plugin runtime follows a structured error-handling flow that automatically retries requests and manages user communication. Understanding this rate limiting architecture is essential for building reliable integrations that gracefully handle API quotas and throttling.

## The MCP Rate Limiting Architecture

Claude plugins manage rate limiting through a coordinated system of error detection, classification, and retry logic. According to the source code in [`plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md) (lines 200-205), the runtime implements a specific pattern for handling rate-limit errors when interacting with third-party services.

### Error Detection and Classification

When an MCP tool call encounters a rate limit, the system follows a precise detection flow:

- **HTTP Status Capture**: MCP servers surface HTTP status codes in the tool's error payload, including 429 (Too Many Requests) responses from external APIs
- **Error Type Classification**: The runtime inspects the error object for `error.type === "rate_limit"` or verifies the HTTP 429 status code
- **Structured Error Objects**: The tool call wrapper normalizes errors into a structured format containing `type`, `status`, and `message` properties for consistent handling

As documented in [`plugins/plugin-dev/skills/mcp-integration/references/server-types.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/server-types.md) (lines 286-294), SSE (Server-Sent Events) servers automatically forward HTTP status codes including 429, while stdio transports provide equivalent error surfacing, ensuring the runtime receives the necessary signals to trigger rate-limit handling.

### Retry Policy and Exponential Back-Off

Once classified as a rate-limit error, the runtime applies a configurable retry strategy:

1. **Default Configuration**: By default, the system performs a maximum of 3 retry attempts using exponential back-off
2. **Timing Calculation**: Wait intervals follow a `2 ** attempt` seconds formula (e.g., 2, 4, 8 seconds)
3. **Frontmatter Configuration**: Developers can override the default via the `retry_attempts` field in command frontmatter
4. **Progress Updates**: After each retry, the plugin emits progress messages to inform users of the current attempt count (e.g., "Retry 1 / 3 – still hitting rate limit")
5. **Final Fallback**: If the limit persists after all retries, the plugin returns a friendly error explaining the quota situation and suggesting remediation

## Implementing Rate Limiting in Plugin Commands

Plugin commands declare their retry behavior through YAML frontmatter and implement specific error-handling logic in their execution steps. The runtime reads these declarations to drive the retry loop.

The following example demonstrates a command configured to handle Jira API rate limits:

```markdown
---
description: Fetch a Jira ticket
allowed-tools: ["mcp__plugin_jira_jira__jira_get_issue"]
retry_attempts: 5        # increase from default 3

---

# Get issue

1. Call `mcp__plugin_jira_jira__jira_get_issue` with the issue key.
2. If the tool returns an error with `type: "rate_limit"`:
   - Wait `2 ** attempt` seconds (exponential back-off).
   - Retry up to `retry_attempts` times.
3. If still failing, reply:
   ❌ "The Jira API is rate-limited. Please try again in a few minutes or request a higher quota."

```

The `allowed-tools` field restricts which MCP tools the command can invoke, while `retry_attempts` drives the retry loop defined in the tool usage specifications. The `tool_error_handler` component processes these errors and manages the retry cycle.

## Automatic Rate Limit Handling for Agents

Claude agents inherit the same error-handling layer as plugin commands, ensuring consistent rate-limit behavior without additional configuration. Agents are allowed to call any MCP tool without pre-allowance, but they utilize the identical retry mechanisms when encountering HTTP 429 responses.

Agents follow this automatic flow:

```markdown
---
name: github-metrics
description: Summarize recent GitHub activity for a repo
model: inherit
---

## Steps

1. Call `mcp__plugin_github_github__github_list_commits` for the target repo.
2. If the call fails with a rate-limit error:
   - The agent’s internal `tool_error_handler` retries up to 3 times (default).
   - After each attempt it emits a progress message: “Retry 1 / 3 – waiting for GitHub rate limit…”.
3. Once data is retrieved, compute metrics and return the summary.

```

Unlike commands, agents do not require explicit `allowed-tools` declarations to access MCP tools, but they utilize identical structured error objects and retry logic when rate limiting occurs.

## Core Components and File Locations

The rate limiting implementation spans several key files in the `anthropics/claude-plugins-official` repository:

- **[`plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md)** (lines 200-205): Defines the generic error-handling pattern and specifies the "wait and retry (max 3 attempts)" step for rate-limit errors
- **[`plugins/plugin-dev/skills/mcp-integration/references/server-types.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/server-types.md)** (lines 286-294): Documents how SSE servers forward HTTP status codes and recommends implementing rate-limit handling for 429 responses
- **[`plugins/plugin-dev/skills/mcp-integration/SKILL.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/SKILL.md)** (lines 390-393): Lists "Check rate limiting and quotas" as a required step for robust MCP tool calls, directly referencing rate-limit checks in the skill implementation
- **[`plugins/feature-dev/README.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/feature-dev/README.md)**: Mentions rate limiting in the context of API endpoint development, indicating ecosystem-wide emphasis on quota management

## Summary

- Claude plugins use **MCP (Model-Context-Protocol)** tools to interact with third-party services and handle rate limits through structured error objects containing `type`, `status`, and `message` fields
- The runtime detects rate limits via **HTTP 429 status codes** or `error.type === "rate_limit"` classification
- A **default retry policy** applies exponential back-off with up to 3 attempts, configurable per command via `retry_attempts` frontmatter
- Both **plugin commands and agents** utilize the same `tool_error_handler` component for consistent rate-limit management
- Progress messages keep users informed during retry cycles, with friendly error messages provided upon final failure suggesting remediation steps

## Frequently Asked Questions

### What happens when a third-party API returns HTTP 429 to a Claude plugin?

When a third-party service returns HTTP 429 (Too Many Requests), the MCP server surfaces this status code through the transport layer (SSE or stdio). The Claude plugin runtime classifies this as a rate-limit error by checking for `error.type === "rate_limit"` or the 429 status, then automatically initiates the retry loop with exponential back-off (`2 ** attempt` seconds), attempting the request up to 3 times by default before returning a user-friendly error message explaining the quota situation.

### How do I configure custom retry behavior for a specific plugin command?

Add the `retry_attempts` field to the command's YAML frontmatter to override the default value of 3. For example, setting `retry_attempts: 5` allows the command to retry failed requests up to 5 times with increasing delays. This configuration is read by the runtime error dispatcher and applies to all rate-limit errors encountered during command execution, as documented in [`plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md).

### Do Claude agents handle rate limits differently than plugin commands?

No, Claude agents inherit the same error-handling logic as plugin commands. While agents do not require explicit `allowed-tools` declarations in their frontmatter, they utilize the identical `tool_error_handler` component to detect rate limits, apply exponential back-off retries, and emit progress messages. This ensures uniform rate-limit handling across both command-based and agent-based workflows in the Claude plugin system.

### Where is the rate limiting logic documented in the source code?

The primary documentation resides in [`plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/tool-usage.md) (lines 200-205), which defines the retry pattern for rate-limit errors. Additional context appears in [`plugins/plugin-dev/skills/mcp-integration/references/server-types.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/references/server-types.md) (lines 286-294) regarding HTTP status code propagation via SSE transports, and in [`plugins/plugin-dev/skills/mcp-integration/SKILL.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/mcp-integration/SKILL.md) (lines 390-393) as a required implementation checklist item for MCP integrations.