Como habilitar agentes de IA Mastra com capacidade de acesso à web em tempo real

Principais Conclusões:

• Agentes Mastra não têm acesso à web ao vivo até que você conecte uma ferramenta — MCP é o caminho mais limpo. Um Agente Mastra raciocina sobre seu modelo e sobre quaisquer ferramentas que você lhe fornecer. Aponte para o servidor Scrapeless MCP e o agente ganha pesquisa Google ao vivo, renderização em JavaScript e um navegador em nuvem completo de anti-deteção sem precisar escrever um único scraper à mão.
• Um MCPClient mais await mcp.listTools() conecta tudo. Construa um MCPClient com uma entrada de servidor scrapeless, passe await mcp.listTools() para new Agent({ tools }), e o agente obtém um scraper de SERP do Google, um scraper de Tendências, ajudantes de HTML/Markdown/Captura de tela, e 16 ferramentas de automação de navegador — todas como ferramentas tipadas em TypeScript.
• O agente pesquisa, renderiza e controla um navegador a partir de comandos simples. Chame agent.generate(...) ou agent.stream(...) com uma tarefa em linguagem natural e o Mastra compõe as chamadas corretas das ferramentas Scrapeless, uma por uma, em vez de ficar limitado ao conhecimento até o ponto de corte do treinamento.
• Proxies residenciais e anti-deteção são tratados do lado da nuvem. Cada solicitação passa pelo navegador em nuvem de anti-deteção Scrapeless com proxies residenciais em mais de 195 países, então o agente recebe uma resposta renderizada e utilizável em sites comerciais sem necessidade de qualquer configuração de proxy ou impressão digital em sua máquina.
• 21 ferramentas em SERP, scraping sem estado e automação de navegador. O servidor Scrapeless MCP expõe google_search, google_trends, scrape_html/scrape_markdown/scrape_screenshot, além de 16 ferramentas browser_* — namespaces scrapeless_<tool> uma vez que o Mastra as carrega, uma base que o planejador do agente extrai a cada turno.
• Transporte via stdio ou HTTP-streamable. Inicie o servidor localmente com npx, ou aponte o mesmo MCPClient para o endpoint HTTP transmissível para funções serverless, trabalhadores remotos e runners de CI.
• Gratuito para começar. Novas contas Scrapeless incluem um tempo de execução de Scraping Browser gratuito — inscreva-se em app.scrapeless.com.

Introdução: um agente TypeScript que pode finalmente ler a web ao vivo

Mastra é um framework TypeScript de código aberto para construir agentes de IA. Você define um Agente com um modelo, um conjunto de instruções e as ferramentas que ele pode chamar, e depois controla isso a partir do seu próprio código com agent.generate(...) ou agent.stream(...). É uma maneira limpa e segura em termos de tipo de enviar agentes dentro de um app Node ou serverless. O que um agente Mastra não pode fazer por conta própria é ver a web ao vivo. Seu conhecimento para no ponto de corte do treinamento do modelo e nas ferramentas que você explicitamente lhe forneceu.

Mastra é deliberada sobre esse limite: o alcance de um agente sobre o mundo é exatamente o conjunto de ferramentas que você anexa. Isso faz da camada de ferramentas o lugar para adicionar acesso à web em tempo real — e o Protocolo de Contexto do Modelo (MCP) é a maneira padrão e independente do framework de fazer isso. Mastra oferece suporte de primeira classe ao MCP por meio do pacote @mastra/mcp, então qualquer servidor MCP se torna um conjunto de ferramentas Mastra nativas e tipadas. Até que você conecte um, o agente não consegue puxar um SERP atual, ler a página de preços de um concorrente, verificar o changelog mais recente ou renderizar um aplicativo somente JavaScript.

Este post fecha essa lacuna conectando o servidor Scrapeless MCP ao Mastra. Um único MCPClient dá ao agente pesquisa no Google, renderização em JavaScript e um navegador em nuvem completo de anti-deteção, tudo acessível por meio dos mesmos comandos em linguagem natural que você já passa para agent.generate(...). Para a mesma superfície Scrapeless através de outro cliente MCP, veja a integração do Pi Agent.

O Que Você Pode Fazer Com Isso

• Pesquisa de SERP ao vivo de um agente TypeScript. Peça ao agente para executar google_search para uma consulta e devolva os principais resultados como JSON, assim a pesquisa acontece dentro do seu app em vez de em uma aba separada do navegador.
• Capturas de concorrentes e preços. Passe uma URL no comando e faça com que o agente renderize a página e extraia nomes de planos, preços e recursos em um registro estruturado que seu código pode persistir.
• Pesquisas de documentos e changelog que alimentam o código. Faça com que o agente busque a documentação atual de uma biblioteca ou notas de lançamento como markdown limpo e raciocine sobre o texto renderizado em vez de uma memória antiga da API.
• Verificações de mercado e tendências. Use google_trends para puxar sinais de interesse para um tópico em uma região alvo, então use como base para cópias de recursos, planos de conteúdo ou ideias de experimentos com evidências atuais.
• Extração de páginas JavaScript em um registro tipado. Aponte o agente para um aplicativo de página única; o navegador em nuvem o hidrata e o agente analisa o resultado em um objeto tipado que seu fluxo de trabalho consome.
• Fluxos de navegação de múltiplos passos. Encadeie browser_goto, browser_click, browser_type e browser_scroll para que o agente navegue na paginação, expanda painéis ou passe por um assistente antes de extrair.
• Captura de tela para revisão. Use scrape_screenshot ou browser_screenshot para capturar uma página renderizada como uma imagem que o agente pode retornar ao seu aplicativo.
• Pipelines de busca-e-leitura. Combine google_search com scrape_markdown para que o agente encontre os principais resultados, leia cada um e resuma-os em uma única interação do agente.

Por que o Servidor MCP Scrapeless

O servidor MCP Scrapeless é uma ponte personalizável e anti-detecção entre um agente de IA e a web ao vivo. Para a Mastra especificamente, ele traz:

• Um navegador em nuvem anti-detecção com renderização JavaScript. As páginas são hidratadas em um Navegador de Scraping Scrapeless completo antes da extração, assim SPAs, feeds de rolagem infinita e painéis carregados sob demanda se tornam alvos de primeira linha para browser_goto + browser_get_html.
• Proxies residenciais em mais de 195 países. Consultas geo-limitação retornam as listagens que um usuário local veria, com a saída do proxy tratada inteiramente do lado Scrapeless.
• Um comando stdio via npx, sem código de scraper. O servidor é iniciado como um processo filho a partir do npx -y scrapeless-mcp-server; não há nada a construir, hospedar ou importar para o seu projeto além do MCPClient.
• 21 ferramentas abrangendo SERP, scraping sem estado e automação de navegador completo. google_search e google_trends cobrem dados de SERP, scrape_html/scrape_markdown/scrape_screenshot cobrem buscas de páginas de uma só vez, e 16 ferramentas browser_* cobrem navegação com estado, cliques, digitação, rolagem e capturas de tela.
• As ferramentas chegam como ferramentas nativas da Mastra. Porque @mastra/mcp adapta ferramentas MCP ao próprio tipo de ferramenta da Mastra, a superfície Scrapeless aparece exatamente como qualquer ferramenta que você escreveria manualmente — digitada, com namespace, e pronta para o planejador do agente.

O plano gratuito é suficiente para configurar isso e executar prompts reais; compare as cotas na página de preços quando você ultrapassar isso. Obtenha sua chave de API no plano gratuito em app.scrapeless.com.

Pré-requisitos

• Node.js 18 ou mais recente na estação de trabalho — a Mastra almeja o Node moderno, e o servidor MCP stdio é gerado com npx.
• Um projeto Mastra com um provedor de modelo configurado. O Agente da Mastra requer um modelo; o loop do agente precisa de um modelo funcional de qualquer provedor que você conecte antes que qualquer chamada de ferramenta seja executada.
• Uma conta Scrapeless e chave de API — inscreva-se no plano gratuito em app.scrapeless.com e copie a chave de Configurações → Gerenciamento de Chaves de API.
• Familiaridade básica com TypeScript — toda a configuração consiste em dois pacotes mais uma pequena definição de MCPClient.

Conecte o Scrapeless à Mastra

A configuração é feita em cinco etapas; cada uma pode ser verificada de forma independente.

1. Instale os pacotes Mastra MCP e core

Adicione o pacote do cliente MCP e o core do agente ao seu projeto:

npm install @mastra/mcp @mastra/core

@mastra/mcp fornece a classe MCPClient que se conecta aos servidores MCP, e @mastra/core fornece a classe Agent à qual você anexa as ferramentas.

2. Configure o MCPClient (stdio)

Crie um MCPClient com uma única entrada de servidor scrapeless. Quando um comando estiver presente, a Mastra detecta automaticamente o transporte stdio e inicia o servidor como um processo filho:

// 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! },
    },
  },
});

Um detalhe é importante aqui: o servidor MCP Scrapeless lê sua chave de SCRAPELESS_KEY, não SCRAPELESS_API_KEY — o CLI e SDK do Scrapeless usam SCRAPELESS_API_KEY, mas o servidor MCP é a exceção documentada. Mantenha a chave em seu ambiente (export SCRAPELESS_KEY=...) e passe-a através do objeto env em vez de codificá-la. O código fonte do servidor está em github.com/scrapeless-ai/scrapeless-mcp-server.

3. Ou use transporte HTTP-streamable

Se o host não puder iniciar npx de forma confiável — uma função serverless, um trabalhador remoto ou um sandbox CI — aponte o mesmo MCPClient para o endpoint HTTP Scrapeless em vez do processo local. Passe uma url e defina a chave como um cabeçalho atravé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! } },
    },
  },
});

Quando você fornece uma url, o Mastra tenta o HTTP streamable primeiro e recua automaticamente para o transporte SSE legado. O mesmo valor de chave funciona em ambos os modos; o HTTP streamable o passa como o cabeçalho x-api-token em vez da variável de ambiente SCRAPELESS_KEY. Stdio é o padrão certo em uma estação de trabalho de desenvolvedor; HTTP streamable é o padrão certo em qualquer lugar onde um processo filho de longa duração é difícil de manter ativo.

4. Anexe as ferramentas a um Agente

Carregue as ferramentas com await mcp.listTools() e passe-as diretamente para um novo Agent. Com esta abordagem estática, as ferramentas são resolvidas uma vez na construção e com o namespace serverName_toolName:

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

const agent = new Agent({
  id: "web-agent",
  name: "Agente Consciente da Web",
  instructions: "Use as ferramentas Scrapeless para pesquisar e ler a web ao vivo.",
  model: "<seu-modelo-fornecedor>",
  tools: await mcp.listTools(), // -> scrapeless_google_search, scrapeless_scrape_markdown, scrapeless_browser_* ...
});

Utilize o modelo que seu fornecedor expõe — o Agent do Mastra aceita qualquer id de modelo de fornecedor, e nenhum modelo ou versão específica é necessária para as ferramentas funcionarem.

Para uma alternativa dinâmica, o Mastra também oferece await mcp.listToolsets(), que resolve as ferramentas por chamada e as namespaceia como serverName.toolName. Passe os conjuntos de ferramentas no momento da chamada em vez de na construção:

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

listTools() é o caminho mais simples quando um cliente serve todo o aplicativo; listToolsets() é adequado para configurações multi-tenant onde cada solicitação pode ter credenciais ou seleções de servidor diferentes. Use await mcp.disconnect() para limpar quando você terminar com o cliente.

5. Verifique enumerando as 21 ferramentas

Resolver as ferramentas e inspecionar suas chaves confirma que o handshake foi concluído e que o servidor está relatando sua superfície completa:

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

A saída lista as 21 ferramentas do servidor, cada uma namespaceada como scrapeless_<tool> — as ferramentas de dados do Google (scrapeless_google_search, scrapeless_google_trends), os ajudantes de página de uma só vez (scrapeless_scrape_html, scrapeless_scrape_markdown, scrapeless_scrape_screenshot), e os primitivos de navegador em nuvem (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).

Como você realmente usa isso: solicite ao seu agente Mastra

Após conectar o servidor MCP, você obtém dados da web ao vivo chamando o agente em seu código — não escrevendo chamadas de ferramentas manualmente. O agente lê a lista de ferramentas que o servidor MCP Scrapeless expõe e escolhe scrapeless_google_search, scrapeless_scrape_markdown ou as ferramentas scrapeless_browser_* conforme necessário, compondo-as uma a uma a partir da tarefa em linguagem natural. Não há JSON de ferramenta a ser criado do seu lado. Você conduz uma única execução com agent.generate(prompt) ou faz streaming do token execução por execução com agent.stream(prompt).

Prompts que você pode colar

Exemplo prático

Você escreve (uma única chamada em seu aplicativo TypeScript):

const result = await agent.generate(
"Use a ferramenta de busca google_search da Scrapeless para encontrar os principais resultados para 'mastra ai github' e retornar os 3 melhores como um array JSON de {título, link}."
- Os argumentos da ferramenta estão em camelCase: passe `sessionId`, `proxyCountry` e campos semelhantes exatamente como nomeados.
- `proxyCountry` é um pedido, não uma garantia — pode se referir à região configurada na sua conta, portanto, confirme a região de saída quando o geo-targeting for importante.
- Os valores na saída da ferramenta dependem do conteúdo: contagem de resultados, ordenação e texto dos snippets variam com a consulta ao vivo.

---

## Conclusão: buscar, renderizar e navegar a partir do TypeScript

Toda a integração se resume a um `MCPClient` mais prompts em linguagem natural. Com uma entrada de servidor `scrapeless`, `await mcp.listTools()` entregue a `new Agent({ tools })` e sua chave em `SCRAPELESS_KEY`, um agente Mastra ganha busca ao vivo no Google, renderização em JavaScript e um navegador em nuvem completo contra detecção — exatamente a camada web que o agente não possui por conta própria. Você descreve a tarefa; o agente escolhe a ferramenta.

Se você estiver conectando outros agentes, o mesmo servidor MCP Scrapeless se integra a eles também: veja a [integração do agente Pi](https://www.scrapeless.com/pt/blog/pi-agent-scrapeless-mcp?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp) e a [visão geral do servidor MCP Scrapeless](https://www.scrapeless.com/pt/blog/scrapeless-mcp-server?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp) para a referência completa da ferramenta. Mantenha sua chave de API em `SCRAPELESS_KEY`, prefira transporte stdio para desenvolvimento local e HTTP-streamable para tempos de execução hospedados, escolha `listTools()` para um único cliente estático ou `listToolsets()` para conjuntos dinâmicos por chamada, e deixe o agente escolher as ferramentas. Referência completa em [docs.scrapeless.com](https://docs.scrapeless.com?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp).

---

## Pronto para Construir Seu Pipeline de Dados Potenciado por IA?

Junte-se à nossa comunidade para reivindicar um plano gratuito e conectar-se com desenvolvedores que estão construindo agentes Mastra + Scrapeless MCP: [Discord](https://discord.gg/VU2vtbq7Q2) · [Telegram](https://t.me/scrapeless).

Inscreva-se em [app.scrapeless.com](https://app.scrapeless.com/passport/login/?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp) para obter tempo de execução gratuito do navegador de scraping e adapte a integração acima aos SERPs, páginas e regiões que sua equipe precisa. Referência completa em [docs.scrapeless.com](https://docs.scrapeless.com?utm_source=website&utm_medium=blog&utm_campaign=aiagent&utm_term=mastra-scrapeless-mcp).

---

## FAQ

### Q: Por que um agente Mastra precisa de um servidor MCP para acesso à web?
Porque um `Agente` Mastra só pode chamar as ferramentas que você anexa a ele, e ele não possui busca web ou navegador embutido. O MCP é a maneira padrão, independente de framework, de adicionar essa capacidade, e `@mastra/mcp` adapta qualquer servidor MCP em ferramentas nativas do Mastra. Conectar o Scrapeless dá ao agente busca ao vivo no Google, acesso a páginas renderizadas e um navegador em nuvem completo contra-detecção em um único movimento.

### Q: Qual é a diferença entre `listTools()` e `listToolsets()`?
`await mcp.listTools()` resolve as ferramentas uma vez e as retorna nomeadas `serverName_toolName` (por exemplo, `scrapeless_google_search`); você passa o resultado para `new Agent({ tools })` na construção. `await mcp.listToolsets()` resolve as ferramentas por chamada e as nomeia `serverName.toolName`; você passa o resultado no momento da chamada via `agent.stream(prompt, { toolsets })` ou `agent.generate(prompt, { toolsets })`. Use `listTools()` para um único cliente estático e `listToolsets()` quando cada solicitação pode ter diferentes credenciais ou seleções de servidor.

### Q: Qual variável de ambiente contém a chave do Scrapeless?
`SCRAPELESS_KEY`. Esta é a exceção documentada — o CLI e o SDK do Scrapeless leem `SCRAPELESS_API_KEY`, mas o servidor MCP lê `SCRAPELESS_KEY`. Na configuração stdio, você a passa através do objeto `env` como `process.env.SCRAPELESS_KEY`; no modo HTTP-streamable, você envia o mesmo valor como o cabeçalho `x-api-token`.

### Q: stdio vs HTTP-streamable — quando você deve usar cada um?
Use stdio quando o servidor roda localmente ao lado do seu aplicativo: o Mastra inicia `scrapeless-mcp-server` como um processo filho e se comunica com ele através da entrada/saída padrão. Use HTTP-streamable (uma `url` de `https://api.scrapeless.com/mcp` com o cabeçalho `x-api-token` via `requestInit`) quando o tempo de execução for sem servidor ou remoto e não puder manter um processo filho local vivo. Quando você fornece uma `url`, o Mastra tenta primeiro o HTTP Streamable e volta automaticamente para o SSE legado.

### Q: Isso requer um modelo específico?
Não. O `Agente` do Mastra aceita qualquer id de modelo de provedor, para que você use o modelo que seu provedor expõe. As ferramentas do Scrapeless são independentes de modelo; escolha um modelo que lide bem com chamadas de ferramentas, e o agente compõe as ferramentas do Scrapeless da mesma forma, independentemente do provedor.

### Q: Como as ferramentas terminam tipadas no meu projeto?
`@mastra/mcp` adapta cada ferramenta MCP ao próprio tipo de ferramenta da Mastra, de modo que as ferramentas Scrapeless apareçam exatamente como ferramentas que você escreveria manualmente — com namespace e prontas para o planejador do agente. Você as conecta através de `tools: await mcp.listTools()` e nunca cria o JSON da ferramenta você mesmo.

### P: A captura de dados da web via agente é legal?
Capturar dados disponíveis publicamente é geralmente permitido, mas você é responsável por como os utiliza. Revise os Termos de Serviço de cada site e respeite o robots.txt, e lembre-se de que as regras sobre dados pessoais e acesso variam de acordo com a jurisdição. Quando em dúvida, procure aconselhamento jurídico para seu caso específico.

### P: Você pode usar isso sem a Mastra?
Sim. O servidor MCP Scrapeless é um servidor MCP padrão, então qualquer cliente compatível com MCP pode chamá-lo — ou você pode controlá-lo diretamente via JSON-RPC (`initialize`, depois `tools/list` e `tools/call`). A Mastra é uma conveniência para aplicativos TypeScript, não uma exigência.