mcp-pool
MCP Key Pool Proxy
mcp-pool is itself an MCP server. Pool multiple API keys per service and distribute tool calls across them — one active subprocess at a time, rotate keys on rate-limit.
Features
Key Pooling
Pool multiple API keys for rate-limited MCP servers. Distribute requests across keys to avoid exhausting any single quota.
Lazy Failover
One subprocess per pool at a time. On rate-limit or crash, the current upstream is closed and a new one spawns with the next key.
Tool Prefixing
All tools are prefixed with their pool name (e.g. `brave-search__brave_web_search`) to avoid name collisions across pools.
Rate Limit Detection
Configurable regex patterns matched against tool error text. Non-matching errors are returned to the client immediately without retry.
Key Retry
Keys are tried in order. Startup retries across all keys until one connects. On failure, advances to the next key.
Stdio Transport
All upstream MCP servers communicate via stdio subprocesses. No HTTP endpoints to manage.
Quick Start
# Install globally
npm install -g mcp-pool
# Create a config
cat > ~/.config/mcp-pool/mcp-pool.yaml << 'EOF'
pools:
brave-search:
command: bunx
args: ["-y", "@brave/brave-search-mcp-server"]
keys:
- {BRAVE_API_KEY: "${BRAVE_API_KEY_1}"}
- {BRAVE_API_KEY: "${BRAVE_API_KEY_2}"}
rateLimitPatterns:
- "rate_limit_exceeded"
- "too many requests"
EOF
# Run it
bunx mcp-pool
How It Works
- 1. Configure — Define pools in `mcp-pool.yaml`. Each pool = one MCP server type with N API keys. Config is auto-discovered from `./mcp-pool.yaml`, `./.mcp-pool.yaml`, or `~/.config/mcp-pool/mcp-pool.yaml`.
- 2. Start — mcp-pool tries each key in order until one connects. Only one upstream subprocess runs at a time per pool.
- 3. Route — When a tool call arrives, mcp-pool strips the `{poolName}__` prefix to identify the pool, then forwards the call to the active upstream.
- 4. Recover — On rate-limit or transport error, the current upstream is closed, the cursor advances to the next key, and a new subprocess spawns automatically. Rate-limited keys remain unavailable for the configured cooldown (300 seconds by default).
Config Reference
| Field | Required | Description |
|---|---|---|
| command | Yes | Executable to spawn (e.g. npx, bunx) |
| args | Yes | CLI arguments |
| keys | Yes | Array of env-var objects, at least 1 |
| rateLimitPatterns | Yes | Regex patterns matched against error text |
| cooldownSeconds | No | Seconds a rate-limited key is skipped; defaults to 300 |