How Claude Plugins Handle Rate Limiting with Third-Party Services

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 (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 (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:

---
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:

---
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 (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 (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 (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: 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.

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 (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 (lines 286-294) regarding HTTP status code propagation via SSE transports, and in plugins/plugin-dev/skills/mcp-integration/SKILL.md (lines 390-393) as a required implementation checklist item for MCP integrations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}