Vercel AI SDK + Scrapeless: Ferramentas Web para Seus Agentes via MCP

Resumo:

• O Vercel AI SDK se conecta ao Scrapeless MCP Server com createMCPClient de @ai-sdk/mcp, passando o endpoint e o cabeçalho x-api-token na configuração de transporte.
• await client.tools() retorna todas as 21 ferramentas — scrape_markdown, scrape_html, google_search, google_trends, scrape_screenshot, e um conjunto de 16 ferramentas browser_* — indexadas por nome, prontas para serem utilizadas em generateText.
• No AI SDK 5 e posteriores, o cliente MCP está em seu próprio pacote: importe createMCPClient de @ai-sdk/mcp, não experimental_createMCPClient de ai, que foi removido.
• Cada ferramenta expõe um método execute, então você pode chamar tools.scrape_markdown.execute({ url }) diretamente e ler o Markdown antes que um modelo esteja envolvido — nenhuma chave de modelo é necessária para carregar ou chamar ferramentas.
• Apenas o passo generateText precisa de uma chave de provedor de modelo, porque é onde o modelo decide quais ferramentas chamar.
• Comece com o plano gratuito do Scrapeless e dê aos seus agentes TypeScript ferramentas web reais.

O Vercel AI SDK é o toolkit padrão para construir aplicativos de IA em TypeScript, e um modelo dentro dele só pode agir através das ferramentas que você fornece. Nada no SDK base alcança a web ao vivo. O Protocolo de Contexto de Modelo fecha essa lacuna: aponte o cliente MCP do SDK para um servidor e cada ferramenta que esse servidor expõe torna-se uma ferramenta do SDK de IA que você pode utilizar diretamente em generateText ou streamText.

Este guia conecta o SDK de IA ao Scrapeless MCP Server, carrega suas 21 ferramentas, chama uma de verdade, e então passa o conjunto a um modelo — verificado contra o endpoint ao vivo. O único passo que precisa de uma chave de provedor de modelo é a chamada de geração, e este post marca exatamente onde essa linha se encontra.

O que o Scrapeless MCP Server fornece a um agente

O Scrapeless MCP Server expõe ferramentas de web scraping e navegador que um agente pode chamar diretamente, então a camada de scraping não é algo que você construa ou hospede. Uma conexão fornece 21 ferramentas: scrape_markdown e scrape_html para conteúdo de página, google_search e google_trends para dados de busca, scrape_screenshot para capturas, e um conjunto de 16 ferramentas browser_* que controla um navegador na nuvem através de cliques, digitação, rolagem, e esperas.

As ferramentas browser_* são executadas no navegador na nuvem Scrapeless, assim um modelo pode navegar em uma página interativa e ler o que realmente é renderizado sem um navegador na sua máquina. Para o próprio protocolo, O que é MCP é a explicação, e LangChain + Scrapeless MCP conecta o mesmo servidor a uma pilha Python.

Pré-requisitos

• Node.js 22 ou posterior.
• Uma chave da API Scrapeless do painel, exportada como SCRAPELESS_API_KEY.
• Uma chave de provedor de modelo como OPENAI_API_KEY apenas para o passo de geração. Carregar e chamar as ferramentas não precisa de uma.

Instalação

Instale o núcleo do AI SDK e o pacote do cliente MCP.

npm install ai@7.0.34 @ai-sdk/mcp@2.0.16

Defina sua chave Scrapeless no shell e mantenha o placeholder fora do seu código fonte.

export SCRAPELESS_API_KEY="sk_your_key_here"

Conectar e carregar as ferramentas

createMCPClient abre a conexão. O transporte http leva o endpoint e os cabeçalhos, e client.tools() realiza o handshake e retorna as ferramentas indexadas por nome.

import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.scrapeless.com/mcp",
    headers: { "x-api-token": process.env.SCRAPELESS_API_KEY! },
  },
});

const tools = await client.tools();
const names = Object.keys(tools).sort();
console.log("contagem de ferramentas:", names.length);
console.log("ferramentas:", names.join(", "));

await client.close();

O servidor ao vivo retorna 21 ferramentas, carregadas apenas com a chave Scrapeless definida.

contagem de ferramentas: 21
ferramentas: browser_click, browser_close, browser_create, browser_get_html, browser_get_text, browser_go_back, browser_go_forward, browser_goto, browser_press_key, browser_screenshot, browser_scroll, browser_scroll_to, browser_snapshot, browser_type, browser_wait, browser_wait_for, google_search, google_trends, scrape_html, scrape_markdown, scrape_screenshot

A camada de transporte e de mensagem segue a especificação do Protocolo de Contexto de Modelo, que é baseada na especificação JSON-RPC 2.0. O AI SDK também aceita uma instância de transporte para servidores stdio ou SSE; o servidor Scrapeless é um endpoint HTTP hospedado, então o transporte http é o correto aqui.

Chamar uma ferramenta diretamente

Cada entrada no objeto retornado é uma ferramenta completa do SDK de IA com um método execute, para que você possa chamar uma você mesmo antes que qualquer modelo esteja conectado. O execute recebe os argumentos e um contexto de chamada, e retorna um resultado cujo content é uma lista de blocos.

import { createMCPClient } from "@ai-sdk/mcp";

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.scrapeless.com/mcp",
    headers: { "x-api-token": process.env.SCRAPELESS_API_KEY! },
  },
});

const tools = await client.tools();
const result = await tools.scrape_markdown.execute(
  { url: "https://quotes.toscrape.com/" },
  { toolCallId: "call_1", messages: [] },
);
const text = result.content
  .filter((block: { type: string }) => block.type === "text")
  .map((block: { text: string }) => block.text)
  .join("");
console.log("caracteres markdown:", text.length);
console.log("contém uma citação:", text.includes("Einstein"));

await client.close();

A chamada retorna a página como Markdown, e a verificação de conteúdo confirma que um texto real foi retornado.

caracteres markdown: 4308
contém uma citação: true

Essa é a forma que um modelo recebe de volta da mesma ferramenta: conteúdo da página sobre o qual pode raciocinar. A documentação das ferramentas AI SDK MCP cobre as opções de transporte e o client.close() que você deve chamar quando o trabalho estiver concluído.

Deixe um modelo chamar as ferramentas

Espalhe as ferramentas em generateText e o modelo as chama quando a tarefa precisa delas. O uso de ferramentas em múltiplas etapas precisa de uma condição de parada — stepCountIs permite que o modelo chame uma ferramenta, leia o resultado e responda. Este é o passo que precisa de uma chave de provedor de modelo.

Nota: este bloco precisa do pacote de provedor @ai-sdk/openai e uma OPENAI_API_KEY, nenhum dos quais está definido aqui. Carregar as 21 ferramentas e a chamada direta scrape_markdown acima funciona sem elas. O bloco é mostrado com sua forma exata; apenas a viagem de ida e volta do modelo é uma lacuna de pré-requisito.

import { createMCPClient } from "@ai-sdk/mcp";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";

const client = await createMCPClient({
  transport: {
    type: "http",
    url: "https://api.scrapeless.com/mcp",
    headers: { "x-api-token": process.env.SCRAPELESS_API_KEY! },
  },
});

const tools = await client.tools();
const { text } = await generateText({
  model: openai("gpt-4o"),
  tools,
  stopWhen: stepCountIs(5),
  prompt:
    "Use scrape_markdown para buscar https://quotes.toscrape.com/ e listar as três primeiras citações com autores.",
});
console.log(text);

await client.close();

Em tempo de execução, o modelo lê o prompt, chama scrape_markdown com a URL, recebe o Markdown que a chamada direta já retornou, e escreve a resposta. As ferramentas são os mesmos objetos, quer o modelo as chame ou você.

Conclusão

O Vercel AI SDK mais o Scrapeless MCP Server é um caminho curto de um modelo básico para um que lê a web ao vivo. O createMCPClient abre a conexão, client.tools() retorna todas as 21 ferramentas, execute prova que uma funciona, e espalhar tools em generateText entrega o conjunto ao modelo. Apenas o passo de geração precisa de uma chave de modelo, então você pode conectar e testar toda a superfície da ferramenta primeiro. Comece a partir dos scripts acima, limite as ferramentas ao que a tarefa precisa e deixe o modelo conduzir.

Crie uma conta gratuita no Scrapeless para obter uma chave de API, e confira preços do Scrapeless quando você planejar um agente recorrente.

FAQ

Q: O Vercel AI SDK precisa de uma chave de modelo para carregar ferramentas MCP?

Não. O createMCPClient executa o handshake e client.tools() retorna as ferramentas com apenas a chave da API Scrapeless definida, e o método execute de cada ferramenta a chama diretamente. Uma chave de provedor de modelo é necessária apenas quando você espalha as ferramentas em generateText ou streamText, porque é quando o modelo decide quais ferramentas chamar.

Q: Qual importação eu uso — createMCPClient ou experimental_createMCPClient?

Use createMCPClient do @ai-sdk/mcp. Tutoriais antigos importam experimental_createMCPClient do pacote ai; o cliente MCP foi movido para seu próprio pacote @ai-sdk/mcp, e a re-exportação do ai foi removida. Se um exemplo falhar ao resolver a importação, esta geralmente é a razão.

Q: Como eu chamo uma ferramenta MCP sem um modelo?

Chame await client.tools() e depois tools.<name>.execute(args, { toolCallId, messages: [] }). Isso retorna um resultado cujo content é uma lista de blocos; leia o texto a partir dos blocos de texto. Esta é a maneira mais rápida de confirmar a conexão e inspecionar a saída de uma ferramenta antes de conectar um modelo.

Q: Como eu me conecto a um servidor MCP local em vez disso?
Passe uma instância de transporte para stdio ou SSE em vez do objeto de transporte http, e então chame client.tools() da mesma forma. O Servidor MCP Scrapeless é um endpoint HTTP hospedado, portanto este guia utiliza o transporte http.

P: O scraping através das ferramentas está sujeito às regras do alvo?

Sim. As ferramentas buscam páginas públicas, e você continua responsável por honrar os termos de cada alvo e suas diretrizes do Protocolo de Exclusão de Robôs. Mantenha o volume limitado, os dados públicos e o modelo restrito às ferramentas que a tarefa realmente necessita.