Rate Limits and Pagination in Forktastic's MCP Server

Every API needs rate limits. The Forktastic MCP server enforces 60 requests per minute and 5,000 requests per day per token, with offset-based pagination on list endpoints. This is the reference doc — what the limits are, how they behave when exceeded, how pagination works, and how to design agents that stay within bounds.

The numbers

• 60 requests per minute per token. Bursting above 60 in a sliding 60-second window returns HTTP 429.
• 5,000 requests per day per token. Daily window is UTC midnight to UTC midnight. Exceeding returns HTTP 429 until the bucket resets.
• Per-token, not per-account. If you have three PATs, you have 3 × 60/min and 3 × 5,000/day.

What a 429 response looks like

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
}

The Retry-After header tells you how long to wait. For per-minute limits, it's typically 0-60s. For per-day limits, it can be hours.

Pagination

List endpoints (search_recipes, list_cookbooks, search_cookbooks, get_trending) use offset-based pagination:

• limit — items per page. Default 20, max 100.
• offset — number of items to skip. Default 0.

To page through results, increment offset by limit each call. To fetch all items, keep paging until you get a short page (fewer items than limit), which means you've reached the end.

The PGRST103 offset-overshoot behavior

If you set offset past the total count, older versions of the API returned an HTTP 416 error (PGRST103). Current behavior: offset overshoot returns an empty array, not an error. This makes paging-until-empty work cleanly. Don't rely on PGRST103 errors as an end-of-list signal — use array length.

Agent design patterns that stay within bounds

Cache when possible. If your agent reads the same cookbook list every hour, cache it. The data changes slowly.

Batch reads. Use search with a larger limit instead of looping with limit=1. One search_recipes call with limit=100 is one request; 100 calls with limit=1 is 100 requests.

Respect Retry-After. When you hit a 429, wait the exact time the header says. Don't aggressively retry — that just compounds the throttle.

Stagger background jobs. If your weekly meal-plan agent runs every Monday at 8am and so does a thousand other people's, you'll all hit the rate limit. Add a small random jitter (±5 minutes) so the load spreads.

Are these limits going to change?

Possibly upward, if usage patterns justify. The current numbers are conservative for a brand-new MCP server in production. We'd rather start tight and loosen than start loose and have to tighten retroactively (which breaks every agent that was relying on higher limits).

What happens if I need higher limits

For now: split your workload across multiple PATs (each has its own bucket), or batch your reads more aggressively. Future: we'll likely offer tier-based limits for users with legitimate higher-volume needs.

Where to go next

For tool reference, 7 MCP tools. For PAT management, PAT walkthrough. For Claude setup, Claude walkthrough. For the MCP pillar, MCP pillar guide.