# Rate Limits Understanding and working with Chipp MCP Server rate limits --- The Chipp MCP Server enforces rate limits to ensure fair usage and platform stability. Every tool call spends **points** from a per-minute budget. A cheap read costs 1 point. A heavy tool costs more. Limits vary by subscription tier, and no plan is unlimited. These limits apply to every Chipp MCP endpoint: `build.chipp.ai/mcp`, `mcp.chipp.ai/mcp`, the `/mcp/` sub-MCPs, and the software factory tools. ## Rate Limits by Tier | Plan | `X-RateLimit-Tier` | Points per minute, per user | Per token or key | Per organization | MCP access | |------|--------------------|-----------------------------|------------------|------------------|------------| | Free | `FREE` | None | None | None | Not available | | Builder (legacy) | `BUILDER` | 30 | 30 | 150 | Full access | | Studio | `STUDIO` | 60 | 60 | 300 | Full access | | Studio Pro | `STUDIO_PRO` | 120 | 120 | 600 | Full access | | Do It With You | `ENTERPRISE` | 1200 | 1200 | 6000 | Full access | Each call spends its weight from three budgets at once: your user budget (shared by all your OAuth tokens and API keys), the budget of the token or key you used, and your organization's budget. A call goes through only if all three have room. > **Note:** MCP server access requires a Studio plan or higher. Free tier users cannot use the MCP server: requests return `403` with error code `tier_blocked`. > **Note:** Enterprise plans have a high default, not unlimited access. If your contract names a different number, we store it for your organization and it replaces the default. ## What Each Call Costs | Tool | Points per call | |------|-----------------| | `dispatch_ticket_batch` | 10 | | `export_conversations` | 10 | | `generate_image` | 10 | | `newsletter_import_contacts` | 10 | | `run_eval` | 10 | | `web_research` | 10 | | `ask_chief_of_staff` | 5 | | `bulk_update_app_settings` | 5 | | `chat_with_agent` | 5 | | `chat_with_app` | 5 | | `consult_agent` | 5 | | `diagnose_chat_latency` | 5 | | `dispatch_ticket` | 5 | | `generate_system_prompt` | 5 | | `generate_utterances` | 5 | | `get_app_analytics` | 5 | | `get_file_analytics` | 5 | | `get_model_usage` | 5 | | `get_moderation_stats` | 5 | | `get_monetization_stats` | 5 | | `get_response_time_analytics` | 5 | | `get_tag_analytics` | 5 | | `get_usage_by_app` | 5 | | `import_collection_tools` | 5 | | `import_tag_examples` | 5 | | `propose_platform_roll` | 5 | | `propose_ticket_batch` | 5 | | `run_nightly_ci` | 5 | | `run_ticket_ci` | 5 | | `spawn_subagent` | 5 | | `trigger_heartbeat` | 5 | | `add_project_files` | 3 | | `generate_suggestions` | 3 | | `get_nightly_ci_report` | 3 | | `get_release_digest` | 3 | | `get_usage` | 3 | | `publish_app` | 3 | | `query_database` | 3 | | `search_conversations` | 3 | | `search_messages` | 3 | | `web_search` | 3 | | `fetch_url` | 2 | | `get_ci_run_log` | 2 | | `search_kb_evidence` | 2 | | Every other tool | 1 | | `wait_for_tickets`, `watch_deploy`, `watch_ci_run`, `watch_release` | 0 points: they use a long-poll slot | | `initialize`, `tools/list`, `ping`, notifications | 0 points: they use a small separate budget of 60 per minute per token | A batch request (a JSON-RPC array) costs the sum of its calls. A request that costs more than your whole per-minute budget is refused, so split it. ## Other Limits | Limit | Value | |-------|-------| | Requests in flight at once, per user | 10 | | Requests in flight at once, per token or key | 8 | | Long-poll calls open at once, per user | 3 | | Long-poll calls open at once, per token or key | 2 | | Long-poll calls open at once, per organization | 10 | | Handshake calls (`initialize`, `tools/list`), per token or key per minute | 60 | | Requests per minute from one network address (all traffic) | 1200 | | Failed sign-ins per minute from one network address | 30 | | Repeated limit errors that block a token or address | 5 within 120 seconds | | Block length, first to last repeat | 1 min, 5 min, 30 min, 2 h | **Long-poll tools** (`wait_for_tickets`, `watch_deploy`, `watch_ci_run`, `watch_release`, and the live ticket stream) hold a request open. They do not spend points, so a client that watches tickets cannot use up its own budget. They take one of a small number of long-poll slots instead, and the slot is freed when the call finishes, fails, or your client disconnects. **Handshake calls** (`initialize`, `tools/list`, `ping`) have their own small budget per token, so reconnecting often never uses the budget for your tool calls. ## Rate Limit Headers Every response carries rate limit information, on every plan: | Header | Description | |--------|-------------| | `X-RateLimit-Tier` | Your subscription tier | | `X-RateLimit-Limit` | Points per minute in your user budget | | `X-RateLimit-Remaining` | Points left in the current window | | `X-RateLimit-Used` | Points used in the current window | | `X-RateLimit-Cost` | Points this request spent | | `X-RateLimit-Reset` | Unix timestamp when the window resets | | `X-RateLimit-Concurrency-Limit` | Requests you can have in flight at once | **Example response headers:** ``` HTTP/1.1 200 OK X-RateLimit-Tier: BUILDER X-RateLimit-Limit: 30 X-RateLimit-Remaining: 20 X-RateLimit-Used: 10 X-RateLimit-Cost: 10 X-RateLimit-Reset: 1704067260 X-RateLimit-Concurrency-Limit: 10 ``` ## Handling Rate Limits (429 Errors) When you exceed a limit, the server returns a `429 Too Many Requests` response. The `limit` field names the limit you hit, so your client knows what to do: ```json { "error": { "code": "rate_limited", "limit": "user", "message": "Rate limit exceeded (limit: user): your per-minute budget (shared by all your tokens and keys). Retry after 45 seconds. Do not retry sooner.", "retry_after_seconds": 45 } } ``` The same text is in the tool error, so an AI assistant that reads it will wait instead of retrying at once. The response also has `X-RateLimit-Limit-Hit` with the same value as `limit`. | `limit` | The limit you hit | |---------|-------------------| | `user` | your per-minute budget (shared by all your tokens and keys) | | `credential` | the per-minute budget of this one token or key | | `tenant` | your organization's per-minute budget | | `ip` | the per-minute request limit for your network address | | `concurrency` | the cap on requests in flight at once | | `long_poll` | the cap on long-running watch calls open at once | | `global` | the server-wide safety limit for this endpoint (not your fault, retry soon) | ### Repeated 429s A client that keeps sending requests after a 429 is blocked for a short time. The block grows each time it repeats (see "Other Limits"). While blocked, every request returns `429` with `"blocked": true` and a `Retry-After` for the end of the block. Always wait for `Retry-After`. ### Retry-After Header The `Retry-After` header tells you exactly when to retry: ``` HTTP/1.1 429 Too Many Requests Retry-After: 45 X-RateLimit-Limit-Hit: user X-RateLimit-Reset: 1704067260 ``` ### Implementing Retry Logic **Basic exponential backoff:** ```javascript async function callWithRetry(makeRequest, maxRetries = 3) { for (let attempt = 0; attempt < maxRetries; attempt++) { const response = await makeRequest(); if (response.status === 429) { const retryAfter = response.headers.get('Retry-After') || 60; console.log(`Rate limited. Waiting ${retryAfter}s...`); await sleep(retryAfter * 1000); continue; } return response; } throw new Error('Max retries exceeded'); } ``` **Respecting Retry-After:** ```python import time import requests def call_mcp(tool_name, args): response = requests.post( "https://build.chipp.ai/mcp", json={"method": "tools/call", "params": {"name": tool_name, "arguments": args}}, headers={"Authorization": f"Bearer {token}"} ) if response.status_code == 429: retry_after = int(response.headers.get('Retry-After', 60)) print(f"Rate limited. Sleeping {retry_after}s...") time.sleep(retry_after) return call_mcp(tool_name, args) # Retry return response.json() ``` ## Best Practices ### 1. Batch Operations Instead of calling tools one at a time, combine related operations: ``` # Inefficient: 10 separate calls for app in apps: update_app(app.id, {...}) # Better: Use bulk patterns where available # Or space out calls to stay within limits ``` ### 2. Use Caching Cache responses that don't change frequently: ```javascript const appCache = new Map(); const CACHE_TTL = 5 * 60 * 1000; // 5 minutes async function getApp(appId) { const cached = appCache.get(appId); if (cached && Date.now() - cached.timestamp < CACHE_TTL) { return cached.data; } const app = await mcpCall('get_app', { app_id: appId }); appCache.set(appId, { data: app, timestamp: Date.now() }); return app; } ``` ### 3. Monitor Your Usage Check the remaining points before large operations: ```javascript // Check headers from any response const remaining = parseInt(response.headers['x-ratelimit-remaining']); const resetTime = parseInt(response.headers['x-ratelimit-reset']); if (remaining < 5 && operations.length > 5) { const waitTime = resetTime - Math.floor(Date.now() / 1000); console.log(`Low on requests. Waiting ${waitTime}s before bulk operation...`); await sleep(waitTime * 1000); } ``` ### 4. Spread Requests Over Time For non-urgent bulk operations, spread requests evenly: ```javascript async function bulkUpdate(apps, updateFn) { const REQUESTS_PER_MINUTE = 25; // Stay under limit const DELAY_MS = 60000 / REQUESTS_PER_MINUTE; // ~2.4 seconds for (const app of apps) { await updateFn(app); await sleep(DELAY_MS); } } ``` ### 5. Use Pagination Wisely Fetch only what you need: ``` # Good: Small pages, specific queries list_apps(limit=10, offset=0) search_conversations(app_id="xxx", query="refund", limit=20) # Avoid: Large fetches you don't need list_apps(limit=1000) export_conversations(app_id="xxx", since="2026-01-01") # Use sparingly ``` ## Upgrading Your Limits Need higher limits? Upgrade your plan. Each plan's limit is in [Rate Limits by Tier](#rate-limits-by-tier). Upgrade Your Plan ## Common Scenarios ### Bulk App Creation **Problem:** Creating 50 apps hits rate limit. **Solution (BUILDER tier):** ```javascript // 30 requests/minute = ~2 seconds between requests for (const appConfig of appConfigs) { await createApp(appConfig); await sleep(2000); // 2 second delay } // Total time: ~100 seconds for 50 apps ``` ### Analytics Dashboard **Problem:** Fetching analytics for 20 apps exceeds limit. **Solution:** ```javascript // Option 1: Fetch in batches const batches = chunk(appIds, 5); for (const batch of batches) { await Promise.all(batch.map(id => getAppAnalytics(id))); await sleep(10000); // Wait 10s between batches } // Option 2: Cache results // Analytics don't change by the second - cache for 5+ minutes ``` ### CI/CD Integration **Problem:** Automated deployments need multiple tool calls. **Solution:** ```yaml # In your CI pipeline steps: - name: Update Chipp App run: | # Use retry logic ./update-app.sh --retry-on-rate-limit env: CHIPP_RETRY_DELAY: 60 CHIPP_MAX_RETRIES: 3 ``` ## Rate Limit FAQ **Q: Do rate limits apply per user or per organization?** A: Both, and per token. All of a user's OAuth tokens and API keys share one user budget. Each token or key also has its own budget, and your organization has a budget shared by all its members. Each team member has their own user budget. **Q: Does reading consume the same rate as writing?** A: No. Each tool has a weight. A cheap read costs 1 point. Exports, bulk analytics, image generation, ticket dispatch and batches cost more (see "What Each Call Costs"). `initialize` and `tools/list` do not spend this budget: they use a small separate one. Watch tools such as `wait_for_tickets` spend no points and use long-poll slots. **Q: Why did I get a 429 when I have points left?** A: Another limit was hit. Read the `limit` field of the error: `concurrency` means too many requests in flight, `long_poll` means too many open watch calls, `credential` or `tenant` means that token's or your organization's budget is spent, `ip` means too many requests from your network address, and `global` is a server-wide safety limit that clears in seconds. **Q: Are unauthenticated or failed requests limited?** A: Yes. Requests from one network address are counted whether or not they are signed in, and repeated failed sign-ins from one address are limited and then blocked for a short time. **Q: What happens if I'm rate limited mid-workflow?** A: Implement retry logic with exponential backoff. Your MCP client should handle 429 responses gracefully. **Q: Is there an unlimited plan?** A: No. Enterprise has a high default budget, and every response still carries the rate limit headers. **Q: Can I request higher limits for a specific use case?** A: Enterprise customers can negotiate custom limits for their organization. Contact sales@chipp.ai for details. --- ## Next Steps - [Tools Reference](/docs/guides/mcp/tools-reference) - All available tools - [Common Workflows](/docs/guides/mcp/workflows) - Efficient usage patterns - [Authentication](/docs/guides/mcp/authentication) - Token management