Limite de Requisições

O servidor MCP aceita 600 requisições por minuto por pessoa e organização — o sub e o org do token, não o token em si.

Trocar de token não zera o orçamento: um token novo, seja de uma nova autorização OAuth ou um novo token pessoal, da mesma pessoa na mesma organização cai no mesmo bucket. A mesma pessoa em outra organização tem orçamento próprio.

Uma chamada de tool nunca é mais barata que a rota que ela espelha: a requisição é contada uma vez no bucket do próprio MCP e, quando é um tools/call, de novo no bucket da API v1 (600 por minuto), com a mesma chave de pessoa e organização. Rotas com limite próprio também o aplicam: kadu_executions_search tem mais 30 por minuto, como GET /v1/executions/search. Isso é deliberado — um agente que varre listagens em laço não deve conseguir contornar o limite que a mesma varredura pagaria pela API.

Tentativas com token recusado são estranguladas por IP, não por token: um token que não verifica não pode ter bucket 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

Estourado o bucket do MCP, o servidor responde 429 — a mensagem JSON-RPC não chega a ser processada:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1793280037
Cache-Control: no-store
Content-Type: application/json

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

Espere os segundos de Retry-After antes da próxima requisição. X-RateLimit-Limit e X-RateLimit-Remaining dizem o tamanho do bucket e o que sobrou; X-RateLimit-Reset é quando ele renova, em segundos desde a época Unix.

Estourado o bucket da rota, a requisição HTTP é 200 e o resultado da tool volta isError com o erro da API, RATE_LIMITED — veja Erros. Espere alguns segundos antes de chamar de novo. Os limites da API estão em Limites de requisição.

Gastando menos

Um agente consome orçamento como o seu backend, e ainda paga contexto por linha que traz. Três hábitos resolvem quase tudo:

• Filtre antes de paginar. kadu_executions_list { status: "failed", started_at_gte: "2026-10-01" } custa uma requisição; varrer todas as execuções para filtrar no modelo custa dezenas.
• Leia só o que é novo. Para acompanhar uma execução em andamento, passe after_sequence em kadu_executions_events_list e after_id em kadu_executions_logs_list, em vez de reler tudo a cada volta.
• Não consulte em laço. Uma aprovação por link se acompanha quando a pessoa diz que decidiu, não a cada poucos segundos.