Skip to Content

Usage limits

Cap MCP tool calls so no one agent or user uses up a shared quota, with a budget per org, user, server, or tool

An agent stuck in a loop can keep making tool calls to an MCP server until the server's quota runs out for everyone. Usage limits cap how many tool calls go through per second, minute, or hour, so one agent or user can't take the capacity everyone else needs.

Usage Limits page listing configured rules with their scope, budget, and action
The Usage Limits page lists every rule alongside its scope, budget, and action

What a usage limit covers

Usage limits count MCP tool calls, not model calls. They never limit listing tools or connecting.

MCP tool calls and model calls

  • MCP tool call (MCP Gateway) – the agent acts in an app, such as searching Jira or posting in Slack.
  • Model call (AI Gateway) – the agent asks a model, such as Claude, to write a reply.

Common setups

  • Give everyone a fair share – set Counted per to user, for example 50 calls a minute. One person's looping agent can't use up everyone else's budget.
  • Stay under one MCP server's quota – scope the rule to that MCP server, such as Jira, and set the budget below the number of calls Jira allows.
  • Add a ceiling for the whole organization – add a rule with Counted per set to organization only, such as 1000 calls a minute, next to the per-user one. Both apply to every call, as Every matching rule applies explains.

What a rule says

A rule sets which calls it covers, how many calls they get, and who shares that budget. It can also carry a condition that limits only some of those calls.

Which calls it covers

Choose them in the scope, the same selector Access Policies and Data Protection use. You can name:

  • Resources, agents, or agent instances
  • Users or groups
  • Tags or tool patterns

Leave a field empty to match anything. An empty scope covers every tool call.

How many calls

  • Calls and Window set the budget, such as 60 calls an hour. The window can be up to an hour.
  • The gateway spaces calls evenly across the window. A rule of 60 calls an hour lets about one call through each minute.
  • Burst lets several calls through together. Leave it at 0 to release one call at a time. Set it to 10 on the same rule and ten calls go through every ten minutes. Burst can be at most Calls.

In the API, these are limit, window_seconds, and burst.

Who shares the budget

Counted per decides whether everyone shares one budget, or each user, agent, server, or tool gets its own. By default it's set to organization only, so everyone shares one budget. To split it, pick one or more options in Counted per:

Pick in Counted perEach of these gets its own budget
userEach user
agent instanceEach connected agent, such as one person's Claude Code
MCP serverEach MCP server, such as Jira or Slack
toolEach tool, such as search

For example, with a rule of 60 calls a minute:

  • organization only – everyone shares 60.
  • user – each user gets their own 60.
  • user and tool – each user gets 60 for search and a separate 60 for summarize. Using up search doesn't touch summarize, or anyone else's budget.

The order you pick them in doesn't matter. In the API, this is key_by, with the values user, agent_instance, mcp, and tool, and it always includes org.

Limit only some calls with a condition

Add a condition when the scope can't describe the calls you want to limit, for example calls from outside your office network. The rule then applies only to calls that match the condition.

Write the condition in Common Expression Language (CEL), the same language Agent Access conditions use. This one limits calls from outside the 10.8.0.0/16 network:

!request.ip.inCidr("10.8.0.0/16")

A condition can check:

  • The agent, including whether it's autonomous (agent, agent.autonomous)
  • The user (user)
  • The MCP server and tool (mcp, mcp.tool)
  • The call's arguments and IP address (request.args, request.ip)

If a condition isn't valid CEL, the console won't save the rule. If a condition can't be checked when a call comes in, the limit applies anyway.

Usage limit rule editor with the condition editor open on a saved CEL condition
The condition editor opens expanded when a rule has a condition

What counts against a budget

Only tool calls that reach the MCP server count. For example, under a rule of 60 calls a minute, every Jira search that reaches Jira uses 1 of those 60.

These calls don't count:

  • A call that an Access Policy blocks.
  • A call to an app the user hasn't connected their account to yet. The user gets the link to connect, not a "Rate limit exceeded" error.

Every matching rule applies

When several rules match a call, each one counts it, and none of them takes priority. If any of them is out of budget and set to Refuse the call, the gateway refuses the call.

This lets a broad rule and a narrow rule work together:

  • 1000 calls a minute for everyone, with Counted per set to organization only
  • 50 calls a minute for each user, with Counted per set to user

One user can't use up the whole organization's budget. And no matter how many users are active, the organization never goes over 1000 calls a minute.

When a call goes over a limit

When a usage limit refuses a call, the agent gets a message it can read, so it can wait and try again:

Rate limit exceeded for "search". Retry in 4s.

Agent Trail marks the call rate limited and names the rule that refused it.

Sometimes the MCP server refuses a call because of its own limit, not a rule you set. Agent Trail marks those calls rate limited by upstream server, with no rule named. If you see that often, add a rule that keeps agents under the server's limit.

Limits you didn't set

By default, no calls are limited until you add a rule.

If Agent Trail shows a call refused by Default per-user limit or Default per-org limit, you won't find that rule on the Usage Limits page. SecureAuth can turn these on for the whole service. Ask your SecureAuth contact about it.

Where rules are listed

Find the rules on Policy Controls › Usage Limits, pictured at the top of this page. Each row shows a rule's scope, its budget, its Counted per options, and whether it refuses calls or only logs them.

  • A rule set to organization only shows org-wide.
  • A rule split by Counted per shows one label for each option you picked, such as user and tool.

Add a rule

This example stops any one person's agents from making more than 50 Jira calls a minute.

  1. Click Add rate limit.
  2. In the scope, pick the calls the rule covers, for example the Jira MCP server.
  3. Set Calls and Window, for example 50 calls per 1 minute. With a window of a minute or less, the whole budget is available at once, so leave Burst at 0.
  4. In Counted per, pick user so each person gets their own 50. Leave it set to organization only and everyone shares one budget.
  5. Leave When the budget runs out at Log only: let the call through, the default, to test the rule first.
  6. To limit only some calls, such as calls from outside your office network, click + condition. See Limit only some calls with a condition.
  7. The editor suggests a name based on the rule's settings. Replace it with your own.
  8. Set the status to Active. Draft and Disabled rules are saved but not enforced.
Usage limit rule editor with name, scope, budget, and burst fields
The rule editor sets a rule's scope, budget, Counted per, and whether it refuses calls or only logs them

Test a rule before you enforce it

A limit set too low refuses work people need, so try a new rule in log-only mode first.

  1. In the rule editor, leave When the budget runs out at Log only: let the call through, the default.
  2. Let the rule run on real traffic. Every call still goes through, and the rule records each one it would have refused.
  3. In Agent Trail, look for calls marked logged, not blocked with the rule's name. They show which calls the rule would have refused, and for whom.
  4. When the number looks right, edit the rule and choose Refuse the call.

In the API, log-only is log_only.

Next steps

You can now cap MCP tool calls for the whole organization, each user, or each tool. Next, find the MCP server that gets the most calls, and start there.

On this page