Rate Limits and Budgets

MCP tool calls pass through the same caller API key boundary as model requests. The rate limits and budgets you set on a caller API key govern that key's tools/call requests with no separate MCP configuration. This page explains which controls apply, how the gateway enforces them on the MCP path, and how to verify the behavior.

For the full rate-limit field reference and counter-storage options, see Rate Limits. For budget configuration in managed deployments, see Budgets.

What the Gateway Governs

The gateway applies rate-limit and budget checks only to tools/call requests. The MCP handshake (initialize) and tool discovery (tools/list) are not rate-limited, so a throttled caller can still connect and list the tools its key allows — it just cannot invoke another tool until the window resets.

When a tools/call is rejected — by a rate limit or a budget — the gateway returns before it contacts any upstream MCP server, and it still records the rejected call as a usage event.

Which Rate Limits Apply

A caller API key's rate_limit object carries request-rate, token-rate, and concurrency limits. On the MCP path:

Limit	Applies to MCP tool calls	Notes
rps, rpm, rph, rpd	Yes	Each tools/call counts as one request in the matching window.
concurrency	Yes	Each in-flight tool call holds one concurrency permit until it returns.
tpm, tpd	Not drawn down	Token-rate windows count model tokens. An MCP tool call carries no token cost, so it adds nothing to a token window — but a window already exhausted by the key's model traffic still blocks that key's tool calls.

Because tool calls carry no token cost, use the request-rate limits (rps, rpm, rph, rpd) or concurrency to throttle MCP callers directly. A tool call never draws down a tpm/tpd window, so token limits alone do not cap MCP call volume — though an already-exhausted token window on the caller's key, filled by that key's model traffic, still rejects the key's MCP tool calls with HTTP 429 until the window resets.

Configure a Tool-Call Rate Limit

Set a rate limit on the caller API key. Updates replace the resource, so include the existing key hash, model access, and tool access along with the new rate_limit. This example limits the caller to one MCP tool call per minute:

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"

curl -sS -X PUT "http://127.0.0.1:3001/admin/v1/apikeys/YOUR_API_KEY_ID" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "key_hash": "'"${AISIX_API_KEY_HASH}"'",
    "allowed_models": [],
    "allowed_tools": ["github__*"],
    "rate_limit": {
      "rpm": 1
    }
  }'

Verification

Connect an MCP client with this caller API key and call a permitted tool twice within the same minute.

Expected result: the client connects and lists permitted tools normally. The first tools/call succeeds. A second tools/call within the same minute is rejected with HTTP 429 before AISIX contacts the upstream MCP server. The handshake and tools/list continue to work while the caller is throttled.

Apply Budgets in Managed Deployments

Budgets are enforced in AISIX Cloud managed deployments. When a budget that covers the caller API key is exhausted, the gateway rejects that key's tools/call requests with a budget_exceeded error before contacting the upstream MCP server, the same check the model path runs.

MCP tool calls carry no token cost, so they do not add to token-based spend themselves. A budget exhausted by the caller's model traffic still blocks that caller's MCP tool calls, because both share one caller API key and one budget. See Budgets for budget targets, the rejection response, and caching behavior.

Self-hosted deployments

Budget enforcement requires the AISIX Cloud control plane. In a self-hosted gateway, use caller API key rate limits to govern MCP tool-call volume.

Manage Rate Limits and Budgets on AISIX Cloud

On AISIX Cloud, you set these controls from the caller API key form in the dashboard instead of the Admin API:

1. Open the environment where the MCP server is exposed and go to API keys.
2. Create or edit the caller API key the MCP client uses. Set its tool access in the key's create or edit form; set its rate limits and budget in the sections on the key's card.
3. In the Rate limits section, set the request limits (per second, minute, hour, or day) and concurrency. These apply to the key's MCP tool calls as well as its model requests. The token limits track model tokens, which tool calls do not add to.
4. Add a budget on the same key — or use the Budgets page for organization- and environment-wide caps. Once the key's budget is exhausted, the gateway blocks its MCP tool calls too.

Because tool access, rate limits, and the budget all attach to the same caller API key, you configure a key's MCP governance in one place. See AISIX Cloud.

Next Steps

• Guardrails — inspect MCP tool arguments and results.
• Observability — read the usage events and metrics tool calls emit, including rejected calls.
• Rate Limits — the full rate-limit field reference and counter-storage options.
• Budgets — configure budgets for managed deployments.