Límites de frecuencia y paginación en el servidor MCP de Forktastic

Toda API necesita límites de frecuencia. El servidor MCP de Forktastic aplica 60 solicitudes por minuto y 5000 solicitudes por día por token, con paginación basada en desplazamiento en los puntos finales de la lista. Este es el documento de referencia: cuáles son los límites, cómo se comportan cuando se exceden, cómo funciona la paginación y cómo diseñar agentes que se mantengan dentro de los límites.

Los números

• 60 solicitudes por minuto por token. Superar las 60 en una ventana deslizante de 60 segundos devuelve HTTP 429.
• 5000 solicitudes por día por token. La ventana diaria es desde la medianoche UTC hasta la medianoche UTC. Exceder el límite devuelve HTTP 429 hasta que se restablezca el bucket.
• Por token, no por cuenta. Si tiene tres PAT, tiene 3 × 60/min y 3 × 5000/día.

Cómo se ve una respuesta 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
}

El encabezado Retry-After le indica cuánto tiempo debe esperar. Para los límites por minuto, normalmente es de 0 a 60 segundos. Para los límites por día, pueden ser horas.

Paginación

Los puntos finales de la lista (search_recipes, list_cookbooks, search_cookbooks, get_trending) utilizan la paginación basada en desplazamiento:

• limit: elementos por página. Predeterminado 20, máximo 100.
• offset: número de elementos para omitir. Predeterminado 0.

Para paginar los resultados, aumente el desplazamiento por límite en cada llamada. Para obtener todos los elementos, siga paginando hasta obtener una página corta (menos elementos que el límite), lo que significa que ha llegado al final.

El comportamiento de sobreimpulso de desplazamiento PGRST103

Si establece el desplazamiento más allá del recuento total, las versiones anteriores de la API devolvían un error HTTP 416 (PGRST103). Comportamiento actual: el sobreimpulso de desplazamiento devuelve una matriz vacía, no un error. Esto hace que la paginación hasta que esté vacía funcione limpiamente. No confíe en los errores PGRST103 como una señal de fin de lista: utilice la longitud de la matriz.

Patrones de diseño de agentes que se mantienen dentro de los límites

Almacene en caché cuando sea posible. Si su agente lee la misma lista de libros de cocina cada hora, guárdela en caché. Los datos cambian lentamente.

Lecturas por lotes. Utilice la búsqueda con un límite mayor en lugar de realizar un bucle con limit=1. Una llamada a search_recipes con limit=100 es una solicitud; 100 llamadas con limit=1 son 100 solicitudes.

Respete Retry-After. Cuando alcance un 429, espere el tiempo exacto que indica el encabezado. No intente volver a intentarlo agresivamente, eso solo agrava la limitación.

Escalone los trabajos en segundo plano. Si su agente semanal de planificación de comidas se ejecuta todos los lunes a las 8 a. m. y también lo hacen los de otras mil personas, todos alcanzarán el límite de frecuencia. Agregue una pequeña fluctuación aleatoria (±5 minutos) para que la carga se distribuya.

¿Van a cambiar estos límites?

Posiblemente hacia arriba, si los patrones de uso lo justifican. Los números actuales son conservadores para un nuevo servidor MCP en producción. Preferimos comenzar ajustados y aflojar que comenzar sueltos y tener que apretar retroactivamente (lo que rompe todos los agentes que dependían de límites más altos).

Qué sucede si necesito límites más altos

Por ahora: divida su carga de trabajo en múltiples PAT (cada uno tiene su propio bucket) o procese sus lecturas de forma más agresiva. Futuro: es probable que ofrezcamos límites basados en niveles para los usuarios con necesidades legítimas de mayor volumen.

A dónde ir después

Para obtener información sobre las herramientas, 7 herramientas MCP. Para la administración de PAT, Tutorial de PAT. Para la configuración de Claude, Tutorial de Claude. Para el pilar MCP, Guía del pilar MCP.