Rate Limits and Budgets

For MCP traffic, the caller API key remains the traffic-control boundary. MCP tool calls share the key's request limits, concurrency limits, and budgets with model traffic, but they do not consume model tokens.

There is no separate MCP rate-limit or budget resource. Configure the caller API key, then verify the behavior on the MCP path.

Where Controls Apply

The gateway applies rate-limit and budget checks only to tools/call requests. The MCP handshake, including initialize, and tool discovery through tools/list are not rate-limited. A throttled caller can still connect and list the tools its key allows, but cannot invoke another tool until the window resets.

When a rate limit or budget rejects a tool call, AISIX returns before contacting the upstream MCP server and still records the rejected call as a usage event.

Applicable Rate Limits

A caller API key's rate_limit object can define request-rate, token-rate, and concurrency limits. On the MCP path, only request-rate and concurrency limits directly meter tool calls:

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	Indirectly	MCP tool calls carry no model tokens, so they do not add to token windows. If the caller key's model traffic already exhausted a token window, the key's tool calls are still rejected with HTTP 429 until the window resets.

Each field is optional. When a field is omitted, AISIX does not enforce that limit.

Use request-rate limits or concurrency to throttle MCP call volume. A token limit alone does not cap MCP tool calls.

For the full rate-limit field reference and counter-storage options, see Rate Limits.

Set a Caller Rate Limit

Update the caller API key with a rate_limit. The following self-hosted example keeps the key MCP-only and limits it to one tool call per minute. Include any existing key fields that should remain; the Admin API PUT replaces the key resource.

# Replace with your values
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" \
  --data-binary @- <<EOF
  {
    "key_hash": "${AISIX_API_KEY_HASH}",
    "allowed_models": [],
    "allowed_tools": ["github__*"],
    "rate_limit": {
      "rpm": 1
    }
  }
EOF

❶ Use an empty model allowlist when the key is only for MCP traffic. Preserve existing model access if the same key also needs to call models.

❷ rpm: 1 limits this caller API key to one request per minute.

To verify the limit, connect an MCP client with this caller API key and call a permitted tool twice within the same minute. The first tools/call succeeds. The second tools/call 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.

In managed deployments, configure the same caller API key limit in the AISIX managed control plane.

Apply Budgets in Managed Deployments

Budgets are configured in the AISIX managed control plane and enforced by the managed gateway. 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. This is 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.

In self-hosted deployments, use caller API key rate limits to govern MCP tool-call volume. For budget configuration details, see Budgets.

Next Steps

You have now applied caller API key controls to MCP traffic. Use these guides to observe the result or refine the shared limit and budget settings:

• Observability: review the usage events and metrics emitted by MCP tool calls.
• Rate Limits: review the full rate-limit field reference and counter-storage options.
• Budgets: configure budget targets, rejection behavior, and cache settings.