Cómo habilitar agentes de Mastra AI con capacidad de acceso web en tiempo real.

Conclusiones Clave:

• Los agentes de Mastra son ciegos a la web en vivo hasta que conectas una herramienta: MCP es la forma más limpia de hacerlo. Un Agente de Mastra razona sobre su modelo y las herramientas que le proporcionas. Apúntalo al servidor MCP de Scrapeless y el agente obtendrá búsqueda en Google en vivo, renderización de JavaScript y un navegador en la nube completamente anti-detección sin necesidad de escribir un solo scraper a mano.
• Un MCPClient más await mcp.listTools() lo conecta todo. Construye un MCPClient con una entrada de servidor scrapeless, pasa await mcp.listTools() a new Agent({ tools }), y el agente obtiene un scraper de SERP de Google, un scraper de tendencias, ayudantes para HTML/Markdown/Capturas de pantalla y 16 herramientas de automatización de navegador, todo como herramientas tipadas de TypeScript.
• El agente busca, renderiza y controla un navegador a partir de simples instrucciones. Llama a agent.generate(...) o agent.stream(...) con una tarea en lenguaje natural y Mastra compone las llamadas a las herramientas de Scrapeless correspondientes turno a turno, en lugar de estar limitado al conocimiento hasta la fecha de corte de entrenamiento.
• Los proxies residenciales y la anti-detección se manejan del lado de la nube. Cada solicitud pasa a través del navegador en la nube anti-detección de Scrapeless con proxies residenciales en más de 195 países, por lo que el agente obtiene una respuesta renderizada y utilizable en sitios comerciales sin necesidad de configurar proxies o huellas digitales en tu máquina.
• 21 herramientas en SERP, scraping sin estado y automatización de navegadores. El servidor MCP de Scrapeless expone google_search, google_trends, scrape_html/scrape_markdown/scrape_screenshot, más 16 herramientas browser_* — nombradas como scrapeless_<tool> una vez que Mastra las carga, una superficie de la cual el planificador del agente extrae en cada turno.
• Transporte por stdio o HTTP-streamable. Inicia el servidor localmente con npx, o apunta el mismo MCPClient al punto final HTTP transmitible para funciones sin servidor, trabajadores remotos y ejecutores de CI.
• Gratis para empezar. Las nuevas cuentas de Scrapeless incluyen un tiempo de ejecución gratuito para el Navegador de Scraping: regístrate en app.scrapeless.com.

Introducción: un agente de TypeScript que finalmente puede leer la web en vivo

Mastra es un marco de trabajo de TypeScript de código abierto para construir agentes de IA. Defines un Agente con un modelo, un conjunto de instrucciones y las herramientas que puede llamar, y luego lo controlas desde tu propio código con agent.generate(...) o agent.stream(...). Es una forma limpia y segura de enviar agentes dentro de una aplicación Node o sin servidor. Lo que un agente de Mastra no puede hacer por sí solo es ver la web en vivo. Su conocimiento se detiene en el corte de entrenamiento del modelo y en las herramientas que le das explícitamente.

Mastra es deliberado acerca de ese límite: el alcance de un agente sobre el mundo es exactamente el conjunto de herramientas que adjuntas. Eso hace que la capa de herramientas sea el lugar para añadir acceso a la web en tiempo real, y el Protocolo de Contexto del Modelo (MCP) es la forma estándar y agnóstica de hacerlo. Mastra ofrece soporte de MCP de primera clase a través del paquete @mastra/mcp, por lo que cualquier servidor MCP se convierte en un conjunto de herramientas nativas y tipadas de Mastra. Hasta que conectes uno, el agente no puede obtener un SERP actual, leer la página de precios de un competidor, verificar el último changelog o renderizar una aplicación solo de JavaScript.

Esta publicación cierra esa brecha conectando el servidor MCP de Scrapeless en Mastra. Un solo MCPClient le da al agente búsqueda en Google, renderización de JavaScript y un navegador completo en la nube anti-detección, todo accesible a través de los mismos prompts en lenguaje natural que ya pasas a agent.generate(...). Para la misma superficie de Scrapeless a través de otro cliente MCP, consulta la integración de Pi Agent.

Lo Que Puedes Hacer Con Esto

• Investigación de SERP en vivo desde un agente de TypeScript. Pide al agente que ejecute google_search para una consulta y devuelva los principales resultados como JSON, de modo que la investigación ocurra dentro de tu aplicación en lugar de en una pestaña de navegador separada.
• Instantáneas de competidores y precios. Pasa una URL en el prompt y haz que el agente renderice la página y extraiga nombres de planes, precios y características en un registro estructurado que tu código puede persistir.
• Búsquedas de documentos y changelogs que alimentan código. Haz que el agente obtenga la documentación actual de una biblioteca o notas de lanzamiento como markdown limpio y razone con el texto renderizado en lugar de una memoria obsoleta de la API.
• Verificaciones de mercado y tendencias. Usa google_trends para obtener señales de interés sobre un tema en una región objetivo, luego alimenta copias de características, planes de contenido o ideas de experimentos con evidencia actual.
• Extracción de páginas JavaScript en un registro tipado. Apunta al agente a una aplicación de una sola página; el navegador en la nube la hidrata y el agente analiza el resultado en un objeto tipado que tu flujo de trabajo consume.
• Flujos de navegador de múltiples pasos. Encadena browser_goto, browser_click, browser_type y browser_scroll para que el agente navegue por la paginación, expanda paneles o pase por un asistente antes de extraer.
• Captura de pantalla para revisión. Utiliza scrape_screenshot o browser_screenshot para capturar una página renderizada como una imagen que el agente puede devolver a tu aplicación.
• Pipelines de buscar-y-luego-leer. Combina google_search con scrape_markdown para que el agente encuentre los mejores resultados, lea cada uno y los resuma en una sola acción del agente.

Por qué el servidor MCP de Scrapeless

El servidor MCP de Scrapeless es un puente personalizable y anti-detección entre un agente de IA y la web en vivo. Para Mastra específicamente, ofrece:

• Un navegador en la nube anti-detección con renderizado de JavaScript. Las páginas se hidratan en un Navegador de Scraping Scrapeless completo antes de la extracción, por lo que las SPAs, los feeds de desplazamiento infinito y los paneles cargados de manera perezosa se convierten en objetivos de primera clase para browser_goto + browser_get_html.
• Proxies residenciales en más de 195 países. Las consultas geolocalizadas devuelven las listas que un usuario local vería, con la salida del proxy manejada completamente en el lado de Scrapeless.
• Un comando stdio a través de npx, sin código de scraper. El servidor se inicia como un proceso hijo de npx -y scrapeless-mcp-server; no hay nada que construir, hospedar o importar a tu proyecto más allá del MCPClient.
• 21 herramientas que abarcan SERP, scraping sin estado y automatización de navegador completa. google_search y google_trends cubren datos de SERP, scrape_html/scrape_markdown/scrape_screenshot cubren la recuperación de páginas en un solo paso, y 16 herramientas browser_* cubren navegación con estado, clics, escritura, desplazamiento y capturas de pantalla.
• Las herramientas llegan como herramientas nativas de Mastra. Debido a que @mastra/mcp adapta las herramientas de MCP al propio tipo de herramienta de Mastra, la superficie de Scrapeless se presenta exactamente como cualquier herramienta que escribirías a mano: tipada, con nombres de espacio y lista para el planificador del agente.

El plan gratuito es suficiente para configurar todo esto y ejecutar comandos reales; compara las cuotas en la página de precios cuando superes esto. Obtén tu clave API en el plan gratuito en app.scrapeless.com.

Requisitos previos

• Node.js 18 o más reciente en la estación de trabajo — Mastra se dirige a Node moderno, y el servidor MCP se inicia con npx.
• Un proyecto Mastra con un proveedor de modelos configurado. El Agente de Mastra toma un modelo; el bucle del agente necesita un modelo funcional del proveedor que configures antes de que se ejecute cualquier llamada a la herramienta.
• Una cuenta de Scrapeless y clave API — regístrate en el plan gratuito en app.scrapeless.com y copia la clave desde Configuración → Gestión de Claves API.
• Familiaridad básica con TypeScript — toda la configuración consiste en dos paquetes más una pequeña definición de MCPClient.

Conectar Scrapeless a Mastra

La configuración consiste en cinco pasos; cada uno es verificable de manera independiente.

1. Instalar los paquetes MCP y core de Mastra

Agrega el paquete del cliente MCP y el núcleo del agente a tu proyecto:

npm install @mastra/mcp @mastra/core

@mastra/mcp proporciona la clase MCPClient que se conecta a los servidores MCP, y @mastra/core proporciona la clase Agente a la que adjuntas las herramientas.

2. Configurar el MCPClient (stdio)

Crea un MCPClient con una única entrada de servidor scrapeless. Cuando hay un comando presente, Mastra detecta automáticamente el transporte stdio y lanza el servidor como un proceso hijo:

// npm install @mastra/mcp @mastra/core
import { MCPClient } from "@mastra/mcp";

const mcp = new MCPClient({
  id: "scrapeless-client",
  servers: {
    scrapeless: {
      command: "npx",
      args: ["-y", "scrapeless-mcp-server"],
      env: { SCRAPELESS_KEY: process.env.SCRAPELESS_KEY! },
    },
  },
});

Un detalle importa aquí: el servidor MCP de Scrapeless lee su clave de SCRAPELESS_KEY, no de SCRAPELESS_API_KEY — el CLI y el SDK de Scrapeless utilizan SCRAPELESS_API_KEY, pero el servidor MCP es la excepción documentada. Mantén la clave en tu entorno (export SCRAPELESS_KEY=...) y pásala a través del objeto env en lugar de codificarla directamente. El código fuente del servidor se encuentra en github.com/scrapeless-ai/scrapeless-mcp-server.

3. O utiliza transporte HTTP-streamable

Si el host no puede iniciar npx de manera confiable — una función serverless, un trabajador remoto o un entorno de CI — apunta el mismo MCPClient al endpoint HTTP de Scrapeless en lugar del proceso local. Pasa una url y establece la clave como un encabezado a través de requestInit:

const mcp = new MCPClient({
  servers: {
    scrapeless: {
      url: new URL("https://api.scrapeless.com/mcp"),
      requestInit: { headers: { "x-api-token": process.env.SCRAPELESS_KEY! } },
    },
  },
});

Cuando proporcionas una url, Mastra intenta primero HTTP transmisible y automáticamente se retrocede al transporte SSE heredado. El mismo valor de clave funciona en ambos modos; HTTP-transmisible lo pasa como el encabezado x-api-token en lugar de la variable de entorno SCRAPELESS_KEY. Stdio es el predeterminado adecuado en una estación de trabajo de desarrollo; HTTP-transmisible es el predeterminado correcto en cualquier lugar donde un proceso secundario de larga duración sea incómodo de mantener vivo.

4. Adjuntar las herramientas a un Agente

Carga las herramientas con await mcp.listTools() y pásalas directamente a un nuevo Agente. Con este enfoque estático, las herramientas se resuelven una vez en la construcción y se nombran como serverName_toolName:

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "web-agent",
  name: "Agente Consciente de la Web",
  instructions: "Usa las herramientas de Scrapeless para buscar y leer la web en vivo.",
  model: "<tu-modelo-de-proveedor>",
  tools: await mcp.listTools(), // -> scrapeless_google_search, scrapeless_scrape_markdown, scrapeless_browser_* ...
});

Usa el modelo que tu proveedor expone; el Agente de Mastra acepta cualquier id de modelo de proveedor, y no se requiere un modelo o versión específica para que las herramientas funcionen.

Para una alternativa dinámica, Mastra también ofrece await mcp.listToolsets(), que resuelve herramientas por llamada y las nombra como serverName.toolName. Pasa los conjuntos de herramientas en el momento de la llamada en lugar de en la construcción:

const result = await agent.stream(prompt, {
  toolsets: await mcp.listToolsets(),
});

listTools() es el camino más simple cuando un cliente sirve toda la aplicación; listToolsets() se adapta a configuraciones de múltiples inquilinos donde cada solicitud puede llevar diferentes credenciales o selecciones de servidor. Usa await mcp.disconnect() para limpiar cuando hayas terminado con el cliente.

5. Verifica enumerando las 21 herramientas

Resolver las herramientas e inspeccionar sus claves confirmará que el apretón de manos se completó y el servidor está reportando su superficie completa:

const tools = await mcp.listTools();
console.log(Object.keys(tools));

La salida lista las 21 herramientas del servidor, cada una con el prefijo scrapeless_<tool> — las herramientas de datos de Google (scrapeless_google_search, scrapeless_google_trends), los ayudantes de página de una sola vez (scrapeless_scrape_html, scrapeless_scrape_markdown, scrapeless_scrape_screenshot), y las primitivas de navegador en la nube (scrapeless_browser_create, scrapeless_browser_goto, scrapeless_browser_get_html, scrapeless_browser_get_text, scrapeless_browser_click, scrapeless_browser_type, scrapeless_browser_press_key, scrapeless_browser_scroll, scrapeless_browser_scroll_to, scrapeless_browser_screenshot, scrapeless_browser_snapshot, scrapeless_browser_wait, scrapeless_browser_wait_for, scrapeless_browser_go_back, scrapeless_browser_go_forward, scrapeless_browser_close).

Cómo usar esto realmente: incita a tu agente Mastra

Después de conectar el servidor MCP, obtienes datos de la web en vivo llamando al agente en tu código — no escribiendo manualmente las llamadas a las herramientas. El agente lee la lista de herramientas que expone el servidor Scrapeless MCP y elige scrapeless_google_search, scrapeless_scrape_markdown, o las herramientas scrapeless_browser_* según sea necesario, componiéndolas una por una a partir de la tarea en lenguaje natural. No hay un JSON de herramientas para autorizar de tu lado. Diriges un turno único con agent.generate(prompt), o transmites la ejecución token por token con agent.stream(prompt).

Prompts que puedes pegar

Ejemplo práctico

Tú escribes (una sola llamada en tu aplicación TypeScript):

const result = await agent.generate(
"Usa la herramienta de búsqueda de Google Scrapeless para encontrar los mejores resultados para 'mastra ai github' y devuelve los 3 principales como un array JSON de {título, enlace}."
- Los argumentos de la herramienta están en camelCase: pasa `sessionId`, `proxyCountry` y campos similares exactamente como están nombrados.
- `proxyCountry` es una solicitud, no una garantía — puede deferir a la región configurada en tu cuenta, así que confirma la región de salida cuando el geo-targeting importa.
- Los valores en la salida de la herramienta dependen del contenido: los recuentos de resultados, el orden y el texto del fragmento varían con la consulta en vivo.

---

## Conclusión: busca, renderiza y navega desde TypeScript

Toda la integración se reduce a un `MCPClient` más prompts en lenguaje natural. Con una entrada de servidor `scrapeless`, `await mcp.listTools()` entregado a `new Agent({ tools })`, y tu clave en `SCRAPELESS_KEY`, un agente de Mastra obtiene búsqueda en vivo de Google, renderizado de JavaScript y un navegador en la nube completo anti-detección — exactamente la capa web que el agente no proporciona por sí mismo. Tú describes la tarea; el agente elige la herramienta.

Si estás conectando otros agentes, el mismo servidor MCP Scrapeless se integra también en ellos: consulta la [integración del Pi Agent](https://www.scrapeless.com/es/blog/pi-agent-scrapeless-mcp?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp) y la [visión general del servidor MCP Scrapeless](https://www.scrapeless.com/es/blog/scrapeless-mcp-server?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp) para toda la referencia de herramientas. Mantén tu clave API en `SCRAPELESS_KEY`, prefiere el transporte stdio para desarrollo local y HTTP-streamable para entornos alojados, elige `listTools()` para un solo cliente estático o `listToolsets()` para conjuntos dinámicos por llamada, y deja que el agente elija las herramientas. Referencia completa en [docs.scrapeless.com](https://docs.scrapeless.com?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp).

---

## ¿Listo para construir tu canal de datos impulsado por IA?

Únete a nuestra comunidad para reclamar un plan gratuito y conectarte con desarrolladores que construyen agentes Mastra + Scrapeless MCP: [Discord](https://discord.gg/VU2vtbq7Q2) · [Telegram](https://t.me/scrapeless).

Regístrate en [app.scrapeless.com](https://app.scrapeless.com/passport/login/?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp) para obtener tiempo de ejecución gratuito del Scraping Browser y adapta la integración anterior a los SERPs, páginas y regiones que tu equipo necesita. Referencia completa en [docs.scrapeless.com](https://docs.scrapeless.com?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp).

---

## Preguntas Frecuentes

### P: ¿Por qué un agente Mastra necesita un servidor MCP para acceder a la web?
Porque un `Agent` de Mastra solo puede llamar a las herramientas que le asocies, y no tiene búsqueda web o navegador incorporado. MCP es la forma estándar y agnóstica de frameworks para agregar esa capacidad, y `@mastra/mcp` adapta cualquier servidor MCP en herramientas nativas de Mastra. Conectar Scrapeless le da al agente búsqueda en vivo de Google, acceso a páginas renderizadas y un navegador en la nube completo anti-detección en un solo movimiento.

### P: ¿Cuál es la diferencia entre `listTools()` y `listToolsets()`?
`await mcp.listTools()` resuelve las herramientas una vez y las devuelve con prefijo `serverName_toolName` (por ejemplo, `scrapeless_google_search`); pasas el resultado a `new Agent({ tools })` al construir. `await mcp.listToolsets()` resuelve herramientas por llamada y las agrupa como `serverName.toolName`; pasas el resultado en el momento de la llamada a través de `agent.stream(prompt, { toolsets })` o `agent.generate(prompt, { toolsets })`. Usa `listTools()` para un solo cliente estático y `listToolsets()` cuando cada solicitud puede llevar diferentes credenciales o selecciones de servidor.

### P: ¿Qué variable de entorno guarda la clave de Scrapeless?
`SCRAPELESS_KEY`. Esta es la excepción documentada: el CLI y SDK de Scrapeless leen `SCRAPELESS_API_KEY`, pero el servidor MCP lee `SCRAPELESS_KEY`. En la configuración stdio, la pasas a través del objeto `env` como `process.env.SCRAPELESS_KEY`; en modo HTTP-streamable envías el mismo valor como el encabezado `x-api-token`.

### P: ¿stdio vs HTTP-streamable — cuándo deberías usar cada uno?
Usa stdio cuando el servidor se ejecute localmente junto a tu aplicación: Mastra lanza `scrapeless-mcp-server` como un proceso hijo y se comunica con él a través de la entrada/salida estándar. Usa HTTP-streamable (una `url` de `https://api.scrapeless.com/mcp` con el encabezado `x-api-token` a través de `requestInit`) cuando el entorno de ejecución sea sin servidor o remoto y no pueda mantener un proceso hijo local vivo. Cuando suministras una `url`, Mastra intenta primero Streamable HTTP y retrocede automáticamente a SSE legado.

### P: ¿Esto requiere un modelo específico?
No. El `Agent` de Mastra acepta cualquier id de modelo de proveedor, por lo que usas el modelo que tu proveedor expone. Las herramientas de Scrapeless son agnósticas al modelo; elige un modelo que maneje bien las llamadas a herramientas, y el agente compone las herramientas de Scrapeless de la misma manera sin importar el proveedor.

### P: ¿Cómo terminan las herramientas tipificadas en mi proyecto?
`@mastra/mcp` adapta cada herramienta MCP al propio tipo de herramienta de Mastra, por lo que las herramientas Scrapeless aparecen exactamente como herramientas que escribirías a mano, con espacios de nombres y listas para el planificador del agente. Las conectas a través de `tools: await mcp.listTools()` y nunca defines el JSON de la herramienta tú mismo.

### P: ¿Es legal el web scraping a través del agente?
Raspar datos disponibles públicamente es generalmente permisible, pero eres responsable de cómo los utilizas. Revisa los Términos de Servicio de cada sitio y respeta robots.txt, y recuerda que las reglas sobre datos personales y acceso varían según la jurisdicción. Cuando tengas dudas, obtén asesoría legal para tu caso de uso específico.

### P: ¿Puedes usar esto sin Mastra?
Sí. El servidor MCP de Scrapeless es un servidor MCP estándar, por lo que cualquier cliente compatible con MCP puede llamarlo, o puedes controlarlo directamente a través de JSON-RPC (`initialize`, luego `tools/list` y `tools/call`). Mastra es una conveniencia para aplicaciones TypeScript, no un requisito.