captcha-mcp
Paywall L402 Lightning e gate PoW para chamadas de ferramentas MCP. Nível gratuito resolve um desafio Hashcash; nível pago paga uma fatura Lightning via LNBits auto-hospedado. Sem contas, sem chaves de API.
Documentação
@powforge/captcha-mcp
Seu servidor MCP retorna 429 quando agentes o sobrecarregam. captcha-mcp faz com que eles ganhem a próxima chamada. Entregue ao agente um quebra-cabeça de prova de trabalho (gratuito, ~5s de CPU) ou uma fatura Lightning de 3 sats — ambos são sinais de backoff legíveis por máquina que um chamador autônomo pode satisfazer sem conta, e-mail ou chave de API.
Três ferramentas via stdio ou HTTP. Apenas stdlib. Sem cadastro, fallback gratuito, auto-hospedado, sem divisão de receita.
Por que não 429?
429 Too Many Requests é o formato errado para a era dos agentes. Três padrões se repetem nos relatórios de servidores MCP:
- Frameworks de agentes tratam 429 como falha de conexão. Eles tentam novamente imediatamente, muitas vezes com backoff exponencial que ainda é agressivo demais, e amplificam a sobrecarga que disparou o limite em primeiro lugar.
- Não há sinal por chamador. Um 429 dispara para o bucket, não para o agente. Um chamador ruidoso faz todos os outros serem limitados, e o servidor não tem como pedir especificamente ao ruidoso para desacelerar.
- Retry-After é apenas uma recomendação e frequentemente ignorado. Agentes não o analisam de forma consistente, não o respeitam de forma consistente e não têm incentivo para esperar — o custo de tentar novamente é zero.
captcha-mcp substitui o 429 por um desafio estilo 402. A próxima chamada custa algo ao chamador (segundos de CPU ou 3 sats). Esse custo é por chamador, legível por máquina e auto-limitante — um agente que não consegue resolver o quebra-cabeça não consegue inundar o endpoint.
Início rápido
npx -y @powforge/captcha-mcp
Sem instalação, sem configuração, sem chave de API. O servidor inicia no stdio e aguarda um cliente MCP.
Para conectá-lo ao Claude Code, Cursor ou qualquer host compatível com MCP, adicione à sua configuração:
{
"mcpServers": {
"powforge-captcha": {
"command": "npx",
"args": ["-y", "@powforge/captcha-mcp"]
}
}
}
Ou execute npx @powforge/captcha-mcp --install para imprimir o bloco de configuração.
O que faz
Encapsula o serviço PowForge pow-captcha (captcha.powforge.dev) como três ferramentas MCP:
| Ferramenta | Propósito |
|---|---|
challenge | Solicita um novo quebra-cabeça de prova de trabalho. Retorna {id, salt, difficulty, signature}. |
verify | Envia um nonce resolvido. Retorna um token de acesso assinado com HMAC de 5 minutos. |
status | Saúde do servidor, estatísticas de tempo de vida, metadados do endpoint L402. |
O nível gratuito custa ao agente ~5-10 segundos de tempo de CPU (SHA-256, padrão de 14 bits zero iniciais). O nível pago custa 3 sats via Lightning através de L402 (RFC 7235 + fatura bolt11 em WWW-Authenticate).
Por que isso e não OAuth, chaves de API ou Stripe
| Abordagem | Custo por chamada | Conta necessária | Auto-hospedado | Amigável a agentes |
|---|---|---|---|---|
| Chaves de API | $0 | sim | n/a | não |
| OAuth | $0 | sim | n/a | não |
| Medição Stripe | alto overhead | sim | n/a | não |
| Plataforma de auth MCP gerenciada | 100–2000 sats | não | não | sim |
| PoW + L402 (este) | segundos ou 3 sats | não | sim | sim |
Agentes não têm endereços de e-mail. Eles não clicam em links de confirmação. Eles não inserem cartões de crédito. PoW + Lightning é o único primitivo de autenticação que funciona para chamadores totalmente autônomos.
Plataformas de auth MCP gerenciadas funcionam, mas cobram 100–2000 sats por chamada na infraestrutura do fornecedor — sua receita flui pelos trilhos deles. Este pacote roda no seu servidor, no seu nó Lightning, nas suas chaves. Você fica com os sats.
Configuração
Defina CAPTCHA_URL para apontar para um backend de captcha diferente. O padrão é http://localhost:3077 para que você possa executar toda a pilha localmente para desenvolvimento. Implantações de produção apontam para https://captcha.powforge.dev.
CAPTCHA_URL=https://captcha.powforge.dev npx @powforge/captcha-mcp
Transporte HTTP Streamable
Clientes MCP hospedados (Smithery, hosts baseados em navegador) precisam de HTTP, não stdio. Passe --http ou defina HTTP_MODE=1:
HTTP_MODE=1 PORT=3200 npx @powforge/captcha-mcp
# or
npx @powforge/captcha-mcp --http
O servidor então escuta em:
| Endpoint | Método | Propósito |
|---|---|---|
/mcp | POST | Requisição JSON-RPC única, resposta JSON-RPC única. Notificações retornam 202. |
/mcp | GET | Stream SSE para notificações enviadas pelo servidor (mantido aberto com heartbeat de 25s). |
/health | GET | Sonda de liveness — retorna {ok, server, transport}. Não faz parte do MCP. |
Sem estado. Sem ids de sessão. CORS aberto (Access-Control-Allow-Origin: *) para que clientes de navegador funcionem. O modo stdio permanece inalterado e é o padrão — npx @powforge/captcha-mcp sem flag ainda fala JSON-RPC via stdin/stdout.
Teste rápido do transporte HTTP:
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"}}}'
Retorna {jsonrpc:"2.0", id:1, result:{protocolVersion:"2024-11-05", capabilities:{tools:{}}, serverInfo:{...}}}.
Desenvolvimento local
Clone o repositório do widget de captcha ou execute o serviço público. O servidor MCP só precisa de acesso HTTP aos endpoints de captcha listados em status.
git clone https://github.com/zekebuilds-lab/captcha-mcp
cd captcha-mcp
node src/server.js
Ele imprime ready no stderr e aguarda JSON-RPC no stdin.
Teste o protocolo manualmente:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' | node src/server.js
Você deve ver uma resposta JSON com serverInfo: { name: "@powforge/captcha-mcp", version: "0.2.5" }.
Verificação de token a partir do seu próprio backend
Quando um agente envia um token ao seu serviço, verifique-o sem confiar no agente:
curl -X POST https://captcha.powforge.dev/api/token/verify \
-H "Content-Type: application/json" \
-d '{"token":"<token-from-verify-tool>"}'
Retorna {valid: true, method, issued_at, expires_at} ou {valid: false, reason}.
Pacotes relacionados
@powforge/captcha— o widget de navegador para o mesmo serviço.@powforge/mcp-l402-gate— middleware Express para proteger qualquer servidor MCP com L402 + pontuação Depth-of-Identity.@powforge/mcp-identity— oráculo de reputação de agentes. Combine com este gate para proteção contra abuso na primeira chamada.
Como isso se compara a outros primitivos de auth de agentes MCP
O espaço de proteger servidores MCP está se preenchendo. Aqui está o panorama honesto, classificado por quão diretamente cada ferramenta se sobrepõe ao que captcha-mcp faz.
| Ferramenta | Trilho de pagamento | Modelo de auth | Auto-hospedado | Nível PoW gratuito | Sem conta para pagar |
|---|---|---|---|---|---|
| PayGated | Créditos Stripe | Chave de API + OAuth 2.1 + PKCE + M2M | sim (MIT) | não | não (registro de cliente Stripe por chamador) |
| APort | nenhum divulgado | Credenciais verificáveis W3C, hook pré-ferramenta | parceiro de design | não | n/a (auditorias, não cobra) |
| AgentSign | nenhum divulgado | Passaporte assinado Ed25519 + gate de confiança | desconhecido | não | n/a |
| x402-mcp | USDC on-chain | assinatura de carteira | sim | não | não (precisa de carteira financiada) |
| Auth MCP gerenciado (Auth0 para IA, MintMCP) | SaaS | OAuth 2.0 / SAML / SSO | não | não | não |
| captcha-mcp (este) | Lightning (L402) | Gate PoW + skip L402 + nível gratuito | sim | sim | sim |
PayGated é a colisão mais próxima. Mesma proposta de "monetizar ferramentas MCP por chamada", mesma postura de auto-hospedado + código aberto, mas ele usa Stripe. Isso significa que você precisa de uma conta Stripe em situação regular (KYC, um banco, um país suportado) para receber, e todo chamador precisa de um registro de cliente Stripe antes de poder pagar um centavo. O diferencial de captcha-mcp é o caminho sem conta: um autor agente não-americano paga 3 sats por chamada em cerca de 200ms sem KYC, ou resolve um quebra-cabeça PoW gratuito se não quiser pagar nada.
APort e AgentSign estão em uma camada diferente. Eles registram quem usou uma ferramenta sob qual autoridade; eles não precificam a chamada. Eles se compõem com um gate como este em vez de substituí-lo.
Nenhum deles precifica o ato de interagir. Cada outra linha assume que o chamador já é uma identidade autorizada e mede ou audita depois disso. O nível PoW aqui é o único mecanismo na tabela que coloca um custo na interação em si, não na identidade do ator. Essa é a posição que este pacote defende.
Uma análise mais detalhada contra x402-mcp, @agentauth/mcp e Cloudflare ARC/ACT está em powforge.dev/mcp/compare/x402-mcp.
Licença
MIT