[ AGENTES ]

Resolução de captcha para
agentes MCP

Um agente que encontra um desafio não tem nada no seu conjunto de ferramentas que consiga respondê-lo, então ele trava ou alucina para contorná-lo. Dê a ele um solucionador como ferramenta e o bloqueio vira só mais uma chamada.

open-source MCP server · npx -y captchano-mcp

# Claude Code
claude mcp add captchano -e CAPTCHANO_API_KEY=cn-YOUR_API_KEY -- npx -y captchano-mcp

# Claude Desktop / Cursor / VS Code (mcpServers config)
{
  "mcpServers": {
    "captchano": {
      "command": "npx",
      "args": ["-y", "captchano-mcp"],
      "env": {
        "CAPTCHANO_API_KEY": "cn-YOUR_API_KEY",
        "CAPTCHANO_MAX_SPEND_USD": "1"
      }
    }
  }
}

# Tools: solve_captcha · get_task · get_balance · list_captcha_types
# Source (MIT): https://github.com/DishantSinghDev2/captchano-mcp

Por que agentes precisam especificamente disso

Um scraper que encontra um desafio falha de forma evidente e você corrige. Um agente falha em silêncio: ele raciocina sobre a página bloqueada, inventa um próximo passo plausível e relata um progresso que nunca fez. A falha é pior porque é silenciosa. Uma ferramenta de resolução tipada transforma um beco sem saída ambíguo em um resultado determinístico a partir do qual o agente pode decidir.

O que a ferramenta retorna

Um token ou cookie — dependendo do tipo de desafio. Sistemas avaliados por sessão retornam um cookie e o conjunto de headers usado para obtê-lo.
O user agent usado, para que o agente possa reutilizá-lo no envio.
O custo da resolução, para que um agente que opera com orçamento possa contabilizá-lo em vez de gastar às cegas.

Mantendo o loop sob controle

Dê ao agente um orçamento de resoluções por execução. Toda resposta informa o seu custo, então um supervisor pode cortar o loop quando o gasto passar de um limite, em vez de descobrir isso na fatura. A $0.00598 por resolução, uma execução típica de agente custa alguns centavos ou menos, mas um loop de novas tentativas sem limite continua sendo um loop sem limite.

Mantenha a chamada da ferramenta bloqueante

Os exemplos chamam ?wait=60, então a ferramenta retorna um token pronto em uma única etapa. Isso importa mais para agentes do que para scripts: uma ferramenta que retorna "ainda resolvendo" obriga o modelo a raciocinar sobre polling, algo que ele faz mal. Se você precisar de um teto maior, aumente wait para até 120 segundos. Os formatos de requisição de cada tipo de desafio estão na referência da API.

[ COMO SE ENCAIXA ]

Como a resolução se encaixa no MCP

O captchano-mcp é o nosso servidor MCP open source: ele expõe a resolução como ferramentas que qualquer cliente MCP pode chamar, então o agente resolve um captcha com uma única chamada de ferramenta e recebe um token de volta.

01
Adicione o servidor
Claude Code: claude mcp add captchano -e CAPTCHANO_API_KEY=cn-… -- npx -y captchano-mcp. Outros clientes usam o mesmo comando npx na configuração MCP.
02
Defina um orçamento
Opcionalmente, defina CAPTCHANO_MAX_SPEND_USD para que o servidor recuse novas resoluções quando a sessão tiver gasto esse valor.
03
Deixe o modelo chamá-lo
Quando o agente encontra um desafio, ele chama solve_captcha com o type, a sitekey e a URL; list_captcha_types informa quais campos cada tipo exige.
04
Use o token
O agente passa o token para a ferramenta de navegador injetar e enviar. Resoluções longas retornam um task id para consultar com get_task.

Colocando o token na página

O cliente recebe o token como resultado da ferramenta e o repassa para a ferramenta de navegador que preenche a página.

[ ARMADILHAS ]

Onde as integrações costumam dar errado

Chave no prompt

Mantenha a chave de API no ambiente do servidor, nunca nos argumentos da ferramenta, para que o modelo nunca a veja.

Ferramenta não bloqueante

Mantenha wait=60 para que a ferramenta retorne um token pronto em vez de pedir ao modelo que faça polling.

[ FAQ ]

Perguntas frequentes sobre captcha no MCP

Existe um pacote MCP oficial da CaptchaNo?

Sim. O captchano-mcp é o nosso servidor open source (MIT), disponível no npm e no MCP Registry oficial. Execute-o com npx -y captchano-mcp e sua chave em CAPTCHANO_API_KEY; a chave fica na sua máquina e nunca é um argumento de ferramenta.

Com quais clientes MCP ele funciona?

Com qualquer cliente que suporte ferramentas MCP via stdio ou HTTP, já que o servidor expõe apenas uma ferramenta padrão.

Como o agente encontra a sitekey?

Pela ferramenta de navegador: ele lê o atributo data-sitekey ou a URL da página de desafio e a passa para a ferramenta de resolução.

Posso limitar quanto o agente gasta?

Sim. Todo resultado inclui o custo, então o servidor pode manter um total acumulado e recusar novas resoluções acima de um orçamento.

[ LEIA A SEGUIR ]