429-throttle-mcp

English | 한국어

더 이상 API 429 거부 없이 — 속도 제한이 내장된 MCP 프록시로, 모델이 장기 작업에서 자동으로 호출 속도를 조절하게 합니다.

소개

많은 무료 대형 모델 API(Grok, Gemini, Dots 등)는 분당 약 30회만 호출할 수 있습니다. 모델이 장기 작업(검색 + PPT 생성, 대량 도구 호출)을 수행할 때 한도를 초과하여 429 거부를 받기 쉽습니다.

429-throttle-mcp는 이 문제점에 투명한 속도 제한 계층을 제공합니다:

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

모델은 속도 제한의 존재를 알 필요가 없습니다. 그저 정상적으로 call_api를 호출하면 됩니다. 속도 제한 로직은 MCP 내부에서 투명하게 실행됩니다 — 한도가 충분하면 통과시키고, 부족하면 모델에게 얼마나 기다린 후 재시도할지 알려줍니다.

Related MCP server: tiny-mcp-gateway

패키지 구조

Monorepo로, 두 개의 독립적인 npm 패키지를 포함하며 핵심 속도 제한 로직을 공유합니다:

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

핵심 파라미터

노출되는 도구

call_api

속도 제한 프록시를 통해 HTTP 요청을 전송합니다. 모든 외부 API 호출은 이 도구를 거쳐야 합니다.

반환: API 응답 + _meta.rateLimit 사용량 스냅샷. 속도 제한으로 거부되면 RATE_LIMIT_EXCEEDED 오류를 반환하며 retryAfterSeconds 권장 대기 시간을 포함합니다.

get_rate_limit_status

현재 속도 제한 사용 현황을 조회합니다. 사용됨/남은 호출 횟수와 Token 수, 그리고 권장 사항을 반환합니다. 대기열 카운터는 포함하지 않아 사용자 불안을 방지합니다.

set_rate_limit

속도 제한 파라미터를 동적으로 조정합니다(슬라이더 조절에 해당, 재시작 없이 실시간 적용).

설치

MCP 클라이언트(예: ZCode)

npm install 429-throttle-mcp

MCP 구성에 추가:

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

DSH 구성에 추가:

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

워크플로 예시

모델이 브랜드 PPT 검색 작업을 수행할 때:

1. get_rate_limit_status 호출 → 한도가 충분한지 확인

2. call_api 호출 → 브랜드 키워드 검색

3. 거부되면 → retryAfterSeconds만큼 기다린 후 재시도

4. 모든 정보를 수집할 때까지 2-3 반복

5. set_rate_limit 호출 → 생성 단계에 맞춰 속도 제한 파라미터를 조정

속도 제한 알고리즘

슬라이딩 윈도우 + 토큰 버킷(Sliding Window + Token Bucket): 60초 슬라이딩 윈도우를 유지하며, 각 호출마다 타임스탬프와 token 소비량을 기록합니다. 윈도우 밖의 오래된 기록은 자동으로 정리됩니다. 한도 초과 시 가장 오래된 기록의 남은 대기 시간을 계산합니다.

동시성 안전: tryConsume()은 동기 함수로, Node.js 단일 스레드 이벤트 루프에서 자연스럽게 직렬화되어 경쟁 조건이 발생하지 않습니다.

프롬프트에 "천천히 호출하세요"라고 쓰는 것보다 이걸 쓰는 이유는?

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