Integração do Mastra CAPTCHA Solver: Um Guia MCP Prático

Resumo rápido

• O MCPClient do Mastra pode iniciar um processo local de resolução de CAPTCHA e descobrir suas ferramentas via stdio.
• listTools() retorna ferramentas com namespace, como capsolver_get_supported_captchas para a chave de servidor do exemplo.
• Execute uma consulta de capacidades diretamente antes de envolver um modelo de linguagem ou enviar uma tarefa de CAPTCHA paga.
• Selecione apenas as ferramentas de que seu agente precisa, em vez de anexar automaticamente todas as capacidades descobertas.
• Feche o cliente MCP quando uma verificação isolada terminar e diferencie resultados do solver da conclusão do fluxo de trabalho no navegador.

A integração do resolvedor de CAPTCHA do Mastra fornece a uma aplicação TypeScript um limite de ferramenta bem definido para um ponto de verificação de verificação. Um fluxo de trabalho de navegador pode já saber o que fazer antes e depois de um desafio, enquanto o agente precisa de uma forma suportada de solicitar a operação de desafio. O MCP conecta essa capacidade sem exigir outro wrapper em torno da API subjacente do solver.

O CapSolver fornece o servidor local neste exemplo. O guia usa o cliente real do Mastra para descobrir suas ferramentas e executar uma consulta de tipos suportados. Em seguida, explica como anexar um subconjunto apropriado a um agente e preservar a distinção entre uma resposta de ferramenta e uma tarefa web concluída. O exemplo é uma verificação de integração local, sem necessidade de website de terceiros ou CAPTCHA pago.

Onde a ferramenta de CAPTCHA se encaixa em uma aplicação Mastra?

A ferramenta de CAPTCHA se encaixa em uma etapa de desafio conhecida dentro de um fluxo de trabalho autorizado da aplicação. O Mastra coordena as ferramentas expostas a um agente; o solver executa uma operação específica; seu navegador ou código de aplicação é responsável pelos passos que usam o resultado.

Considere um serviço de QA executando um teste de formulário controlado pelo proprietário. O teste preparou seus dados e chegou a um desafio suportado. Uma operação de solver pode fornecer a resposta relevante, mas o teste ainda precisa enviar o formulário corretamente e verificar a confirmação esperada. Um agente não deve relatar sucesso apenas porque recebeu uma resposta de ferramenta não vazia.

O projeto Mastra fornece o framework, enquanto seu guia de conexão MCP descreve a interface de cliente usada aqui. Esta é uma conexão MCP direta. Ela não implica que o solver seja um provedor nativo em todos os produtos Mastra ou em todo catálogo de integrações hospedadas.

Prepare um pequeno projeto de integração local

Prepare um projeto local Node.js e um ambiente Python para que cada parte tenha um conjunto de dependências explícito. O exemplo foi executado com Node.js 24.16.0, Python 3.12.14, @mastra/mcp 2.4.1 e capsolver-mcp 0.1.3. O pacote Mastra selecionado requer Node.js 22.13.0 ou mais recente; usar o runtime Node.js 24 testado evita incompatibilidades com runtimes mais antigos.

Execute estes passos em um diretório de projeto novo no macOS ou Linux:

npm init -y
npm install @mastra/mcp@2.4.1
python3 -m venv py
py/bin/python -m pip install capsolver-mcp==0.1.3

O arquivo .mjs abaixo usa o suporte a módulos ES do Node. O caminho do servidor é resolvido em relação ao diretório a partir do qual você executa o script, então execute-o a partir da raiz do projeto contendo py. Se o seu ambiente Python estiver em outro lugar, altere o caminho em vez de depender de qualquer Python que apareça primeiro no PATH do shell.

Nenhuma credencial de modelo é necessária para esta verificação direta de ferramenta. Respostas orientadas por modelo precisam da autenticação do provedor do modelo. Operações de CAPTCHA pagas requerem as credenciais de conta apropriadas do solver e parâmetros de tarefa. Essa separação permite diagnosticar problemas de instalação antes de introduzir comportamento de modelo, estado de navegador ou cobranças de conta.

Conecte MCPClient e consulte os tipos de CAPTCHA suportados

Conecte o MCPClient ao processo Python instalado, descubra as ferramentas e execute a consulta de capacidades. Salve o seguinte como mastra-check.mjs no diretório do projeto:

import { MCPClient } from '@mastra/mcp';
import { resolve } from 'node:path';

const client = new MCPClient({
  id: 'captcha-setup-check',
  servers: {
    capsolver: {
      command: resolve('py/bin/python'),
      args: ['-m', 'capsolver_mcp'],
      env: { CAPSOLVER_API_KEY: process.env.CAPSOLVER_API_KEY || '' },
    },
  },
});

try {
  const tools = await client.listTools();
  console.log('TOOLS', Object.keys(tools));
  const capabilityTool = tools.capsolver_get_supported_captchas;
  if (!capabilityTool) throw new Error('Capability tool was not discovered');
  const result = await capabilityTool.execute({});
  console.log('CAPABILITIES', JSON.stringify(result, null, 2));
} finally {
  await client.disconnect();
  console.log('DISCONNECTED');
}

Este adaptador combina a interface de lançamento MCP oficial do CapSolver com o cliente do Mastra. O script foi executado contra os pacotes instalados, incluindo a chamada de capacidades e o disconnect. Ele não constrói uma resposta falsa de servidor nem envia um desafio.

Execute-o a partir do mesmo diretório do projeto:

node mastra-check.mjs

A lista testada continha capsolver_solve_captcha, capsolver_detect_captchas, capsolver_solve_on_page, capsolver_get_balance e capsolver_get_supported_captchas. A chamada de capacidade retornou este resultado estruturado:

{
  "success": true,
  "registered_handlers": ["recaptcha", "cloudflare"],
  "captcha_types": ["reCaptchaV2", "reCaptchaV3", "cloudflare"]
}

O resultado descreve os handlers registrados e os valores de tipo do pacote instalado. Isso não significa que todo produto listado no site do CapSolver esteja disponível por meio desta versão do pacote. O script também imprimiu DISCONNECTED após fechar o cliente. Sua execução pode incluir linhas adicionais de diagnóstico do servidor em torno desses valores.

Entenda os nomes antes de anexar ferramentas a um agente

O Mastra aplica namespaces à lista achatada de ferramentas usando a chave de servidor configurada. Aqui, capsolver é a chave de servidor e get_supported_captchas é o nome da ferramenta remota, produzindo capsolver_get_supported_captchas no objeto retornado.

Use a chave retornada em vez de adivinhá-la a partir de um rótulo de exibição. Renomear a entrada de servidor altera a chave que seu código espera. Ao mover uma configuração funcional para uma aplicação maior, inspecione as ferramentas descobertas novamente antes de reutilizar uma busca ou uma instrução de agente que mencione uma delas.

A referência do MCPClient documenta descoberta e ciclo de vida da conexão. Mantenha a versão do pacote junto com suas anotações de configuração. Copie nomes de métodos da referência para a versão instalada em vez de combinar um cliente atual com chamadas de um tutorial antigo.

Escolha um subconjunto de ferramentas para cada trabalho

Escolha o subconjunto de ferramentas com base no trabalho que o agente pode executar. Um assistente de configuração pode precisar apenas da consulta de capacidades. Um fluxo de trabalho que já extrai parâmetros de tarefa pode precisar de resolução orientada a token. Um fluxo de trabalho orientado a página tem dependências de navegador e requisitos de sessão diferentes.

Para um agente real no Mastra, construa o objeto de ferramentas a partir das entradas relevantes descobertas e forneça-o por meio da configuração tools documentada do agente. Mantenha a conexão MCP ativa enquanto o agente puder invocar suas ferramentas. Este script isolado desconecta imediatamente porque seu único trabalho é uma consulta; copiar esse ciclo de vida sem modificação para um agente de longa duração fecharia a conexão cedo demais.

A consulta direta torna o transporte e os dados visíveis sem pedir que um modelo escolha uma ferramenta. Depois que ela passar, teste a seleção de ferramentas pelo agente separadamente, com credenciais normais de modelo e as regras de permissão da sua aplicação. Uma consulta direta bem-sucedida deve ajudar a isolar o próximo teste, não substituí-lo.

Resgate Seu Código de Bônus CapSolver

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

Conecte o resultado da ferramenta ao fluxo de trabalho do navegador

Conecte o resultado da ferramenta ao componente que é responsável pela tarefa aprovada no navegador. Resultados orientados a token e orientados a página exigem tratativas diferentes, então decida qual interface a aplicação usará antes de adicionar um prompt de agente em torno dela.

Se seu código já conhece o tipo de CAPTCHA suportado e seus parâmetros exigidos, uma ferramenta de resolução pode receber essa entrada estruturada. O código do navegador continua responsável por aplicar o resultado por meio do caminho de integração documentado e observar o próximo estado da aplicação. Uma chamada de ferramenta bem-sucedida não substitui essas verificações.

Para as ferramentas baseadas em navegador do servidor, instale as dependências documentadas e confirme como a sessão é criada. Um serviço iniciado por meio de um comando local é um processo separado. Ele não herda automaticamente a aba aberta, o estado de formulário ou a sessão autenticada de outro navegador. O SDK core é uma superfície diferente a avaliar quando seu programa precisa trabalhar diretamente com um objeto de página que já controla.

Um registro de QA pode capturar o estágio atingido, a ferramenta selecionada, o resultado da ferramenta e a asserção final da aplicação. Esses campos respondem a perguntas diferentes. Uma falha de conexão diz respeito à integração; um erro de tarefa diz respeito à solicitação ao solver; um estado de confirmação ausente diz respeito ao fluxo de trabalho da aplicação. Preserve essas distinções em logs e mensagens de status voltadas ao usuário.

Trate as falhas no estágio que as produziu

Trate o estágio com falha antes de permitir que um agente repita todo o fluxo de trabalho. A maioria das falhas iniciais de integração tem um pequeno conjunto de verificações práticas:

Uma chamada de API pode ter sucesso em uma camada enquanto a tarefa maior do usuário permanece inacabada. Relate o resultado realmente observado. “Conexão de ferramenta estabelecida” é útil durante a configuração; “formulário enviado” exige um resultado de formulário observado.

Mantenha as tentativas de repetição limitadas para operações de desafio reais. Evite criar uma nova tarefa paga apenas para diagnosticar configuração. A consulta de capacidades funcional oferece uma forma mais barata de isolar a conexão local. O guia oficial de instalação MCP também ajuda quando o comando do servidor não pode ser localizado.

Preserve o contexto de diagnóstico útil

Preserve versões de pacotes, a chave de servidor configurada, o nome da operação e se o processo iniciou com sucesso. Esses detalhes ajudam outro desenvolvedor a reproduzir a falha sem receber uma chave de conta ou toda a sessão do navegador. Neste exemplo, um namespace ausente e uma falha de inicialização do servidor exigem correções diferentes, mesmo que ambos pareçam inicialmente ser uma ferramenta ausente.

Quando uma tarefa se move entre trabalhadores, mantenha o registro da aplicação separado da vida útil deste cliente de diagnóstico. Não deixe que um agente transforme automaticamente um objeto local ausente em uma nova requisição paga. A aplicação deve decidir se uma operação anterior ainda é relevante antes de permitir outra tentativa.

Mantenha a primeira integração pequena

Mantenha a primeira integração focada em um único fluxo de trabalho permitido e um conjunto estreito de ferramentas. Este exemplo prova que o cliente pode descobrir o serviço real, executar uma consulta de capacidades que não resolve CAPTCHA, receber dados estruturados e desconectar. Ele não afirma que um modelo escolheu a ferramenta certa ou que um CAPTCHA pago e uma tarefa de navegador foram concluídos.

A partir dessa base, conecte a operação de desafio de que sua aplicação precisa e adicione seu teste de aceitação. O CapSolver fornece a capacidade de resolução; a aplicação Mastra determina quando ela é apropriada e o que conta como trabalho concluído. Prepare credenciais no seu painel CapSolver antes desse teste ponta a ponta separado.

Perguntas frequentes

P: Posso testar a conexão sem uma chave de API de LLM?

Sim. O exemplo chama uma ferramenta descoberta diretamente através do cliente MCP do Mastra. Ele não pede a um modelo de linguagem que gere uma resposta ou selecione uma ferramenta.

P: A consulta de capacidades é uma resolução real de CAPTCHA?

Não. Ela retorna informações de handlers registrados e tipos de CAPTCHA do serviço instalado. Ela não valida uma resolução paga nem o estado de uma página de navegador.

P: Por que a ferramenta se chama capsolver_get_supported_captchas?

O prefixo vem da chave de servidor capsolver. O Mastra adiciona esse namespace ao nome da ferramenta remota na lista achatada.

P: Toda ferramenta descoberta deve estar disponível para meu agente?

Não. Selecione as capacidades necessárias para o trabalho atribuído a ele e então teste seleção e execução em relação às permissões e ao fluxo de trabalho da sua aplicação.

P: Quando devo chamar disconnect?

Desconecte quando não forem necessárias mais chamadas através do cliente. Um diagnóstico de uso único pode fechar no finally; um agente em execução precisa da conexão durante todo o uso de ferramentas.

P: Isso prova que meu fluxo de trabalho de navegador em produção vai funcionar?

Não. Isso verifica a integração local cliente-servidor e a consulta. A produção ainda precisa de credenciais válidas, parâmetros de tarefa suportados, estado de navegador adequado e uma verificação ponta a ponta da aplicação.