This server (@powforge/captcha-mcp) adds machine-readable, account-free rate limiting and access control to MCP endpoints using proof-of-work and Lightning (L402) payments instead of 429 errors. You can:
Request a PoW challenge (challenge): get an id, salt, difficulty, and signature, then solve an SHA-256 puzzle with required leading zero bits (~5–10s CPU).
Verify a PoW solution (verify): submit the solved nonce with challenge fields to receive a 5-minute HMAC-signed access token; optional algo/difficulty overrides are supported, and tokens can be independently verified via POST https://captcha.powforge.dev/api/token/verify.
Check server status (status): retrieve health, lifetime stats (pow_solves, ln_skips, challenges_issued), and L402 metadata (scope, 3-sat price, paid endpoint) to discover the Lightning skip option.
Run anywhere: operates over stdio or HTTP/SSE (/mcp, /health), supports self-hosting, requires no accounts or API keys, and offers a free tier plus a paid 3-sat Lightning bypass.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@powforge/captcha-mcp request a challenge to access the API"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: @bitcoinbenji/mcp
npx -y @powforge/captcha-mcpNo 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:
{
"mcpServers": {
"powforge-captcha": {
"command": "npx",
"args": ["-y", "@powforge/captcha-mcp"]
}
}
}Or run npx @powforge/captcha-mcp --install to print the config block.
Wraps the PowForge pow-captcha service (captcha.powforge.dev) as three MCP tools:
Tool | Purpose |
| Request a fresh proof-of-work puzzle. Returns |
| Submit a solved nonce. Returns a 5-minute HMAC-signed access token. |
| 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).
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.
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.
CAPTCHA_URL=https://captcha.powforge.dev npx @powforge/captcha-mcpHosted MCP clients (Smithery, browser-based hosts) need HTTP, not stdio. Pass --http or set HTTP_MODE=1:
HTTP_MODE=1 PORT=3200 npx @powforge/captcha-mcp
# or
npx @powforge/captcha-mcp --httpThe server then listens on:
Endpoint | Method | Purpose |
| POST | Single JSON-RPC request, single JSON-RPC response. Notifications return 202. |
| GET | SSE stream for server-pushed notifications (kept open with a 25s heartbeat). |
| GET | Liveness probe — returns |
Stateless. No session ids. CORS open (Access-Control-Allow-Origin: *) so browser clients work. Stdio mode is unchanged and remains the default — npx @powforge/captcha-mcp with no flag still talks JSON-RPC over stdin/stdout.
Smoke test the HTTP transport:
HTTP_MODE=1 PORT=3200 node src/server.js &
curl -X POST http://localhost:3200/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'Returns {jsonrpc:"2.0", id:1, result:{protocolVersion:"2024-11-05", capabilities:{tools:{}}, serverInfo:{...}}}.
Clone the captcha widget repo or run the public service. The MCP server only needs HTTP access to the captcha endpoints listed under status.
git clone https://github.com/zekebuilds-lab/captcha-mcp
cd captcha-mcp
node src/server.jsIt prints ready to stderr and waits for JSON-RPC on stdin.
Smoke-test the protocol manually:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' | node src/server.jsYou should see a JSON response with serverInfo: { name: "@powforge/captcha-mcp", version: "0.2.5" }.
When an agent submits a token to your service, verify it without trusting the agent:
curl -X POST https://captcha.powforge.dev/api/token/verify \
-H "Content-Type: application/json" \
-d '{"token":"<token-from-verify-tool>"}'Returns {valid: true, method, issued_at, expires_at} or {valid: false, reason}.
@powforge/captcha — the browser widget for the same service.
@powforge/mcp-l402-gate — Express middleware to gate any MCP server with L402 + Depth-of-Identity scoring.
@powforge/mcp-identity — agent reputation oracle. Pair with this gate for first-call abuse protection.
The gate-the-MCP-server space is filling up. Here is the honest landscape, ranked by how directly each tool overlaps with what captcha-mcp does.
Tool | Payment rail | Auth model | Self-host | Free PoW tier | No account to pay |
PayGated | Stripe credits | API key + OAuth 2.1 + PKCE + M2M | yes (MIT) | no | no (Stripe customer record per caller) |
APort | none disclosed | W3C verifiable creds, pre-tool hook | design-partner | no | n/a (audits, does not charge) |
AgentSign | none disclosed | Ed25519 signed passport + trust gate | unknown | no | n/a |
x402-mcp | USDC on-chain | wallet signature | yes | no | no (needs funded wallet) |
Managed MCP auth (Auth0 for AI, MintMCP) | SaaS | OAuth 2.0 / SAML / SSO | no | no | no |
captcha-mcp (this) | Lightning (L402) | PoW gate + L402 skip + free-tier | yes | yes | yes |
PayGated is the closest collision. Same "monetize MCP tools per call" pitch, same self-host + open-source posture, but it settles on Stripe. That means you need a Stripe account in good standing (KYC, a bank, a supported country) to collect, and every caller needs a Stripe customer record before it can pay you a cent. captcha-mcp's differentiator is the no-account path: a non-US agent author pays 3 sats per call in about 200ms with no KYC, or solves a free PoW puzzle if it will not pay at all.
APort and AgentSign sit at a different layer. They record who used a tool under what authority; they do not price the call. They compose with a gate like this one rather than replace it.
None of them price the act of interacting. Every other row assumes the caller is already an authorized identity and meters or audits after that. The PoW tier here is the only mechanism in the table that puts a cost on the interaction itself, not on the identity of the actor. That is the position this package defends.
A longer breakdown against x402-mcp, @agentauth/mcp, and Cloudflare ARC/ACT is at powforge.dev/mcp/compare/x402-mcp.
MIT
Request a fresh PoW challenge from the PowForge captcha service. Returns {id, salt, difficulty, signature, instructions}. The agent must find a nonce such that SHA-256(salt + nonce) has at least difficulty leading zero bits, then call the verify tool. Free tier — no payment required.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the tool creates a new challenge (non-idempotent), returns specific fields, requires a subsequent PoW solution, and mentions free tier. Lacks rate limit info but is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences concisely cover purpose, return structure, workflow, and free tier. No redundancies or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no input schema and no output schema, so the description fully covers both: explains that no input is needed and details the returned object fields along with subsequent steps. Sufficient for a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No input parameters exist, so schema coverage is 100%. The description adds value by explaining the return structure, which is not parameter semantics but compensates for missing output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Request' and resource 'fresh PoW challenge from PowForge captcha service', and distinguishes from sibling 'verify' by mentioning the complete workflow including the call to verify.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (requesting a captcha challenge) and what to do next (find nonce, call verify), but does not explicitly contrast with 'status' or provide when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return PowForge captcha server health, lifetime stats (pow_solves, ln_skips, challenges_issued), and L402 endpoint metadata (scope, price_sats, paid endpoint URL). Use this to discover the Lightning skip price before paying, or as a liveness check.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and adequately lists the return data: health, lifetime stats, and L402 metadata. It implies a read-only operation but could explicitly state no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that is front-loaded with the main purpose. It could be split into two sentences for readability, but it is efficient and contains no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description explains the return values and use cases adequately. It does not specify response format or error handling, but for a health endpoint, the provided information is sufficient for tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100% (vacuously). Baseline for zero parameters is 4, and the description adds value by detailing the output fields beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns health, lifetime stats, and L402 endpoint metadata. It distinguishes itself from siblings 'challenge' and 'verify' by specifying use cases like discovering the Lightning skip price and liveness check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides two use cases: discovering the Lightning skip price before paying and as a liveness check. It gives clear context for when to use the tool, though it does not mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a PoW solution. Input: {salt, nonce, id, signature, algo?, difficulty?} from a prior challenge call plus the nonce the agent computed. Returns a 5-minute HMAC-signed token on success, or {valid: false, reason} on failure. Tokens can be re-verified server-side via POST /api/token/verify.
| Name | Required | Description | Default |
|---|---|---|---|
| salt | Yes | Hex salt from the challenge response | |
| nonce | Yes | Nonce string the agent computed | |
| id | Yes | Challenge id from the challenge response | |
| signature | Yes | HMAC signature from the challenge response | |
| algo | No | Hash algorithm. Default: 'sha256' | |
| difficulty | No | Leading zero bits required. Default: matches challenge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It explains the return value: a 5-minute HMAC-signed token on success or an error object on failure. It also mentions server-side re-verification. However, it does not cover potential side effects or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three concise sentences: the first states the purpose, the second details input/output, and the third mentions server-side capabilities. It is front-loaded and free of superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains return values (success token with lifetime, failure reason). It references the sibling 'challenge' and describes the token's re-verification endpoint. However, it lacks detail on possible failure reasons or error codes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds valuable context by listing parameters and stating they come from a prior challenge call, plus the agent-computed nonce. This clarifies the origin and usage beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Verify a PoW solution,' using a specific verb and resource. It clearly distinguishes from sibling tools like 'challenge' by describing input from a prior challenge call and the verification purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates that input comes 'from a prior challenge call,' implying a sequence (call challenge first, then verify). It does not explicitly state when not to use it or contrast with alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0challengestatusverifyScored across 3 tools
Each tool has a distinct purpose: challenge initiates a PoW challenge, status checks server health and metadata, and verify submits the solution. No overlap in functionality.
All tool names are single-word imperative verbs (challenge, status, verify), following a consistent naming pattern.
Three tools are appropriate for a captcha service, covering the core workflow (challenge, verify) and a status check. Not excessive or insufficient.
The core PoW challenge-verify cycle is complete. However, the status tool mentions a Lightning skip option, but no tool to execute it, which is a minor gap.
Hosted MCP server for AI agent identity, permissions, verification, and reusable proof.
Pay-per-action access to APIs and MCP tools over Lightning L402 and Base USDC x402.
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.
Hosted MCP server for live public-data APIs and Skills for AI agents.