429-throttle-mcp

English | 中文

No more API 429 rejections — a rate-limited MCP proxy that lets models automatically control their call pace in long-running tasks.

What it is

Many free LLM APIs (Grok, Gemini, Dots, etc.) only allow about 30 calls per minute. When models work on long-running tasks (searching + generating PPTs, batch tool calls), they can easily exceed the quota and get rejected with 429.

429-throttle-mcp provides a transparent rate-limiting layer for this pain point:

模型 → call_api 工具 → 限流器 → 实际 API 请求 → 返回结果 + 用量快照

The model doesn't need to know rate limits exist; it just calls call_api normally. The rate-limiting logic runs transparently inside MCP — if quota is available, the call goes through; if not, the model is told how long to wait before retrying.

Related MCP server: mcp-doorman

Package structure

Monorepo containing two independent npm packages that share the core rate-limiting logic:

429-throttle-mcp/
├── packages/
│   ├── rate-limiter.js              # 核心限流逻辑（共享）
│   ├── 429-throttle-mcp/            # MCP Server 包
│   │   ├── package.json
│   │   ├── server.js
│   │   └── README.md
│   └── dsh-throttle/                # DSH Plugin 包
│       ├── package.json
│       ├── plugin.js
│       └── README.md
├── dsh-manifest.json
├── README.md
└── .env.example

Core parameters

Exposed tools

call_api

Sends HTTP requests through the rate-limiting proxy. All external API calls must go through this tool.

Returns: API response + _meta.rateLimit usage snapshot. If rejected by rate limiting, returns a RATE_LIMIT_EXCEEDED error with a suggested retryAfterSeconds wait time.

get_rate_limit_status

Queries current rate limit usage. Returns used/remaining call counts and token counts, plus recommendations. Does not include queue counters, to avoid user anxiety.

set_rate_limit

Dynamically adjusts rate limit parameters (like adjusting a slider, takes effect in real time without restart).

Installation

MCP clients (e.g., ZCode)

npm install 429-throttle-mcp

Add to the MCP configuration:

{
  "mcpServers": {
    "429-throttle-mcp": {
      "command": "node",
      "args": ["node_modules/429-throttle-mcp/server.js"],
      "env": {
        "MAX_CALLS": "30",
        "MAX_TOKENS": "750000"
      }
    }
  }
}

DeepSeek Harness

npm install dsh-throttle

Add to the DSH configuration:

{
  "plugins": {
    "dsh-throttle": {
      "maxCalls": 30,
      "maxTokens": 750000
    }
  }
}

Workflow example

When a model works on a brand PPT search task:

1. Call get_rate_limit_status → confirm sufficient quota

2. Call call_api → search brand keywords

3. If rejected → wait retryAfterSeconds then retry

4. Repeat steps 2-3 until all information is collected

5. Call set_rate_limit → tighten rate limit parameters for the generation phase

Rate limiting algorithm

Sliding Window + Token Bucket: maintains a 60-second sliding window, recording the timestamp and token consumption of each call. Old records outside the window are automatically cleaned up. When the limit is exceeded, the remaining wait time is calculated from the earliest record.

Concurrency safety: tryConsume() is a synchronous function, naturally serialized in Node.js's single-threaded event loop, so no race conditions occur.

Why use this instead of writing "call slower" in the prompt?

Application scenario Keyword

429报错, anti 429, MCP限流, 大模型每分钟调用限制, 免费大模型速率限制, Agent批量调用触发429, MCP排队调用, RPM, TPM, rate limiter mcp, quota guard, mcp server, mcp proxy, throttle, llm api quota, cop, HTTP 429, Too Many Requests, rate limiting, token bucket, sliding window, API proxy, LLM rate limit, AI API throttle, concurrent rate limit, 30 calls per minute

License

MIT