Skip to main content

Rate Limiting

The MCP server shares the same limits as the REST API, counted per person and organization — the token's sub and org, not the token itself.

Switching tokens does not reset the budget: a new token, whether from a fresh OAuth authorization or a new personal token, for the same person in the same organization lands in the same bucket. The same person in another organization has a budget of its own.

A tool call is never cheaper than the endpoint it mirrors: the request is counted once in the MCP's own bucket and, when it is a tools/call, again by the bucket of the endpoint it dispatches to. That is deliberate — an agent looping over listings should not be able to dodge the limit the same sweep would pay over REST.

Attempts with an invalid token are throttled by IP, not by token, the same way the REST edge does it: a token that does not verify cannot have a bucket of its own. A request with no token at all — every client's first step, before OAuth — does not count as an attempt.

When the limit is hit​

The server answers 429 — the JSON-RPC message is not processed at all:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json

{ "error": { "code": "TOO_MANY_REQUESTS", "message": "Rate limit exceeded" },
  "retry_after": 37 }

Wait the Retry-After seconds before the next request. The per-account, per-request-type limits are on the API rate-limit page — they are the same ones.

Spending less​

An agent burns the same budget as your backend, and additionally pays context for every row it brings back. Two habits cover almost everything:

  • Filter before paginating. dashboards_portal_users_list { status: "suspended" } costs one request; sweeping every portal user to filter in the model costs dozens.
  • Ask only for the columns you need. fields: ["email", "status", "last_login_at"] does not reduce the number of requests, but it greatly reduces the context spent — see Listing, sorting and fields.