Limites de débit et pagination dans le serveur MCP de Forktastic

Chaque API a besoin de limites de débit. Le serveur MCP de Forktastic applique 60 requêtes par minute et 5 000 requêtes par jour par jeton, avec une pagination basée sur l’offset sur les points de terminaison de liste. Voici le document de référence : quelles sont les limites, comment elles se comportent lorsqu’elles sont dépassées, comment fonctionne la pagination et comment concevoir des agents qui restent dans les limites.

Les chiffres

• 60 requêtes par minute par jeton. Le dépassement de 60 dans une fenêtre glissante de 60 secondes renvoie HTTP 429.
• 5 000 requêtes par jour par jeton. La fenêtre quotidienne va de minuit UTC à minuit UTC. Le dépassement renvoie HTTP 429 jusqu’à la réinitialisation du bucket.
• Par jeton, pas par compte. Si vous avez trois PAT, vous avez 3 × 60/min et 3 × 5 000/jour.

À quoi ressemble une réponse 429

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

{
  "error": "rate_limited",
  "limit_type": "per_minute",
  "reset_in_seconds": 12
}

L’en-tête Retry-After vous indique combien de temps attendre. Pour les limites par minute, il est généralement de 0 à 60 secondes. Pour les limites par jour, il peut être de plusieurs heures.

Pagination

Les points de terminaison de liste (search_recipes, list_cookbooks, search_cookbooks, get_trending) utilisent la pagination basée sur l’offset :

• limit — nombre d’éléments par page. Par défaut, 20, maximum 100.
• offset — nombre d’éléments à ignorer. Par défaut : 0.

Pour parcourir les résultats, incrémentez l’offset par la limite à chaque appel. Pour récupérer tous les éléments, continuez la pagination jusqu’à obtenir une page courte (moins d’éléments que la limite), ce qui signifie que vous avez atteint la fin.

Le comportement de dépassement d’offset PGRST103

Si vous définissez l’offset au-delà du nombre total, les anciennes versions de l’API renvoyaient une erreur HTTP 416 (PGRST103). Comportement actuel : le dépassement d’offset renvoie un tableau vide, pas une erreur. Cela permet à la pagination jusqu’à vide de fonctionner correctement. Ne vous fiez pas aux erreurs PGRST103 comme signal de fin de liste : utilisez la longueur du tableau.

Modèles de conception d’agent qui restent dans les limites

Mettre en cache lorsque cela est possible. Si votre agent lit la même liste de livres de cuisine toutes les heures, mettez-la en cache. Les données changent lentement.

Lectures par lots. Utilisez la recherche avec une limite plus grande au lieu de boucler avec limit=1. Un appel search_recipes avec limit=100 est une requête ; 100 appels avec limit=1 représentent 100 requêtes.

Respectez Retry-After. Lorsque vous atteignez un 429, attendez exactement le temps indiqué par l’en-tête. N’essayez pas de manière agressive, cela ne fait qu’aggraver la limitation.

Échelonnez les tâches en arrière-plan. Si votre agent de planification de repas hebdomadaire s’exécute tous les lundis à 8 heures du matin, tout comme les milliers d’autres personnes, vous atteindrez tous la limite de débit. Ajoutez une petite gigue aléatoire (±5 minutes) afin que la charge se répartisse.

Ces limites vont-elles changer ?

Peut-être à la hausse, si les schémas d’utilisation le justifient. Les chiffres actuels sont prudents pour un tout nouveau serveur MCP en production. Nous préférons commencer petit et relâcher que de commencer large et de devoir resserrer rétroactivement (ce qui casse tous les agents qui comptaient sur des limites plus élevées).

Que se passe-t-il si j’ai besoin de limites plus élevées

Pour l’instant : répartissez votre charge de travail sur plusieurs PAT (chacun a son propre bucket) ou regroupez vos lectures de manière plus agressive. À l’avenir : nous proposerons probablement des limites basées sur des niveaux pour les utilisateurs ayant des besoins légitimes de volumes plus importants.

Où aller ensuite

Pour la référence des outils, 7 outils MCP. Pour la gestion des PAT, Présentation des PAT. Pour la configuration de Claude, Présentation de Claude. Pour le pilier MCP, Guide du pilier MCP.