Pular para o conteúdo principal
Está tendo problemas para obter o token?
Entre em contato com o suporte

MCP

O Model Context Protocol (MCP) permite que agentes de IA se conectem a ferramentas e serviços externos.

O MCP do CapMonster Cloud fornece ao agente ferramentas para trabalhar com CAPTCHA.

Como funciona o MCP do CapMonster Cloud

Com o MCP, um agente de IA pode identificar o tipo de CAPTCHA e os parâmetros da tarefa, acessar a documentação do CapMonster Cloud, criar tarefas e obter os resultados da solução. O objetivo final do agente não é apenas resolver o CAPTCHA, mas também integrar corretamente esse processo ao projeto do usuário.

Para trabalhar com uma página da Web, o MCP do CapMonster Cloud pode ser usado junto com o MCP de navegador capmonster-mcp-patchright:

Agente de IA
├── capmonster → API do CapMonster Cloud
└── patchright → navegador

O capmonster é responsável pela interação com o CapMonster Cloud. O patchright abre a página, ajuda a identificar o tipo de CAPTCHA e obter seus parâmetros, além de aplicar a solução pronta. Em seguida, o agente transfere o fluxo validado para o código do projeto.

Fluxo típico coberto pelo SKILL.md:

  1. Obter a URL da página de destino.

  2. Identificar o tipo de CAPTCHA.

  3. Consultar a documentação e determinar os parâmetros obrigatórios.

  4. Obter os parâmetros da página.

  5. Enviar uma solicitação ao CapMonster Cloud.

  6. Obter o resultado.

  7. Aplicar o resultado na página e integrar esse fluxo ao código do usuário.

Observação

Use automação somente em recursos nos quais você tenha autorização para isso, por exemplo, em seu próprio site, em um ambiente de teste ou em uma página de demonstração.

Início rápido​

Copie o prompt para o agente de IA

Escolha o prompt de acordo com o seu ambiente — Python / PyPI ou TypeScript / npm — e clique em Copiar prompt. Em seguida, cole-o no Claude Code, Codex ou em outro agente de IA. O agente identificará o cliente e o sistema operacional, configurará capmonster e patchright e verificará se eles funcionam.

Se a configuração automática falhar, configure o MCP manualmente seguindo as instruções.

Após a verificação, forneça ao agente a URL da página de destino, os arquivos do projeto e as condições em que o CAPTCHA aparece. O agente deve não apenas verificar a solução no navegador, mas também integrar o fluxo funcional do CapMonster Cloud ao seu código.

Permissões durante a configuração

O agente pode solicitar permissão para instalar dependências, alterar a configuração do MCP, executar comandos, acessar a rede ou controlar o navegador. Revise cada solicitação e confirme as ações esperadas clicando em Allow ou Approve.

No Codex, você pode verificar ou alterar o modo de permissões atual com o comando /permissions.

Não é necessário reenviar o prompt antes de cada tarefa. Na sessão atual, depois que o SKILL.md for carregado, você pode fornecer novas URLs, condições de exibição do CAPTCHA e tarefas de integração.

Configuração manual​

Você pode trabalhar com o agente por meio de um aplicativo Desktop, terminal, IDE ou editor de código. Para o fluxo completo, recomendamos conectar os dois servidores: capmonster e patchright.

Escolha como deseja trabalhar — com um agente CLI ou um aplicativo Desktop. Cada aba contém a sequência completa de configuração para a opção selecionada.

Etapa 1. Instale um agente de IA


Você precisa de um agente de IA ou outro aplicativo compatível com MCP.

Se o agente já estiver instalado, verifique se ele inicia corretamente e está disponível no sistema.

Por exemplo, para o Claude Code:

claude --version

Para o Codex:

codex --version

Se o comando não for encontrado, instale o agente de IA escolhido de acordo com a documentação oficial: Claude Code ou Codex.

Após a instalação, verifique se o agente inicia corretamente e é compatível com servidores MCP locais.

Agente não encontrado após a instalação

Se o terminal ou a IDE não encontrar o agente instalado, feche completamente e abra novamente o terminal e o ambiente de desenvolvimento. Aplicativos que já estavam em execução podem continuar usando o valor antigo de PATH e não reconhecer o novo comando até serem reiniciados.

Etapa 2. Instale o Node.js e, se necessário, o uv


Para executar os servidores MCP, você precisa do npx e, dependendo da implementação escolhida do CapMonster MCP, do uvx.

Node.js e npx

Importante:

O patchright é executado por meio do npx, portanto o Node.js é obrigatório independentemente da implementação do CapMonster MCP escolhida.

Verifique a instalação:

node --version
npm --version
npx --version

Se os comandos não estiverem disponíveis, instale o Node.js.

O npm e o npx normalmente são instalados junto com o Node.js, portanto não é necessário instalar o npx separadamente.

Recomendamos usar o Node.js 18 ou posterior.

uv e uvx

Se você pretende usar a versão Python/PyPI do capmonster-mcp, também precisará do uvx.

Verifique se ele está disponível:

uvx --version

Se o comando não estiver disponível, instale o uv.

Depois de instalar o uv, o comando uvx também ficará disponível.

Verifique:

uv --version
uvx --version
Observação

Se você usar a versão TypeScript/npm do capmonster-mcp, não será necessário instalar uv nem uvx.

Etapa 3. Obtenha uma chave de API


O capmonster requer uma chave de API do CapMonster Cloud.

Ela é passada ao servidor MCP por meio da seguinte variável de ambiente:

CM_API_KEY
Etapa 4. Escolha uma implementação do CapMonster MCP


Há duas implementações equivalentes do capmonster-mcp.

Esta versão usa o pacote npm capmonster-mcp e o npx.

Execute o servidor MCP com:

npx -y capmonster-mcp

Não é necessário instalar o capmonster-mcp como dependência do seu projeto. Por padrão, o cliente MCP pode executar o pacote publicado diretamente por meio do npx ou uvx.

Instalação de pacotes com npm e pip


Por padrão, não é necessário pré-instalar os pacotes MCP: você pode executá-los diretamente com npx ou uvx. Se quiser instalar os pacotes antecipadamente, use uma das opções abaixo.

CapMonster Cloud MCP

Instale o capmonster-mcp com npm:

npm i capmonster-mcp

Você pode verificar a instalação com:

npm list capmonster-mcp

Após a instalação, use npx para executar o capmonster:

{
  "command": "npx",
  "args": ["capmonster-mcp"],
  "env": {
    "CM_API_KEY": "YOUR_API_KEY"
  }
}

Patchright MCP

Se você pretende usar um navegador para abrir páginas, obter parâmetros de CAPTCHA e aplicar soluções, instale o capmonster-mcp-patchright. O código-fonte está disponível no repositório oficial:

npm i capmonster-mcp-patchright

Você pode verificar a instalação com:

npm list capmonster-mcp-patchright

A pré-instalação do capmonster-mcp-patchright é opcional. Em todos os exemplos abaixo, você também pode executá-lo diretamente com:

npx -y capmonster-mcp-patchright

Após instalar o pacote npm ou Python, reinicie completamente o cliente MCP se o pacote tiver sido instalado depois que o cliente já estava em execução.


Etapa 5. Configure o cliente MCP


Selecione o cliente CLI que você usa.

Para uma configuração compartilhada do projeto, crie um arquivo .mcp.json na raiz do projeto e adicione capmonster e patchright a ele.

dica

Esse não é o único local possível. O Claude Code oferece suporte a diferentes escopos de configuração; configurações específicas do usuário ou do projeto também podem ser armazenadas em .claude.json ou adicionadas com comandos do Claude Code. Se um agente estiver configurando o MCP, permita que ele determine automaticamente o escopo e o arquivo adequados.

{
  "mcpServers": {
    "capmonster": {
      "command": "npx",
      "args": ["-y", "capmonster-mcp"],
      "env": {
        "CM_API_KEY": "YOUR_API_KEY"
      }
    },
    "patchright": {
      "command": "npx",
      "args": ["-y", "capmonster-mcp-patchright"]
    }
  }
}

Após reiniciar o Claude Code, verifique a conexão com o comando /mcp.

Substitua YOUR_API_KEY pela sua chave de API do CapMonster Cloud e reinicie o cliente MCP.

Etapa 6. Envie o prompt ao agente


Abra um novo chat ou uma nova sessão e envie o prompt da seção Início rápido. Após a verificação, forneça a URL da página, os arquivos do projeto e as condições em que o CAPTCHA aparece.

Durante a configuração, aprove apenas as solicitações de permissão esperadas. Não é necessário reenviar o prompt antes de cada tarefa na sessão atual.

Ferramentas disponíveis​

Depois que os servidores MCP forem conectados, as ferramentas ficarão automaticamente disponíveis para o agente de IA. Normalmente, não é necessário selecioná-las manualmente — o agente chama as ferramentas adequadas conforme a tarefa atual.

CapMonster Cloud​

O capmonster-mcp fornece as seguintes ferramentas:

  • get_supported_tasks — retorna os tipos de tarefa compatíveis com o CapMonster Cloud;
  • get_task_parameters(task_type) — retorna os parâmetros do tipo de tarefa selecionado e o esquema da solução;
  • get_docs(url, offset, limit, section) — carrega a documentação do CapMonster Cloud;
  • create_task(task) — cria uma tarefa e retorna o taskId;
  • get_task_result(task_id) — verifica o status da tarefa uma vez;
  • get_task_result_wait(task_id, timeout_seconds, poll_interval_seconds) — aguarda automaticamente a conclusão da tarefa;
  • get_actual_user_agent() — retorna o User-Agent atual do Windows;
  • get_balance() — retorna o saldo da conta do CapMonster Cloud.

Patchright​

O capmonster-mcp-patchright fornece ferramentas para interação com o navegador. O agente acessa essas ferramentas por meio do cliente MCP e seleciona automaticamente as ações necessárias.

A lista atual de ferramentas está disponível no repositório oficial e na página do pacote npm capmonster-mcp-patchright.

Solução de problemas​

Deixe o agente diagnosticar o problema

Se a configuração não funcionar, envie a mensagem de erro ao agente. Ele pode verificar o runtime, os comandos de inicialização, as configurações MCP do usuário e do projeto e sugerir ou aplicar as correções necessárias.

O servidor MCP não inicia

Verifique se o comando da configuração está disponível no mesmo ambiente em que o cliente MCP está sendo executado:

node --version
npx --version
npx -y capmonster-mcp

Se o comando iniciar e não produzir nenhuma saída, isso não significa necessariamente que há um erro: o servidor MCP STDIO está aguardando a conexão de um cliente. Você pode interromper a execução de teste com Ctrl+C.

Verifique também se:

  • a configuração JSON não contém comentários, vírgulas finais ou colchetes/chaves não fechados;

  • os nomes dos campos mcpServers, command, args e env estão escritos corretamente;

  • o cliente MCP foi reiniciado completamente após a alteração da configuração;

  • o download de pacotes por npx ou uvx não está sendo bloqueado pela rede, proxy, antivírus ou política corporativa.

O comando capmonster-mcp não é encontrado após a instalação do pacote

Um comando CLI pré-instalado deve estar disponível no PATH do processo que inicia o cliente MCP.

Verifique a localização do comando:

where.exe capmonster-mcp

Se o terminal encontrar o comando, mas o aplicativo Desktop não, feche completamente e abra o aplicativo novamente. Se necessário, informe o caminho completo para o executável no campo command.

As ferramentas capmonster ou patchright não são exibidas

Peça ao agente para verificar de onde a sessão atual carrega a configuração MCP. O local depende do cliente, do escopo da configuração e da forma como o servidor foi conectado:

  • no Claude Code, os servidores podem ser configurados no nível do projeto ou do usuário; a configuração pode ser armazenada em .mcp.json, .claude.json ou gerenciada por comandos do Claude Code;

  • o Claude Desktop usa claude_desktop_config.json;

  • o Codex usa ~/.codex/config.toml, %USERPROFILE%\.codex\config.toml ou um .codex/config.toml no nível do projeto;

  • no ChatGPT Desktop, os servidores locais também podem ser adicionados pelas configurações de MCP.

Após corrigir a configuração, reinicie completamente o cliente e abra uma nova sessão. No Claude Code, você pode verificar a conexão com /mcp; no Codex, use /mcp ou codex mcp list.

get_balance retorna um erro

Peça ao agente para verificar a configuração do capmonster. Normalmente, é necessário garantir que:

  • a variável CM_API_KEY contenha uma chave de API válida do CapMonster Cloud;

  • o valor de exemplo YOUR_API_KEY tenha sido substituído;

  • a chave seja passada no bloco env do servidor capmonster, e não do patchright.

Depois de alterar a chave, reinicie o cliente MCP. O agente poderá verificar novamente a conexão e o saldo.

Se o saldo for zero, faça uma recarga antes de criar tarefas.

get_docs não carrega a documentação

Peça ao agente para verificar o acesso de rede do cliente MCP a https://docs.capmonster.cloud/ e se ele consegue carregar o arquivo a seguir:

https://docs.capmonster.cloud/llms.txt

Se a documentação estiver temporariamente indisponível ou se os parâmetros da tarefa precisarem de verificação adicional, o agente poderá usar a especificação da API:

https://api.capmonster.cloud/docs/swagger-ui/spec.js
patchright não abre a página

Verifique o node, o npx e o comando de inicialização:

npx -y capmonster-mcp-patchright

Se a página exigir proxy, User-Agent ou locale, forneça esses parâmetros ao agente. Ele poderá usá-los ao iniciar o navegador por meio do patchright.

A tarefa retorna um erro ou o site rejeita a solução

Forneça ao agente a mensagem de erro e as condições em que o CAPTCHA aparece. Para o diagnóstico, ele pode:

  1. verificar o tipo de tarefa compatível;

  2. obter os parâmetros atuais e o esquema da solução;

  3. abrir a documentação do tipo de CAPTCHA selecionado;

  4. obter novamente os parâmetros dinâmicos após recarregar ou invocar o CAPTCHA outra vez;

  5. verificar se User-Agent, proxy, cookies, cabeçalhos e Client Hints são consistentes para CAPTCHAs vinculados à sessão;

  6. garantir que o resultado seja aplicado no formato exigido pelo tipo específico de CAPTCHA.

Não use valores expirados de challenge, token, data, blob ou outros parâmetros de uso único.

ERROR_INVALID_TASK normalmente indica parâmetros inválidos ou desatualizados. ERROR_CAPTCHA_UNSOLVABLE pode ser um erro temporário — o agente pode verificar os dados de entrada e criar uma nova tarefa.

Perguntas frequentes​

Preciso selecionar e chamar as ferramentas MCP manualmente?

Não. Depois que os servidores MCP forem conectados, as ferramentas ficam automaticamente disponíveis para o agente de IA. O agente as seleciona e chama de acordo com a tarefa atual.

Preciso conectar os dois servidores MCP?

Não. Você pode usar o capmonster sozinho se os parâmetros do CAPTCHA já forem conhecidos e não for necessária interação com o navegador. O patchright é necessário quando o agente precisa abrir uma página, obter parâmetros do CAPTCHA ou aplicar a solução.

Qual implementação devo escolher: npm ou Python?

As duas implementações do capmonster-mcp fornecem as mesmas ferramentas. Escolha a opção que corresponde ao seu ambiente:

  • npm — se o Node.js e o npx já estiverem instalados;

  • Python — se você usar Python 3.11 ou posterior e tiver o uvx instalado.

Em ambos os casos, o patchright requer Node.js e npx.

Onde devo armazenar a chave de API?

Passe a chave de API por meio da variável de ambiente CM_API_KEY na configuração do servidor capmonster. Não a inclua no prompt, em mensagens de chat, exemplos de código ou em um repositório público.

Se o arquivo de configuração contiver uma chave real, exclua-o do Git ou use um mecanismo seguro de armazenamento de segredos compatível com o cliente MCP.

Preciso enviar o prompt antes de cada CAPTCHA?

Não. Após a configuração, durante a sessão atual, basta fornecer novas URLs, condições de exibição do CAPTCHA e tarefas de integração.

Em uma nova sessão, recomendamos enviar o prompt novamente se o agente não preservar as instruções carregadas e os resultados da verificação do ambiente.

Como posso verificar quais tipos de CAPTCHA são compatíveis?

Peça ao agente para identificar os tipos de CAPTCHA compatíveis. Ele pode usar get_supported_tasks e, para uma tarefa específica, get_task_parameters(task_type) e a documentação por meio de get_docs.

Preciso configurar um proxy na configuração MCP?

Não necessariamente. Se o navegador exigir um proxy, forneça os parâmetros ao agente — ele poderá usá-los ao iniciar o navegador sem alterar a configuração MCP.

Se o tipo de CAPTCHA selecionado exigir seu próprio proxy, o agente também deverá passar os parâmetros na tarefa do CapMonster Cloud. Para CAPTCHAs vinculados a um endereço IP ou a uma sessão, o mesmo proxy deve ser usado no navegador e na tarefa.

O artigo foi útil?
Confira os preços do solucionador de CAPTCHA com IA