How to Rate-Limit MCP Tool Calls (Stop Runaway Agent Loops)
Agents fail in loops. A tool errors, the model retries; the retry errors, it retries harder; and by morning one confused session has made forty thousand tool calls — burning upstream API quota, your usage bill, and possibly your upstream account’s standing. Unlike human users, an agent never gets bored, never sleeps, and never notices it’s been doing the same thing for six hours.
MCP servers ship with no throttle of their own. On MCP Trail, every server gets a token-bucket rate limit on tools/call — a sustained rate plus a burst allowance — enforced at the gateway, configured per server, separate from your credit budget.
How the token bucket works
Two numbers define it:
- RPM (sustained rate) — how many
tools/callrequests per minute the bucket refills; the long-run ceiling - Burst — how many calls can happen back-to-back before throttling kicks in
Defaults apply out of the box (120 RPM, burst 60) so even an untouched server can’t be flooded. Bursty-but-legitimate agent behavior — a quick flurry of reads — passes; a sustained hammer does not.
Step 1: Create your free MCP Trail account and add a server
Sign up at app.mcptrail.com and route a server through the gateway (marketplace or existing URL). Rate limiting is already active with defaults the moment traffic flows.
Step 2: Tune the limits for this server
Open the server under Guardian servers → Security tab → Request limits. The rate-limit card takes your RPM and burst; leave fields empty to keep the defaults. Size it to the workload: an interactive coding assistant might peak at a few calls per second for a moment (burst) but average far less (RPM).
Step 3: Trip it on purpose
From the playground or a client, fire calls faster than your configured burst. The gateway starts rejecting with an explicit rate-limit error — which well-behaved clients back off from, and which turns a runaway loop from an unbounded incident into a bounded one.
Step 4: Watch for throttling in the wild
Rate-limit hits appear in the Audit log, and the Monitoring view’s request-volume chart makes loop patterns obvious — a flat line that suddenly goes vertical at 2am is your retry loop, caught. If you see legitimate traffic throttled, raise the burst first, then the RPM.
Rate limits vs. everything else
Each control catches what the others miss:
- Rate limit — caps how fast calls happen, regardless of what they are
- Credit budgets — cap how much total usage a server can consume
- Session risk scoring — weighs what kind of calls a session makes
- Request size limits — cap how big each call can be
A runaway loop of cheap reads trips the rate limit; six slow destructive calls trip risk scoring. You want both.
FAQ
Is the rate limit per server or per user?
Per server at the gateway (with optional per-client-IP treatment when forwarded-IP trust is explicitly enabled). Each server has its own bucket, so a noisy integration can’t starve a quiet one.
What error does a throttled client get?
An explicit rate-limit rejection, not a timeout — clients and agents can distinguish “slow down” from “broken” and back off accordingly.
Does the rate limit consume credits?
No — rejected calls are stopped before the expensive work. The limit exists precisely to protect your quota and budget.
What are sensible starting values?
The defaults (120 RPM, burst 60) suit most interactive use. Tighten for servers with expensive or dangerous tools; loosen for high-volume pipelines you trust.
Related Articles
- How to Set Request & Response Size Limits for MCP Servers
- MCP Session Risk Scoring
- MCP Cost Management
- How to Check and Monitor MCP Server Logs
Your next retry loop is a question of when, not if. Create your free MCP Trail account and put a ceiling on it now.