How to Rate-Limit an MCP Server (Per-User, Per-Tool, Per-Agent)
An agent loops. The loop calls your MCP tool 3,000 times in five minutes. Your database struggles, your LLM bill jumps, and someone gets paged at 2am. By the time you match up the logs, it is over.
“Add a rate limit” sounds like the fix. MCP makes the obvious version useless. Every call from ChatGPT, Claude Desktop or Cursor reaches your server with the same service API key. Your server can’t tell Alice’s 10 calls from Bob’s 2,990. A per-IP limit doesn’t help, because the LLM runtime is one IP. A per-key limit treats the whole runtime as one caller.
You need limits on three things: the user, the tool and the agent.
Why the default fails
Here is a typical MCP server:
from mcp.server import Server, stdio_server
from mcp.types import Tool, TextContent
server = Server("crm-mcp")
@server.list_tools()
async def list_tools() -> list[Tool]:
return [Tool(name="search_customers", inputSchema={...}, description="...")]
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "search_customers":
return [TextContent(type="text", text=crm.search(arguments["query"]))]
There is no limit. The runtime holds one credential, and your server handles whatever arrives. If a loop produces 1,000 calls, you run 1,000 calls.
A simple @rate_limit(per_minute=100) decorator fails four ways:
- It can’t see the user. If Alice makes 10 calls a minute and Bob makes 90, the decorator can’t tell them apart. When Bob hits the cap, Alice’s next call fails too.
- It can’t tell tools apart.
search_customersmight be cheap.generate_reportmight cost $5 and take 30 seconds. One limit per server treats them the same. - It doesn’t know the agent. A Claude Code Explore subagent scanning a codebase needs a very different limit from a person typing queries.
- It lives inside your server process. With three replicas, each keeps its own counter, so the real limit is three times what you set. Fixing that needs a shared store.
The three axes
User. “Alice can call search_customers 100 times an hour. Bob can call it 10.” This needs your server to know who the user is. MCP doesn’t carry that by default. You need something that verifies the user’s JWT, passed as an auth header, and attributes each call to that verified identity.
Tool. “generate_report is capped at 5 a minute across all users, because it hits an upstream API with a global quota.” This needs a counter per tool, not per server. Tools differ in cost and in damage, so limit them separately.
Agent. “A scheduled workflow gets a low hourly cap because nobody is watching it. A subagent sweeping a codebase gets more. A person typing queries gets the most headroom.” This needs each call to name the agent making it. A subagent sweeping ten files really does make more calls than a person chatting. You want different limits, not one shared number that either throttles real sweeps or misses runaways.
Option A: build it yourself
- Pull the user’s JWT from the MCP transport headers.
- Validate it: fetch the JWKS from your identity provider, verify the signature, and check audience, issuer and expiry.
- Take
subfor the user axis, the tool name from thetools/callrequest, and the agent from a header you define. - Keep counters in a shared store such as Redis so replicas agree.
- Return an MCP error when any limit is exceeded.
- Log which axis fired.
That is a few hundred lines plus a Redis dependency. You will revisit it every time you add a tool, an agent type or an identity provider.
Option B: let ACP do the counting
ACP checks coding-agent tool calls through hooks, and it also runs an MCP endpoint at https://api.agenticcontrolplane.com/mcp. Here is what it limits today, per call it governs. Only calls that reach ACP are counted. An MCP server that nothing routes through ACP is not limited by it.
- Per user, per session type, per minute. Each policy tier can carry a rate limit. The counter is per person, not per workspace, so one noisy user can’t use up the limit for everyone else. It is also per person rather than per API key, so minting child keys doesn’t reset it. A limit on a single tool can only tighten the tier’s cap, never raise it.
- Per agent type. You can set policy for one agent shape, such as all interactive Claude Code traffic or the Explore subagent. The key is
client::tier::name, for exampleClaude Code::subagent::Explore. Agent-type policy sits between role and user in the merge: workspace, then role, then agent type, then user. Only workspace owners and admins can write it. An agent’s own API key can’t. - A ceiling per agent run. This is the runaway brake. The default is 500 governed calls an hour as a base, and interactive and subagent sessions get four times that. Background and API sessions get the base. The count is per agent, so a parent session and its subagents don’t share one counter. From 80% of the ceiling, each allowed call carries a warning, so an agent can finish what it is writing before it hits the wall. The ceiling counts governed tool calls only, not model requests. Model spend is what budgets cover.
- A workspace rate limit on the Limits page. The default is 60 requests per 60-second window.
These limits are in-memory on each gateway instance. They are a runaway brake, not a billing meter.
What a denial looks like
When a limit fires, the call is denied with a plain reason. For the tier limit, it reads like this:
rate-limited: background (61/60 per minute)
The agent is told to wait and retry the same call. The log row starts with rate-limited, so you can filter on it. The ceiling’s denial states when the window clears.
The runaway loop, again
With limits set, here is the 3,000-call loop:
- Calls up to the limit succeed.
- The next call is denied and the agent is told to wait and retry.
- The agent either stops, passes the error up, or keeps hammering. Past the limit, your database sees none of it.
- Your log shows the user, the tool and the
rate-limitedreason.
You read it in the morning.
What this doesn’t cover
Rate limits handle too many calls too fast. They don’t handle:
- Cost. That is budgets, which are separate from the call ceiling.
- Wrong user, right tool. That is permission rules per user.
- Right user, wrong data. That is checking tool arguments and outputs for sensitive data.
Related
- How to add per-user authentication to a LangGraph agent: the identity side.
- Three-axis governance overview: the tool, agent and user model.
- MCP rate-limit blast radius: what happens in production without a limit.
- ACP Cloud: where the Limits page lives.
Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex