Limite de requisições

O servidor MCP conta as requisições em dois baldes, ambos por pessoa na organização — o org e o sub do token, nunca o token em si:

Balde	O que conta	Limite
O do próprio MCP	Toda mensagem: initialize, tools/list, cada tools/call…	600 por minuto
O do endpoint despachado	Cada tools/call, no endpoint da API para onde a tool despacha	600 por minuto

Trocar de token não zera o orçamento: um token novo — de uma nova autorização OAuth ou um novo token pessoal — da mesma pessoa na mesma organização cai nos mesmos baldes. A mesma pessoa em outra organização tem orçamento próprio.

Uma chamada de tool nunca é mais barata que o endpoint que ela espelha: ela gasta o balde do MCP e, de novo, o do endpoint. Isso é deliberado — um agente que varre listagens em laço não deve conseguir contornar o limite que a mesma varredura pagaria por REST.

Tentativas com token recusado são estranguladas por IP: 60 por minuto; depois, 429. Um token que não verifica não pode ter balde próprio. Uma requisição sem token nenhum — o primeiro passo de todo cliente, antes do OAuth — não conta como tentativa.

Quando o limite é atingido

Quando o balde do MCP se esgota, o servidor responde 429 — a mensagem JSON-RPC não chega a ser processada:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 37
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793016060

{ "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded" } }

Quando é o balde do endpoint que se esgota, a mensagem já foi aceita: o tools/call volta um resultado isError com o RATE_LIMITED da API — veja Erros.

Nos dois casos, espere os segundos de Retry-After (ou até o instante de X-RateLimit-Reset) antes da próxima requisição. A janela é fixa: tentar antes só desperdiça chamadas. O limite do endpoint é o mesmo da API REST.

Gastando menos

Um agente consome o mesmo orçamento que uma integração, e ainda paga contexto por linha que traz. Dois hábitos resolvem quase tudo:

• Filtre antes de paginar. dunning_charges_list { status: "overdue", due_date_to: "2026-09-30" } custa uma requisição; varrer todas as cobranças para filtrar no modelo custa dezenas. Veja Listagem e paginação.
• Use per_page: 100 quando for mesmo percorrer uma lista: menos requisições para a mesma informação.