zekebuilds-lab/captcha-mcp

**Your MCP server returns 429 when agents pound it. captcha-mcp makes them earn their next call instead.** Hand the agent a proof-of-work puzzle (free, ~5s of CPU) or a 3-sat Lightning invoice — both are machine-readable backoff signals an autonomous caller can satisfy without an account, email, or API key.
Three tools over stdio or HTTP. Stdlib only. No signup, free fallback, self-hosted, no revenue share.
Why not 429?
429 Too Many Requests is the wrong shape for the agent era. Three patterns recur across MCP server reports:
- **Agent frameworks treat 429 as a connection failure.** They retry immediately, often with exponential backoff that is still too aggressive, and amplify the overload that triggered the limit in the first place.
- **There is no per-caller signal.** A 429 fires for the bucket, not the agent. One noisy caller gets every other caller throttled, and the server has no way to ask the noisy one to slow down specifically.
- **Retry-After is advisory and frequently ignored.** Agents do not consistently parse it, do not consistently respect it, and have no incentive to wait — the cost of retrying is zero.
captcha-mcp replaces the 429 with a 402-style challenge. The next call costs the caller something (CPU seconds or 3 sats). That cost is per-caller, machine-readable, and self-throttling — an agent that cannot solve the puzzle cannot flood the endpoint.
Quickstart
No install, no config, no API key. The server starts on stdio and waits for an MCP client.
To wire it into Claude Code, Cursor, or any MCP-compatible host, add to your config:
Or run npx @powforge/captcha-mcp --install to print the config block.
What it does
Wraps the PowForge pow-captcha service (captcha.powforge.dev) as three MCP tools:
| Tool | Purpose |
|-------------|-------------------------------------------------------------------------|
| challenge | Request a fresh proof-of-work puzzle. Returns {id, salt, difficulty, signature}. |
| verify | Submit a solved nonce. Returns a 5-minute HMAC-signed access token. |
| status | Server health, lifetime stats, L402 endpoint metadata. |
The free tier costs the agent ~5-10 seconds of CPU time (SHA-256, default 14 leading zero bits). The paid tier costs 3 sats over Lightning via L402 (RFC 7235 + bolt11 invoice in WWW-Authenticate).
Why this and not OAuth, API keys, or Stripe
| Approach | Per-call cost | Account required | Self-hosted | Agent-friendly |
|---------------------------|--------------------|------------------|-------------|----------------|
| API keys | $0 | yes | n/a | no |
| OAuth | $0 | yes | n/a | no |
| Stripe metering | high overhead | yes | n/a | no |
| Managed MCP auth platform | 100–2000 sats | no | no | yes |
| **PoW + L402 (this)** | seconds or 3 sats | **no** | **yes** | **yes** |
Agents do not have email addresses. They do not click confirmation links. They do not enter credit cards. PoW + Lightning is the only auth primitive that works for fully autonomous callers.
Managed MCP auth platforms work, but they charge 100–2000 sats per call on vendor infrastructure — your revenue flows through their rails. This package runs on your server, your Lightning node, your keys. You keep the sats.
Configuration
Set CAPTCHA_URL to point at a different captcha backend. Default is http://localhost:3077 so you can run the full stack locally for development. Production deployments point it at https://captcha.powforge.dev.