Integración del solucionador de CAPTCHA de Mastra: una guía práctica de MCP

Resumen

• El MCPClient de Mastra puede lanzar un proceso local de resolución de CAPTCHA y descubrir sus herramientas por stdio.
• listTools() devuelve herramientas con espacio de nombres, como capsolver_get_supported_captchas para la clave de servidor del ejemplo.
• Ejecuta una consulta de capacidades justo antes de involucrar a un modelo de lenguaje o enviar una tarea de CAPTCHA de pago.
• Selecciona solo las herramientas que tu agente necesita en lugar de adjuntar automáticamente todas las capacidades descubiertas.
• Cierra el cliente MCP cuando se complete una comprobación independiente y distingue los resultados del solver de la finalización del flujo de trabajo del navegador.

La integración del solver de CAPTCHA de Mastra da a una aplicación TypeScript un límite de herramienta definido para un punto de verificación. Un flujo de trabajo de navegador puede saber ya qué hacer antes y después de un desafío, mientras que el agente necesita una forma compatible de solicitar la operación del desafío. MCP conecta esa capacidad sin requerir otro wrapper alrededor de la API subyacente del solver.

CapSolver proporciona el servidor local en este ejemplo. La guía usa el cliente real de Mastra para descubrir sus herramientas y ejecutar una consulta de tipos admitidos. Luego explica cómo adjuntar un subconjunto apropiado a un agente y mantener la distinción entre una respuesta de herramienta y una tarea web completada. El ejemplo es una comprobación de integración local, sin sitio web de terceros ni CAPTCHA de pago.

¿Dónde encaja la herramienta de CAPTCHA en una aplicación Mastra?

La herramienta de CAPTCHA encaja en un paso de desafío conocido dentro de un flujo de trabajo de aplicación autorizado. Mastra coordina las herramientas expuestas a un agente; el solver realiza una operación específica; tu navegador o código de aplicación es el propietario de los pasos que usan su resultado.

Considera un servicio de QA que ejecuta una prueba de formulario controlada por el propietario. La prueba ha preparado sus datos y ha llegado a un desafío admitido. Una operación del solver puede proporcionar la respuesta relevante, pero la prueba aún debe enviar el formulario correctamente y comprobar la confirmación esperada. Un agente no debe informar éxito solo porque recibió una respuesta de herramienta no vacía.

El proyecto Mastra proporciona el framework, mientras que su guía de conexión MCP describe la interfaz de cliente utilizada aquí. Esta es una conexión MCP directa. No implica que el solver sea un proveedor nativo en todos los productos Mastra o en cada catálogo de integraciones alojadas.

Prepara un pequeño proyecto de integración local

Prepara un proyecto local de Node.js y un entorno de Python para que cada parte tenga un conjunto de dependencias explícito. El ejemplo se ejecutó con Node.js 24.16.0, Python 3.12.14, @mastra/mcp 2.4.1 y capsolver-mcp 0.1.3. El paquete de Mastra seleccionado requiere Node.js 22.13.0 o más reciente; usar el runtime probado de Node.js 24 evita un desajuste con runtimes más antiguos.

Ejecuta estos pasos en un directorio de proyecto nuevo en macOS o 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

El archivo .mjs de abajo usa el soporte de módulos ES de Node. La ruta del servidor se resuelve en relación con el directorio desde el que ejecutas el script, así que ejecútalo desde la raíz del proyecto que contiene py. Si tu entorno de Python vive en otro lugar, cambia la ruta en lugar de depender de la primera instalación de Python que aparezca en el PATH del shell.

No se necesita una credencial de modelo para esta comprobación directa de herramientas. Las respuestas impulsadas por modelos necesitan la autenticación del proveedor de modelos. Las operaciones de CAPTCHA de pago requieren las credenciales de cuenta del solver correspondiente y los parámetros de tarea. Esta separación te permite diagnosticar problemas de instalación antes de introducir comportamiento del modelo, estado del navegador o cargos en la cuenta.

Conecta MCPClient y consulta los tipos de CAPTCHA admitidos

Conecta MCPClient al proceso de Python instalado, descubre las herramientas y ejecuta la consulta de capacidades. Guarda lo siguiente como mastra-check.mjs en el directorio del proyecto:

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 la interfaz oficial de lanzamiento MCP de CapSolver con el cliente de Mastra. El script se ejecutó contra los paquetes instalados, incluida la llamada de capacidades y la desconexión. No construye una respuesta falsa de servidor ni envía un desafío.

Ejecútalo desde el mismo directorio del proyecto:

node mastra-check.mjs

La lista probada contenía capsolver_solve_captcha, capsolver_detect_captchas, capsolver_solve_on_page, capsolver_get_balance y capsolver_get_supported_captchas. La llamada de capacidades devolvió este resultado estructurado:

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

El resultado describe los handlers registrados del paquete instalado y los valores de tipo. No significa que todos los productos listados en el sitio web de CapSolver estén disponibles a través de esta versión del paquete. El script también imprimió DISCONNECTED después de cerrar el cliente. Tu ejecución puede incluir líneas de diagnóstico adicionales del servidor alrededor de estos valores.

Comprende los nombres antes de adjuntar herramientas a un agente

Mastra agrega un espacio de nombres a la lista aplanada de herramientas usando la clave de servidor configurada. Aquí, capsolver es la clave de servidor y get_supported_captchas es el nombre de la herramienta remota, produciendo capsolver_get_supported_captchas en el objeto devuelto.

Usa la clave devuelta en lugar de adivinarla a partir de una etiqueta de visualización. Cambiar el nombre de la entrada del servidor cambia la clave que tu código espera. Al mover una configuración funcional a una aplicación más grande, inspecciona de nuevo las herramientas descubiertas antes de reutilizar una búsqueda o una instrucción de agente que nombre una.

La referencia de MCPClient documenta el descubrimiento y el ciclo de vida de la conexión. Mantén la versión del paquete junto a tus notas de configuración. Copia los nombres de métodos de la referencia de tu versión instalada en lugar de combinar un cliente actual con las llamadas de un tutorial más antiguo.

Elige un subconjunto de herramientas para cada tarea

Elige el subconjunto de herramientas según el trabajo que el agente pueda realizar. Un asistente de configuración puede necesitar solo la consulta de capacidades. Un flujo de trabajo que ya extrae parámetros de tarea puede necesitar resolución orientada a tokens. Un flujo de trabajo orientado a páginas tiene dependencias de navegador y requisitos de sesión diferentes.

Para un agente real de Mastra, construye el objeto de herramientas a partir de las entradas relevantes descubiertas y proporciónalo mediante la configuración documentada de tools del agente. Mantén la conexión MCP viva mientras el agente pueda invocar sus herramientas. Este script independiente se desconecta inmediatamente porque su única tarea es una consulta; copiar ese ciclo de vida sin cambios a un agente de larga ejecución cerraría la conexión demasiado pronto.

La consulta directa hace visible el transporte y los datos sin pedir a un modelo que elija una herramienta. Una vez que pasa, prueba la selección de herramientas del agente por separado con credenciales normales de modelo y las reglas de permisos de tu aplicación. Una consulta directa exitosa debe ayudar a aislar la siguiente prueba, no reemplazarla.

Canjea tu código de bono de CapSolver

Impulsa tu presupuesto de automatización al instante.
Usa el código de bono CAP26 cuando recargues tu cuenta de CapSolver para obtener un 5% de bono adicional en cada recarga, sin límites.
Canjéalo ahora en tu Panel de CapSolver

Conecta el resultado de la herramienta con el flujo de trabajo del navegador

Conecta el resultado de la herramienta con el componente que es propietario de la tarea de navegador aprobada. Los resultados orientados a tokens y a páginas necesitan manejos distintos, así que decide qué interfaz usará la aplicación antes de añadir un prompt de agente alrededor de ella.

Si tu código ya conoce el tipo de CAPTCHA admitido y sus parámetros requeridos, una herramienta de resolución puede recibir esa entrada estructurada. El código del navegador sigue siendo responsable de aplicar el resultado mediante la ruta de integración documentada y de observar el siguiente estado de la aplicación. Una llamada de herramienta exitosa no sustituye estas comprobaciones.

Para las herramientas basadas en navegador del servidor, instala sus dependencias documentadas y confirma cómo se crea la sesión. Un servicio lanzado mediante un comando local es un proceso separado. No hereda automáticamente la pestaña abierta, el estado del formulario o la sesión autenticada de otro navegador. El SDK principal es una superficie diferente que evaluar cuando tu programa necesita trabajar directamente con un objeto de página que ya controla.

Un registro de QA puede capturar la etapa alcanzada, la herramienta seleccionada, el resultado de la herramienta y la aserción final de la aplicación. Estos campos responden a preguntas diferentes. Un fallo de conexión concierne a la integración; un error de tarea concierne a la solicitud al solver; un estado de confirmación ausente concierne al flujo de trabajo de la aplicación. Conserva esas distinciones en los logs y en los mensajes de estado orientados al usuario.

Maneja los fallos en la etapa que los produjo

Maneja la etapa fallida antes de permitir que un agente repita todo el flujo de trabajo. La mayoría de los fallos iniciales de integración tienen un pequeño conjunto de comprobaciones prácticas:

Una llamada de API puede tener éxito en una capa mientras la tarea de usuario más amplia sigue sin terminar. Informa del resultado realmente observado. “Conexión de herramienta establecida” es útil durante la configuración; “formulario enviado” requiere un resultado de formulario observado.

Mantén acotados los reintentos para operaciones de desafío reales. Evita crear una nueva tarea de pago solo para diagnosticar la configuración. La consulta de capacidades que funciona ofrece una forma más económica de aislar la conexión local. La guía oficial de instalación de MCP también ayuda cuando no se puede localizar el comando del servidor.

Conserva el contexto de diagnóstico útil

Conserva las versiones de los paquetes, la clave de servidor configurada, el nombre de la operación y si el proceso se inició correctamente. Estos detalles ayudan a otro desarrollador a reproducir el fallo sin recibir una clave de cuenta o toda la sesión del navegador. En este ejemplo, un espacio de nombres ausente y un fallo de arranque del servidor requieren soluciones diferentes incluso si ambos parecen inicialmente una herramienta ausente.

Cuando una tarea se mueve entre workers, mantén su registro de aplicación separado del ciclo de vida de este cliente de diagnóstico. No dejes que un agente convierta un objeto local ausente en una nueva solicitud de pago automáticamente. La aplicación debe decidir si una operación anterior sigue siendo relevante antes de permitir otro intento.

Mantén pequeña la primera integración

Mantén la primera integración centrada en un flujo de trabajo permitido y un conjunto estrecho de herramientas. Este ejemplo demuestra que el cliente puede descubrir el servicio real, ejecutar una consulta de capacidades sin resolución, recibir datos estructurados y desconectarse. No afirma que un modelo eligiera la herramienta correcta ni que un CAPTCHA de pago y una tarea del navegador se completaran.

A partir de esa base, conecta la operación de desafío que tu aplicación necesita y añade su prueba de aceptación. CapSolver proporciona la capacidad de resolución; la aplicación Mastra determina cuándo es apropiada y qué cuenta como trabajo completado. Prepara credenciales en tu panel de CapSolver antes de esa prueba de extremo a extremo por separado.

Preguntas frecuentes

P: ¿Puedo probar la conexión sin una clave de API de LLM?

Sí. El ejemplo llama directamente a una herramienta descubierta a través del cliente MCP de Mastra. No pide a un modelo de lenguaje que genere una respuesta ni que seleccione una herramienta.

P: ¿La consulta de capacidades es una resolución real de CAPTCHA?

No. Devuelve información de handlers registrados y tipos de CAPTCHA del servicio instalado. No valida una resolución de pago ni el estado de la página de un navegador.

P: ¿Por qué la herramienta se llama capsolver_get_supported_captchas?

El prefijo proviene de la clave de servidor capsolver. Mastra añade ese espacio de nombres al nombre de la herramienta remota en la lista aplanada.

P: ¿Debo poner a disposición de mi agente todas las herramientas descubiertas?

No. Selecciona las capacidades requeridas para la tarea asignada, luego prueba la selección y ejecución frente a los permisos y el flujo de trabajo de tu aplicación.

P: ¿Cuándo debo llamar a disconnect?

Desconéctate cuando no se necesiten más llamadas a través del cliente. Un diagnóstico de una sola ejecución puede cerrar en finally; un agente en ejecución necesita la conexión durante todo el uso de sus herramientas.

P: ¿Esto demuestra que mi flujo de trabajo de navegador en producción funcionará?

No. Verifica la integración y consulta local cliente-servidor. Producción aún necesita credenciales válidas, parámetros de tarea admitidos, un estado de navegador adecuado y una comprobación de aplicación de extremo a extremo.