Rate-Limit MCP Tools

Tasks

Add call-rate limits to an Access Binding — "100 calls per hour per agent to merge_pull_request" — counted exactly across every AIControls replica. For where limits sit in the access model, see Team Access.

Add a rate limit

1. Go to Setup → Settings → Access Bindings and edit the binding whose tools you want to cap.

2. Under Rate limits, add a row:

   Field	Values	Meaning
   Calls	any positive number	Calls allowed per window
   Window	per minute, per hour, per day	Fixed windows — the count resets at each boundary
   For each	agent, user, team, label value, everyone combined	Who gets their own bucket. everyone combined is one shared bucket — a server-capacity cap
   On exceed	Deny, Warn, Require approval	Deny rejects the call; Warn lets it through and raises a notification; Require approval parks each over-limit call in the Approvals queue

3. Save. The limit applies to the calls the binding covers — its tool rows, or the whole bound server when the binding has none.

note

A limit only counts callers the binding's teams and subjects match — it is a cap on granted traffic, not a global throttle. For one shared cap across all callers, use everyone combined.

What happens on exceed

• Deny — the call is rejected with HTTP 429 and the limit's numbers in the message. Security Events records a denial with policy binding-rate-limit:<binding>, so limit trips are searchable like any other decision.
• Warn — the call proceeds; a rate_limit_exceeded notification is dispatched to your configured channels (Slack, Teams, email, in-app).
• Require approval ("approve to burst") — each over-limit call parks in the Approvals queue for up to two minutes by default. An approval releases that one call; on timeout the call is denied by default. Useful when the cap is a guardrail rather than a hard ceiling — a reviewer can wave through a legitimate burst without editing the binding. Both the wait time and the timeout outcome are configurable per rate limit — see below.

Either way the notification includes the agent, tool, and configured limit.

Configuring the "require approval" timeout

A require-approval limit accepts two optional overrides, set alongside the limit itself:

Field	Default	Meaning
Approval timeout (minutes)	2	How long an over-limit call waits in the Approvals queue before timing out
On timeout	Deny	What happens if nobody reviews it in time: Deny, Warn (let it through, notify), or Allow (let it through silently) — timeoutAction in the API, lowercase (deny/warn/allow)

Leave both blank to keep the defaults — a short interactive window with a deny fallback suits a developer waiting on their own call. Widen the timeout (or switch the timeout action to Warn/Allow) for limits an on-call approver reviews rather than the calling developer, where a two-minute window is unrealistic.

Verify

1. Set a deliberately small limit (e.g. 2 per minute per agent) on a test binding.
2. Call the covered tool three times as the same agent — the third call fails with HTTP 429.
3. Find the denial in Security Events by policy name binding-rate-limit:, then restore the real limit.

Notes on counting

• Counts are stored centrally, so limits hold exactly even with multiple AIControls replicas — two replicas cannot each allow the same "last" call.
• Windows are fixed, not sliding: a per hour limit resets on the hour boundary.
• If the counter store is briefly unreachable, calls are allowed rather than blocked (fail-open) and the condition is logged.

See also

• Control MCP tool access
• Team Access
• Set a Budget — token/cost budgets, the spend-side counterpart to call-rate limits