Como conectar o CapSolver MCP aos Agentes de Navegador rtrvr

TL;DR

• rtrvr pode chamar uma ferramenta de CAPTCHA externa através do MCP. O sistema de ferramentas aceita servidores HTTP ou SSE streamable e expõe ferramentas importadas com nomes qualificados.
• Use a ferramenta modo token para trabalho de navegador vinculado à sessão. Ela retorna um token sem abrir um segundo navegador, deixando o rtrvr responsável pela aba original e pelo passo de submissão específico da aplicação.
• Não confunda duas ferramentas chamadas solve_captcha. O rtrvr documenta uma ação de navegador integrada com esse nome, enquanto o servidor MCP externo importa uma ferramenta qualificada separada, como capsolver.solve_captcha.
• Um token retornado não é prova de que a tarefa do navegador foi bem-sucedida. Verifique a mesma aba, a resposta da aplicação desejada, os limites de tentativas e o estado final do fluxo de trabalho.

Introdução: Conecte uma ferramenta de desafio tipado ao rtrvr

O rtrvr combina uma extensão Chrome, navegadores em nuvem, uma API, um MCP, uma CLI e um SDK para trabalho de navegador com agentes. Seu nível de chamada de ferramenta também pode conectar servidores MCP externos e invocar suas ferramentas a partir de chats ou sub-rotinas JavaScript reutilizáveis. CapSolver se encaixa nesse arquitetura como um serviço de tratamento de desafio separado para sites e ambientes de teste que você possui ou está autorizado a automatizar.

Este guia mostra a integração estreita que as duas interfaces documentadas realmente suportam. O rtrvr mantém o controle da aba de navegador ativa. O CapSolver MCP fornece uma ferramenta modo token com tipo definido. Uma pequena sub-rotina do rtrvr valida a solicitação, chama a ferramenta MCP qualificada e retorna um resultado estruturado ao fluxo de trabalho. A atualização final da página permanece como um passo específico da aplicação, pois um token de CAPTCHA está vinculado ao contexto do desafio e não é um resultado genérico de clique.

Este guia não pressupõe uma parceria oficial nativa entre os produtos. Tampouco afirma que o CapSolver MCP pode se conectar ao objeto navegador interno do rtrvr. Em vez disso, ele usa o contrato de ferramenta externa publicado pelo rtrvr e o esquema de ferramenta MCP publicado pelo CapSolver.

O que a integração do rtrvr e CapSolver suporta

A documentação Calling de Ferramentas do rtrvr diz que os usuários podem conectar um servidor MCP por URL, habilitar ferramentas importadas, chamá-las diretamente com @toolname e compô-las dentro de uma ferramenta personalizada com rtrvr.callTool(name, params). As ferramentas MCP importadas são salvas com um prefixo de servidor, o que é importante quando dois sistemas publicam o mesmo nome de ferramenta.

A documentação do Serviço MCP do CapSolver expõe cinco ferramentas:

Para uma aba do rtrvr autenticada, solve_captcha é o ponto de partida prático. As ferramentas do CapSolver MCP baseadas no navegador iniciam sua própria sessão Playwright. Elas não recebem a aba atual, cookies, armazenamento local ou estado da página do rtrvr. Isso torna solve_on_page útil para uma verificação de página independente e autorizada, mas não para uma continuação transparente de uma sessão rtrvr existente.

Também há uma colisão de nomes a ser tratada intencionalmente. O rtrvr documenta solve_captcha como uma das suas ferramentas pageAction integradas. O CapSolver MCP publica uma ferramenta com o mesmo nome curto. Após conectar o servidor externo, inspecione a lista de ferramentas e chame seu nome completo importado, normalmente capsolver.solve_captcha. Não deixe um planejador adivinhar qual você pretendia.

Arquitetura e limites de responsabilidade

Mantenha a integração em quatro camadas:

Esta separação evita três erros comuns. Primeiro, o modelo não inventa campos de tarefa. Segundo, uma resposta de token não é registrada como uma ação de negócio concluída. Terceiro, uma recusa de acesso, parede de login, solicitação de MFA ou desafio não suportado não é enviada repetidamente ao solucionador.

Use este padrão apenas em sistemas que você possui ou tem permissão para testar ou automatizar. Mantenha fluxos sensíveis como pagamento, verificação de identidade, criação de conta, acesso a dados privados e outros atrás de aprovação humana explícita e das regras de serviço aplicáveis.

Etapa 1: Inicie o CapSolver MCP via HTTP Streamable

O rtrvr conecta servidores MCP externos por URL, enquanto o CapSolver MCP usa por padrão stdio. Inicie o mesmo servidor com HTTP Streamable para que a extensão rtrvr possa alcançá-lo.

python -m venv .venv
source .venv/bin/activate
pip install capsolver-core
pip install capsolver-mcp

export CAPSOLVER_API_KEY="SUA_CHAVE_API_DO_CAPSOLVER"
capsolver-mcp --transport streamable-http --host 127.0.0.1 --port 8000

O SDK Python oficial do MCP usa /mcp como caminho padrão de HTTP Streamable, então o endpoint local é:

http://127.0.0.1:8000/mcp

Vincular a 127.0.0.1 mantém o serviço local. A opção --api-key ou a variável de ambiente CAPSOLVER_API_KEY autentica o servidor ao CapSolver; não é uma camada de autenticação do cliente para quem pode alcançar a porta MCP. Não vincule este comando diretamente a uma interface pública. Se um ambiente rtrvr remoto precisar alcançá-lo, implante-o atrás de HTTPS autenticado, restrinja a rede permitida, proteja a chave API em um repositório de segredos e revise as configurações de origem e transporte do servidor MCP.

As ferramentas modo token não exigem Playwright. Instale o extra do navegador apenas quando tiver um uso autorizado separado para detect_captchas ou solve_on_page:

pip install "capsolver-mcp[browser]"
playwright install chromium

Etapa 2: Conecte e verifique o servidor MCP no rtrvr

Abra a seção Ferramentas do rtrvr, adicione a URL local do MCP e habilite apenas as ferramentas que o fluxo de trabalho precisa. O rtrvr documenta suporte a servidores MCP com HTTP Streamable, SSE e OAuth. Para esta configuração local, use a URL HTTP Streamable da etapa anterior.

Comece com duas chamadas não baseadas no navegador:

@capsolver.get_supported_captchas
@capsolver.get_balance

O prefixo exato é atribuído pelo rtrvr quando o servidor é conectado. Se for diferente, use o nome mostrado no painel Ferramentas. Uma sub-rotina personalizada também pode chamar await rtrvr.listTools() e inspecionar cada ferramenta disponível, seu nome, descrição, esquema de parâmetro e origem.

Essas verificações respondem a perguntas diferentes. get_supported_captchas comprova que o rtrvr descobriu a ferramenta externa. get_balance comprova que o processo MCP recebeu uma credencial de conta funcional. Nenhuma dessas verificações comprova que um desafio real pode ser concluído, mas ambas separam falhas de configuração de falhas de tarefa antes de gastar tempo debugando um fluxo de navegador.

Não coloque uma chave de API real em uma pergunta do rtrvr, gravação de página, captura de tela ou repositório. Mantenha-a no ambiente do processo MCP. Se o processo registrar argumentos de ferramenta, redija tokens, chaves, URLs com parâmetros sensíveis e quaisquer identificadores específicos do alvo antes de manter os logs.

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 no seu Painel do CapSolver

Etapa 3: Adicione uma sub-rotina rtrvr determinística

Ferramentas JavaScript personalizadas do rtrvr podem chamar ferramentas MCP conectadas através de rtrvr.callTool. A sub-rotina a seguir faz quatro coisas antes de retornar um token: valida a URL, permite os tipos de desafio suportados, descobre a ferramenta externa qualificada e normaliza os estados de falha.

const allowedTypes = new Set(["reCaptchaV2", "reCaptchaV3", "cloudflare"]);

function fail(state, message, details = {}) {
  return { ok: false, state, message, ...details };
}

if (!allowedTypes.has(captchaType)) {
  return fail("unsupported_challenge", `Tipo não suportado: ${captchaType}`);
}

const parsed = new URL(websiteUrl);
if (parsed.protocol !== "https:") {
  return fail("policy_block", "Apenas destinos HTTPS aprovados são permitidos");
}

const tools = await rtrvr.listTools();
const solver = tools.find((tool) =>
  tool.source === "mcp" &&
  (tool.name === "capsolver.solve_captcha" || tool.name.endsWith(".solve_captcha"))
);

if (!solver) {
  return fail("configuration_error", "CapSolver MCP solve_captcha não foi encontrado");
}

const result = await rtrvr.callTool(solver.name, {
  captcha_type: captchaType,
  website_url: websiteUrl,
  website_key: websiteKey,
  version: version || null,
  page_action: pageAction || null,
  min_score: minScore || null,
  invisible: invisible ?? null,
  enterprise: enterprise ?? null,
  cdata: cdata || null,
  timeout: 90,
  polling_interval: 5,
});

if (!result?.success || !result?.solution?.token) {
  return fail("solve_failed", result?.error || "Nenhum token retornado", {
    errorCode: result?.error_code || null,
    httpStatus: result?.http_status || null,
  });
}

return {
  ok: true,
  state: "token_ready",
  captchaType: result.solution.captcha_type,
  token: result.solution.token,
  expiresAt: result.solution.expire_time || null,
};

Defina captchaType, websiteUrl, websiteKey e os campos opcionais como parâmetros da ferramenta no rtrvr. O exemplo intencionalmente não extrai uma chave de site de páginas arbitrárias ou insere um token em uma aplicação desconhecida. Para uma aplicação de teste que você controla, adicione um adaptador separado que leia os parâmetros exatos do desafio do seu contrato de aplicação e submeta o resultado através da forma ou endpoint de servidor suportado.

O teste local incluído cobre a lógica de ramificação de orquestração com um runtime de ferramenta rtrvr simulado. Uma comunicação real ainda exige uma conta rtrvr, um dispositivo de navegador ativo ou contexto em nuvem, uma chave API do CapSolver e uma página de teste autorizada.

Etapa 4: Mantenha o token vinculado ao estado original do navegador

Soluções de CAPTCHA são sensíveis ao contexto. O tipo de desafio, chave de site pública, URL da página, nome da ação, estado da sessão e, às vezes, dados de proxy ou agente do usuário podem afetar se a aplicação de destino aceita um resultado. O fluxo de trabalho do navegador, portanto, deve preservar a aba original e submeter o token retornado da maneira esperada pela aplicação.

Use um estado de fluxo tipado em vez de um loop genérico de tentativa:

1. page_ready: a página desejada carregou e sua identidade foi verificada.
2. challenge_detected: um desafio suportado está presente e os parâmetros vieram de evidência de página confiável.
3. solve_requested: uma chamada MCP vinculada foi criada para essa instância de desafio.
4. token_ready: o serviço retornou um token, mas nenhuma sucesso da aplicação foi reivindicada ainda.
5. submitted: o adaptador específico da aplicação submeteu o token na mesma sessão autorizada.
6. accepted: a rota, resposta da API ou estado da página desejada confirma o sucesso.
7. review ou stopped: o estado é ambíguo, não suportado, sensível ou ultrapassou o orçamento.

Não chame solve_on_page como atalho para esse fluxo vinculado à sessão. A implementação atual do CapSolver MCP abre uma página Chromium headless separada para essa ferramenta, realiza a detecção e preenchimento lá e fecha o navegador depois. Isso é uma operação válida autônoma, mas é uma sessão diferente da extensão ou navegador em nuvem do rtrvr. Use-a apenas quando uma sessão separada for aceitável e explicitamente autorizada.

Etapa 5: Verifique o resultado da aplicação

Uma resposta bem-sucedida do MCP significa que a ferramenta retornou um objeto de solução. Não significa que um login, submissão de formulário, tarefa de extração ou tarefa de navegador tenha sido concluída. A verificação deve ocorrer no rtrvr na aba original.

Use pelo menos três verificações:

• Continuidade da aba: o ID da aba, host e etapa do fluxo desejado ainda correspondem à solicitação que produziu o desafio.
• Aceitação da aplicação: uma rota documentada, estado do DOM ou resposta do servidor confirma que a aplicação aceitou o resultado.
• Resultado do negócio: a tarefa autorizada desejada foi concluída sem troca silenciosa de páginas, contas ou registros.

Se a página mostrar o mesmo desafio novamente, pare após o orçamento de tentativas configurado. Laços repetidos de desafio podem indicar um token expirado, parâmetros desalinhados, inconsistência de proxy ou agente do usuário, variação de desafio não suportada ou uma decisão de política de acesso mais ampla. Mais chamadas não provam progresso.

Registre estados e códigos de erro, não segredos. Um evento útil contém um ID de correlação, horário, nome da ferramenta, tipo de desafio, host de destino, número de tentativas, transição de estado, latência e resultado final da aplicação. Não mantenha o token de solução ou chave API em logs normais.

Solução de problemas da integração do rtrvr MCP

Lista de verificação de produção

Antes de avançar para uma página de teste, confirme todas as seguintes condições:

• o alvo e o fluxo de trabalho do navegador estão autorizados;
• a ferramenta CapSolver é selecionada pelo seu nome qualificado MCP;
• os parâmetros de desafio vêm de evidências de tempo de execução confiáveis, não de adivinhações do modelo;
• as chaves da API ficam em um ambiente ou armazenamento de segredos;
• o ponto de extremidade MCP está local ou protegido por HTTPS autenticado e controles de rede;
• o tratamento de tokens é separado da submissão específica da aplicação;
• os retries são limitados por instância de desafio e por fluxo de trabalho;
• os logs omitem chaves da API, tokens de solução, URLs sensíveis e dados de página privados;
• o rtrvr verifica o estado final na aba original;
• ações sensíveis de conta, pagamento, identidade e dados privados exigem revisão explícita;
• estados não suportados ou ambíguos interrompem com segurança.

Esta lista de verificação é mais importante do que adicionar outro prompt de planejador. A maioria das falhas de integração ocorre na fronteira entre o estado do navegador, entradas da ferramenta, saída do serviço e aceitação da aplicação. Esses são contratos de tempo de execução, não problemas de raciocínio de modelo de linguagem.

Conclusão

O rtrvr fornece a superfície de ferramenta externa necessária para chamar o CapSolver MCP, mas a integração confiável é mais estreita do que simplesmente habilitar uma ferramenta. Inicie o CapSolver MCP sobre HTTP Streamable, conecte o ponto de extremidade no rtrvr, verifique a descoberta com ferramentas fora do navegador e chame o solucionador externo pelo seu nome qualificado. Para sessões ativas do rtrvr, use o modo de token e mantenha a submissão da página e a verificação do resultado dentro do fluxo de trabalho original do navegador. Trate ferramentas de navegador separadas como sessões separadas, mantenha a evidência digitada e interrompa estados não suportados ou ambíguos. Em fluxos de trabalho de agente de navegador autorizados, o CapSolver fornece a ferramenta de desafio documentada enquanto o rtrvr permanece responsável pelo contexto do navegador e pelo sucesso da aplicação final.

Adicione tratamento de CAPTCHA a um fluxo de trabalho rtrvr autorizado

Revise as cinco ferramentas publicadas na documentação do CapSolver MCP, depois conecte um ponto de extremidade local ou corretamente protegido no painel de Ferramentas do rtrvr. Use o Painel do CapSolver para testar um fluxo aprovado antes de expandir a integração.

Perguntas frequentes

P: O rtrvr tem uma integração nativa com o CapSolver?

A documentação revisada não afirma uma parceria nativa ou provedor integrado do CapSolver. A integração neste guia usa a conexão geral de ferramenta MCP do rtrvr e o servidor MCP público do CapSolver.

P: Por que não chamar o nome curto solve_captcha?

O rtrvr documenta uma ação de navegador integrada com esse nome, e o CapSolver MCP publica o mesmo nome curto. Use o nome importado qualificado mostrado no painel de Ferramentas, como capsolver.solve_captcha, para evitar ambiguidade.

P: O CapSolver MCP pode usar a aba do navegador já aberta no rtrvr?

Não por meio das ferramentas MCP documentadas. O modo de token precisa de parâmetros de desafio explícitos e retorna um token, enquanto as ferramentas de modo de navegador iniciam um navegador Playwright separado.

P: Devo expor a porta MCP local para a internet?

Não. Mantenha-a em localhost para uso local. Uma implantação compartilhada precisa de HTTPS autenticado, restrições de rede, gerenciamento de segredos, controles de origem e revisão de segurança explícita.

P: Como saber se a tarefa do navegador foi bem-sucedida?

Verifique o resultado na aba original do rtrvr usando a rota esperada, estado do DOM, resposta da API e resultado comercial. Um token retornado sozinho não é evidência de sucesso.