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/<area> sub-MCPs, and the software factory tools.

Rate Limits by Tier

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.

What Each Call Costs

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

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:

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:

{
  "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.

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:

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:

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:

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:

// 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:

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.

Common Scenarios

Bulk App Creation

Problem: Creating 50 apps hits rate limit.

Solution (BUILDER tier):

// 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:

// 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:

# 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 - All available tools
• Common Workflows - Efficient usage patterns
• Authentication - Token management