Rate limit
The MCP server counts requests per person in the organization — the token's org and sub together — never per token.
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.
Two buckets
| Bucket | What it counts | Limit |
|---|---|---|
| MCP | Every message — initialize, tools/list, each tools/call, any other method | 600 per minute |
| Dispatched endpoint | Each tools/call also spends the bucket of the /v1 endpoint it dispatches to, under the same key | 600 per minute |
A tool call is never cheaper than the endpoint it mirrors: it is counted once by the MCP bucket and again by the endpoint's. 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 a refused token are throttled by IP, not by token: 60 per minute, after which the answer is 429. A token that does not verify cannot have a bucket of its own.
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
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1753272060
Content-Type: application/json
{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded" } }
Wait the Retry-After seconds before the next request.
When it is the dispatched endpoint's bucket that runs out, the MCP message was already accepted: the tools/call comes back as a tool result flagged isError, carrying the API's RATE_LIMITED envelope — see Errors. Wait before calling again just the same.
The window semantics are the API's — see Rate limiting in the API documentation.
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.
dunning_charges_list { status: "overdue", due_date_to: "2026-09-30" }costs one request; sweeping every charge to filter in the model costs dozens. - Use the largest page you need.
per_page: 100cuts the number of requests for a full sweep — see Listing and pagination.