Handling MCP Rate Limits, 429 Errors, and Transport Timeouts

In autonomous agent workflows and multi-agent coordination, execution halts the moment an MCP client receives an unhandled 429 Too Many Requests error. According to Anthropic's file upload documentation, while Claude Projects accepts files up to 30MB each with unlimited total files, the total content must fit within Claude's context window. When multi-agent systems try to circumvent local context constraints by blasting dozens of concurrent tool calls across an external Model Context Protocol connection, throughput walls appear quickly.

An MCP rate limit is a throughput constraint enforced by an MCP client, host application, or remote MCP server that caps the number of JSON-RPC tool calls, resources, or prompts processed per second or per minute.

Debugging these bottlenecks requires isolating which layer generated the throttling signal. In production environments, an MCP interaction crosses three separate architectural layers, each with its own rate limiting mechanism:

1. The Host Application and Model Layer: The host orchestrator, such as Claude Desktop, Claude Code, Cursor, or an autonomous agent runtime, interfaces with underlying LLM inference endpoints. LLM providers enforce Tokens Per Minute (TPM) and Requests Per Minute (RPM) quotas. When an agent enters an iterative reasoning loop and issues ten to twenty tool calls in rapid succession, the accumulated prompt tokens and tool completion payloads quickly exhaust model provider quotas. Here, the 429 response originates from the LLM provider API rather than the MCP transport.

2. The Protocol Transport and Gateway Layer: Remote MCP servers run behind reverse proxies, API gateways, load balancers, and web application firewalls. These intermediaries enforce connection limits, request rate thresholds per IP address or session token, and payload size ceilings. If five concurrent agents initiate parallel JSON-RPC requests across a single gateway, the gateway may return an HTTP 429 status code or drop the TCP connection before the request reaches the MCP application logic.

3. The Downstream Tool and Upstream Service Layer: The MCP server acts as an interface adapter for underlying backend systems, including SaaS APIs, databases, and cloud storage providers. When an agent calls an MCP tool to query records or update files, the server executes corresponding operations against the backend service. If that external service enforces strict throttling, such as ten requests per second, the MCP server receives an upstream rate limit. The server then translates that backend rejection into an MCP error.

The following table compares how throttling manifests across these three layers:

Multi-agent deployments amplify rate limit problems because agent execution is inherently bursty. Rather than distributing requests evenly over time, autonomous teams experience idle periods during context evaluation followed by intense microbursts where multiple worker agents invoke tools simultaneously. A pipeline with five parallel agents analyzing repository components can trigger 50 tool invocations in under three seconds. Without coordination, these microbursts overwhelm unbuffered MCP endpoints.

• Best MCP Clients for 2026: Connect Your AI to Any ToolMCP clients are AI interfaces like Claude Desktop, Cursor, or specialized IDEs that implement the Model Context...
• Best MCP Tools for AI Agent Development in 2026MCP tools extend AI agent capabilities through the Model Context Protocol standard. This guide compares essential MCP...
• MCP Server Examples: Practical Implementations for AI AgentsThe Model Context Protocol ecosystem has grown past 1,000 public servers, but finding the right implementation for your...
• How to Connect AI Agents to Google Docs with MCPAn MCP server for Google Docs exposes document read, write, and search capabilities to AI agents through the Model...
• How to Use MCP for Agent WorkflowsMCP (Model Context Protocol) standardizes tool calls in multi-agent systems. This guide covers how to use MCP for agent...
• How to Connect AI Agents to Azure Blob Storage via MCPAn Azure Blob Storage MCP server exposes cloud containers and object storage to AI agents using standard Model Context...

More on this subject: MCP and Model Context Protocol (232 guides)

Transport stability determines whether an agent can complete multi-step tasks. In early MCP deployments, developers frequently encounter dropped streams and timeout errors when running agents over Server-Sent Events (SSE).

The original Model Context Protocol specification implemented a dual-endpoint HTTP+SSE transport. Under this architecture, the client establishes a long-lived HTTP GET connection to an events endpoint to receive server-sent events, while transmitting JSON-RPC client messages via HTTP POST requests to a separate messages endpoint.

Under production loads and multi-agent concurrency, this dual-endpoint model introduces three severe failure modes:

1. Middlebox and Proxy Timeouts: Cloud infrastructure relies on reverse proxies, load balancers, and CDN edges. By default, proxies such as AWS Application Load Balancers, Cloudflare, and Nginx maintain aggressive idle connection timeouts, typically ranging from 30 to 120 seconds. If an agent pauses to perform local inference or multi-step reasoning, no packets travel across the SSE stream. The intermediary proxy assumes the TCP connection has hung and silently terminates the socket. When the client subsequently attempts to post a message, the server rejects the request because the corresponding SSE stream is dead.

2. File Descriptor and Socket Exhaustion: Server-Sent Events require a persistent, dedicated TCP connection for every active client. In high-concurrency environments where dozens of autonomous agents or subagent threads connect simultaneously, the server must keep all sockets open concurrently. Standard Linux environments enforce a default limit of 1024 open file descriptors per process. When connection counts approach this ceiling, the operating system drops incoming connections, producing transport-level connection refused errors or connection resets.

3. Session State and Load Balancer Routing Conflicts: Horizontal scaling requires distributing traffic across multiple container instances or server replicas. Because legacy SSE ties the event stream on the GET endpoint to subsequent POST requests on the messages endpoint, the load balancer must enforce sticky sessions. If a proxy routes a POST request to an instance other than the one holding the client's open SSE stream, the target instance returns an HTTP 404 or invalid session error. Maintaining sticky sessions complicates autoscaling and introduces single points of failure.

The updated MCP specification establishes Streamable HTTP as the standard transport. In Streamable HTTP:

• The dual-endpoint model is replaced with a single endpoint.
• Every interaction begins as a standard HTTP POST request directed to the server URL.
• The client sends an Accept header requesting both application/json and text/event-stream.
• If the tool execution completes quickly, the server returns a standard application/json payload. If the operation involves progress tracking or continuous output, the server returns a chunked event stream over that specific HTTP response and closes it when the tool finishes.
• Session continuity is decoupled from persistent TCP sockets through the Mcp-Session-Id header, allowing any server replica behind a round-robin load balancer to handle incoming requests.

Client-side resilience prevents transient 429 errors from terminating agent executions. When an MCP server or gateway enforces throughput limits, the client must detect the condition, respect server backoff signals, and smooth out request spikes.

MCP clients must parse three distinct error formats:

1. Transport-Level HTTP 429 Status Codes: When an HTTP proxy or gateway throttles a request, it returns an HTTP 429 status code. The response often includes a Retry-After header indicating the required wait duration in seconds or an HTTP-date timestamp.

2. JSON-RPC Protocol Errors: When the MCP server processes the request but rejects it due to protocol-level rate limits, it returns an HTTP 200 status code containing a JSON-RPC error object. The JSON-RPC error code typically falls in the implementation-defined server error range (-32000 to -32099), with an error message detailing the throughput violation.

3. Tool Execution Result Errors: When an underlying backend service fails due to rate limits, the MCP server may return a valid JSON-RPC result where the tool response object has isError set to true and the text content describes the upstream throttling.

A common error in agent development is implementing plain exponential backoff without randomness. When multiple agents in a swarm receive a 429 error at timestamp T, a deterministic backoff formula causes all agents to retry simultaneously at T + 2s, T + 4s, and T + 8s. This creates a thundering herd that re-saturates the MCP server at each step.

The solution is Full Jitter backoff. The client calculates the exponential ceiling based on the attempt count, then chooses a uniform random duration between zero and that ceiling:

interface McpRequestOptions {
  maxRetries?: number;
  baseDelayMs?: number;
  maxDelayMs?: number;
}

async function callMcpToolWithRetry(
  serverUrl: string,
  toolName: string,
  args: Record<string, unknown>,
  options: McpRequestOptions = {}
): Promise<unknown> {
  const maxRetries = options.maxRetries ?? 5;
  const baseDelayMs = options.baseDelayMs ?? 500;
  const maxDelayMs = options.maxDelayMs ?? 10000;
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(serverUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream'
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: Date.now(),
        method: 'tools/call',
        params: { name: toolName, arguments: args }
      })
    });
    if (response.status === 429) {
      if (attempt === maxRetries) {
        throw new Error(`MCP rate limit exceeded after ${maxRetries} retries`);
      }
      const retryAfterHeader = response.headers.get('Retry-After');
      let waitMs = 0;
      if (retryAfterHeader) {
        const seconds = Number.parseInt(retryAfterHeader, 10);
        waitMs = Number.isNaN(seconds) ? baseDelayMs : seconds * 1000;
      } else {
        const calculatedCeiling = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attempt));
        waitMs = Math.floor(Math.random() * calculatedCeiling);
      }
      await new Promise((resolve) => setTimeout(resolve, waitMs));
      continue;
    }
    const data = await response.json() as {
      error?: { code: number; message: string };
      result?: { isError?: boolean; content?: Array<{ text: string }> };
    };
    if (data.error && data.error.code === -32000 && data.error.message.includes('rate limit')) {
      if (attempt === maxRetries) {
        throw new Error(`MCP server rate limit: ${data.error.message}`);
      }
      const calculatedCeiling = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attempt));
      const waitMs = Math.floor(Math.random() * calculatedCeiling);
      await new Promise((resolve) => setTimeout(resolve, waitMs));
      continue;
    }
    return data.result;
  }
}

In addition to backoff, production agent frameworks should incorporate a client-side concurrency limiter. A semaphore pattern bounds the number of simultaneous active requests dispatched to any single MCP server. For example, capping concurrent requests at four prevents a parallel swarm of agents from triggering server-side gateway tripwires.

For critical integrations, teams wrap tool dispatches in a circuit breaker. When the failure rate exceeds a configured threshold across a short moving window, the circuit breaker opens, failing fast locally for a cooldown period before transitioning to half-open state to probe server availability.

Scale Agent Workspaces Without Hitting Transport Limits

Connect your agents to persistent workspaces over Streamable HTTP. Store, index, and query large document collections through a consolidated MCP toolset with full version history. Monthly plans start with a 14-day free trial.

Start 14-Day Trial

Developers building and hosting remote MCP servers must protect their infrastructure against unbounded tool consumption. Without server-side controls, a single misconfigured agent in an infinite reasoning loop can exhaust server memory, deplete backend API allowances, and degrade service for all connected clients. Developers can inspect tool schemas and documentation at the Fast.io MCP setup guide and the Fast.io MCP developer documentation.

Implementing fair, resilient server-side rate limits involves four core practices:

1. Caller Identification Beyond IP Addresses: Traditional web services rate limit by client IP address. For MCP servers, IP tracking fails because multiple agent runtimes frequently execute from shared IP pools, such as cloud execution sandboxes, container clusters, or corporate outbound gateways. Remote MCP servers must identify callers using authenticated credentials:

   • Scoped API Bearer tokens passed via the Authorization header.
   • OAuth 2.0 client identifiers and access tokens.
   • The Mcp-Session-Id header established during client initialization.

2. Cost-Weighted Method Accounting: Different MCP methods impose vastly different computational and financial costs. A flat request-per-minute limit allows agents to spam expensive tools while starving lightweight discovery. Server architectures implement differential cost accounting:

   • Metadata inspection (tools/list, prompts/list, resources/list): Low cost, rated at 1 request unit.
   • Lightweight read operations: Moderate cost, rated at 5 request units.
   • Heavy operational tools (full-text search, code execution, database writes): High cost, rated at 20 request units.

3. Sliding Window Counter Algorithms: Fixed-window algorithms reset counters at the top of the minute, allowing a client to send its entire quota in the final second of minute one and another full quota in the first second of minute two. This boundary burst doubles permissible throughput and strains backend services. A sliding window counter smooths traffic by calculating request density across rolling intervals.

4. Emitting Standardized Telemetry Headers: When rejecting requests, servers should provide complete rate limit metadata so compliant clients can adjust their pacing. Remote MCP servers running over Streamable HTTP should return an HTTP 429 status code accompanied by standard rate limiting headers:

   • Retry-After: Number of seconds to wait before retrying.
   • RateLimit-Limit: Total request quota allocated within the current window.
   • RateLimit-Remaining: Number of requests remaining in the current window.
   • RateLimit-Reset: Seconds remaining until the quota resets.

The server should accompany the 429 status code with a JSON-RPC error payload containing a structured error code. This provides clarity to both transport-level HTTP clients and JSON-RPC protocol decoders.

Many MCP rate limits and connection timeouts are not caused by request frequency, but by payload inflation. When developers connect agents to file systems or knowledge repositories, naive tool implementations frequently read entire document files and dump their complete contents into JSON-RPC response payloads.

This practice creates two immediate bottlenecks:

First, transmitting multi-megabyte payloads across HTTP connections causes serialization delays, buffer overruns, and socket timeouts. Second, ingesting massive raw file dumps consumes tens of thousands of prompt tokens in a single turn. This rapidly depletes the LLM provider's Tokens Per Minute (TPM) quota, triggering 429 errors at the model layer.

Engineering teams evaluating persistence layers face distinct tradeoffs:

• Local Filesystem Storage: Writing files to local disk works for single-developer prototypes on desktop machines. It breaks down in distributed multi-agent clusters, cloud execution sandboxes, and collaborative team environments where agents run on ephemeral containers without shared disk access.

• Raw Object Storage (such as Amazon S3): Cloud object storage provides durable binary storage, but it lacks native document indexing, requires engineering custom retrieval pipelines, and provides no built-in version auditing for concurrent agent writes.

Fast.io persistent workspaces provide an intelligent workspace architecture that eliminates payload bloat at the root:

Instead of attaching large documents directly to chat contexts or shoving entire files through MCP tool calls, teams place their corpus in shared, org-owned Fast.io workspaces. Files can be uploaded directly or synchronized from Google Drive, Dropbox, Box, or OneDrive.

When Intelligence Mode is enabled on a workspace, files are indexed automatically for hybrid search across full-text, semantic meaning, and metadata values. Teams that need structured document extraction can use Metadata Views to convert unstructured files into queryable spreadsheets. AI assistants and autonomous agents connect through the remote MCP server at https://mcp.fast.io/mcp/tools (or https://mcp.fast.io/mcp/code for coding agents) using Streamable HTTP. Learn more about Fast.io storage for agents and Fast.io AI features.

Instead of pulling an entire multi-page document across an MCP tool call and blasting the LLM context window, the agent invokes targeted search tools. The MCP server returns only the relevant excerpts, key paragraphs, and source citations. This keeps JSON-RPC messages lightweight, eliminates transport timeouts, and prevents model rate limit exhaustion.

For concurrent agent operations, Fast.io provides advisory file locks through MCP actions: lock-acquire and lock-release on the storage_manage tool, and lock-status on the storage tool. A lock signals active edits to other agents without blocking concurrent writes. Because concurrent writes both land safely, per-file version history preserves every revision, allowing teams to inspect changes through the detailed activity log.

Teams and agents keep shared notes inside a workspace, while the events feed provides WebSocket and long-poll subscriptions to workspace activity.

Monthly plans start with a 14-day free trial that requires a credit card. Check the Fast.io pricing plans for complete details:

Credits meter AI work. Seats and storage come with the plan. Additional storage beyond the plan allowance is billed in cents per gigabyte monthly rather than in credits.