Como usar o Servidor MCP do CapSolver: Guia de Configuração de Agente de IA

TL;DR

• O servidor MCP do CapSolver expõe cinco ferramentas documentadas: solve_captcha, detect_captchas, solve_on_page, get_balance e get_supported_captchas.
• Instale capsolver-core antes de capsolver-mcp, em seguida, configure um cliente MCP para executar o comando capsolver-mcp com a chave de API em seu ambiente.
• Ferramentas de navegador exigem o extra do navegador e o Chromium; o modo token pode ser executado sem um navegador quando o tipo de CAPTCHA, a URL da página e a chave do site já forem conhecidos.
• Agentes de produção precisam de regras de hosts aprovados, uma tentativa de recuperação limitada, logs redigidos e uma verificação de sucesso no nível da aplicação.

Introdução

A resposta mais segura sobre como usar o servidor MCP do CapSolver é tratar o tratamento de CAPTCHA como uma ferramenta de infraestrutura estreita, e não como uma nova fonte de autoridade para o agente. CapSolver fornece o serviço oficial capsolver-mcp, que encapsula capsolver-core e permite que clientes de IA compatíveis descubram ferramentas de CAPTCHA documentadas. O agente pode, então, recuperar interrupções de reCAPTCHA v2, reCAPTCHA v3 incluindo Enterprise ou Cloudflare Turnstile dentro de um fluxo de trabalho de navegador autorizado. Sua aplicação ainda detém o escopo, credenciais, limites de tentativa e a afirmação final do negócio. Este guia mostra a instalação real e a configuração JSON, explica cada ferramenta e limite de saída e define condições de parada para uso legal, razoável e responsável. Ele não autoriza o acesso a dados privados, restritos, sensíveis ou não autorizados.

Entenda as Três Camadas do CapSolver

Antes de decidir como usar o servidor MCP do CapSolver, separe as camadas do produto. A visão geral do CapSolver para agentes de IA descreve a arquitetura da camada de recuperação. capsolver-core realiza detecção e resolução, capsolver-agent adapta esses métodos em esquemas acessíveis ao agente e capsolver-mcp publica a mesma capacidade via MCP.

A API do SDK core documenta create_capsolver, detect, get_captcha_info, solve e solve_on_page. O adaptador de ferramentas do agente documenta get_all_tools e create_executor. O guia do serviço MCP é a fonte de verdade para instalação, transportes, configuração e as cinco ferramentas MCP.

Escolha o MCP quando o cliente já fala MCP

Use o servidor MCP do CapSolver para clientes como Claude Desktop, Cursor, Cline, VS Code ou outro host compatível. Use capsolver-agent quando você estiver escrevendo o loop de chamada de função por conta própria. Use capsolver-core quando o Playwright ou um serviço possuir o controle total do fluxo e nenhum modelo precise de esquemas de ferramentas. Essa distinção evita adaptadores duplicados e torna mais fácil manter como usar o servidor MCP do CapSolver.

Instale os Pacotes Oficiais

A sequência oficial instala primeiro o motor principal e depois o wrapper MCP:

pip install git+https://github.com/capsolver-ai/capsolver-core.git
pip install git+https://github.com/capsolver-ai/capsolver-mcp.git

Para detecção de navegador e solve_on_page, instale o extra do navegador e o Chromium:

pip install "capsolver-mcp[browser] @ git+https://github.com/capsolver-ai/capsolver-mcp.git"
playwright install chromium

Esses comandos são a entrada verificada sobre como usar o servidor MCP do CapSolver. Uma saída bem-sucedida é um comando executável capsolver-mcp. Pare se a instalação resolver-se a um nome de pacote não oficial, se o comando estiver ausente ou se o Chromium estiver indisponível para uma implantação em modo navegador.

Configure o Cliente MCP

A configuração oficial via stdio é compacta e funciona em muitos clientes MCP locais:

{
  "mcpServers": {
    "capsolver": {
      "command": "capsolver-mcp",
      "env": {
        "CAPSOLVER_API_KEY": "SUA_CHAVE_DE_API"
      }
    }
  }
}

Mantenha a chave real em um gerenciador de segredos ou no ambiente do cliente, em vez de no controle de versão. A entrada é o comando e o ambiente. A saída é um servidor conectado cuja lista de ferramentas pode ser inspecionada. A condição de parada é um lançamento falho, um caminho de executável inesperado ou um registro incompleto. O Especificação de Ferramentas MCP explica por que os clientes devem descobrir e validar os esquemas de ferramentas antes das chamadas.

Verifique os nomes exatos das ferramentas

Após recarregar o cliente, confirme todos os cinco nomes: solve_captcha, detect_captchas, solve_on_page, get_balance e get_supported_captchas. O artigo sobre solucionar erros de CAPTCHA em um servidor MCP fornece um caminho diagnóstico útil, enquanto recuperação de checkpoint do agente MCP explica por que a recuperação deve permanecer limitada.

Resgate seu código promocional do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta do CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Defina Entradas, Saídas e Condições de Parada

No modo token, o agente fornece um tipo de CAPTCHA suportado, a URL da página autorizada e a chave do site pública; solve_captcha retorna uma solução através do resultado da ferramenta MCP. No modo navegador, detect_captchas lista os tipos detectados e solve_on_page realiza detecção documentada, resolução e preenchimento. get_balance relata informações de saldo e get_supported_captchas relata o registro atual.

Não infira sucesso a partir de uma resposta de ferramenta sem erro. A aplicação deve verificar se a rota, o estado do formulário ou a afirmação de teste esperada mudaram na mesma sessão do navegador. Pare de usar o servidor MCP do CapSolver após uma tentativa autônoma, uma mudança no hostname, um segundo checkpoint, autorização expirada, tipo de CAPTCHA não suportado ou estado de página ambíguo.

O guia passo a passo para configuração de CAPTCHA MCP ajuda a conectar a configuração à descoberta real de ferramentas. Para comportamento específico de reCAPTCHA no MCP, o exemplo de reCAPTCHA v2 do Cursor mostra como uma integração de cliente estreita difere de uma implantação de servidor geral.

Adicione Barreiras de Produção

Uma implementação de produção de como usar o servidor MCP do CapSolver deve permitir apenas hosts aprovados e ações declaradas. Mantenha cookies e credenciais fora das mensagens do modelo. Registre identificadores de solicitação, nomes de ferramentas, estados terminais e códigos de erro redigidos, em vez de tokens brutos. O guia de registro da OWASP apoia o design de eventos conscientes de privacidade, e o Quadro de Gestão de Risco de IA da NIST apoia controles responsáveis.

Teste chaves ausentes, dependências de navegador ausentes, descoberta incompleta de ferramentas, tipos não suportados, estado de página inalterado e desafios repetidos. Cada caso negativo deve retornar um estado de revisão terminal, em vez de outra chamada autônoma.

Conclusão

O método prático para usar o servidor MCP do CapSolver é simples: instale capsolver-core e capsolver-mcp, configure o comando oficial, verifique todas as cinco ferramentas e coloque uma porta de autorização rigorosa diante de cada chamada. Trate o sucesso da aplicação como o resultado e a conclusão da ferramenta como evidência. Equipes que operam fluxos de trabalho de agente de IA permitidos podem avaliar o CapSolver como a camada de infraestrutura de CAPTCHA.

Perguntas Frequentes

O servidor MCP do CapSolver suporta todos os tipos de tarefa do CapSolver para agentes?

Não. A documentação atual de agentes de IA limita essa camada a reCAPTCHA v2, reCAPTCHA v3 incluindo Enterprise e Cloudflare Turnstile. Verifique get_supported_captchas em tempo de execução.

Qual comando um cliente MCP deve executar?

Use o executável oficial capsolver-mcp, ou execute o módulo instalado com o Python do ambiente quando o executável não estiver no PATH do cliente.

Quando o uso do servidor MCP do CapSolver requer o Playwright?

A detecção de navegador e solve_on_page exigem o extra do navegador e o Chromium. O modo token não exige um navegador quando os parâmetros da página já forem conhecidos.

O que deve parar um agente de IA após uma chamada de CAPTCHA?

Pare em caso de mudança de escopo, tipo não suportado, contexto de navegador ausente, desafio repetido, autorização expirada ou estado da aplicação inalterado após uma tentativa.