Vercel AI SDK + Scrapeless: Herramientas web para tus agentes a través de MCP

Resumen:

• El SDK de Vercel AI se conecta al servidor MCP de Scrapeless con createMCPClient de @ai-sdk/mcp, pasando el endpoint y el encabezado x-api-token en la configuración del transporte.
• await client.tools() devuelve todas las 21 herramientas — scrape_markdown, scrape_html, google_search, google_trends, scrape_screenshot, y un conjunto de 16 herramientas browser_* — agrupadas por nombre, listas para usarse en generateText.
• En el SDK de AI 5 y posteriores, el cliente MCP reside en su propio paquete: importa createMCPClient de @ai-sdk/mcp, no experimental_createMCPClient de ai, que fue eliminado.
• Cada herramienta expone un método execute, por lo que puedes llamar a tools.scrape_markdown.execute({ url }) directamente y leer el Markdown antes de que intervenga un modelo: no se necesita clave de modelo para cargar o llamar herramientas.
• Solo el paso de generateText necesita una clave de proveedor de modelo, porque es ahí donde el modelo decide qué herramientas llamar.
• Comienza con el plan gratuito de Scrapeless y dale a tus agentes en TypeScript herramientas web reales.

El SDK de Vercel AI es el conjunto de herramientas estándar para construir aplicaciones de IA en TypeScript, y un modelo dentro de él solo puede actuar a través de las herramientas que le pasas. Nada en el SDK base accede a la web en vivo. El Protocolo de Contexto de Modelo cierra esa brecha: apunta al cliente MCP del SDK a un servidor y cada herramienta que ese servidor expone se convierte en una herramienta del SDK de IA que puedes usar directamente en generateText o streamText.

Esta guía conecta el SDK de IA al servidor MCP de Scrapeless, carga sus 21 herramientas, llama a una en la práctica y luego entrega el conjunto a un modelo, verificándolo contra el endpoint en vivo. El único paso que necesita una clave de proveedor de modelo es la llamada de generación, y esta publicación marca exactamente dónde se sitúa esa línea.

Lo que el servidor MCP de Scrapeless ofrece a un agente

El servidor MCP de Scrapeless expone herramientas de raspado web y de navegador que un agente puede llamar directamente, por lo que la capa de raspado no es algo que tú construyas o hospedes. Una conexión sirve 21 herramientas: scrape_markdown y scrape_html para contenido de páginas, google_search y google_trends para datos de búsqueda, scrape_screenshot para capturas, y un conjunto de 16 herramientas browser_* que controla un navegador en la nube a través de clics, escritura, desplazamiento y esperas.

Las herramientas browser_* funcionan en el navegador en la nube de Scrapeless, por lo que un modelo puede navegar por una página interactiva y leer lo que realmente se muestra sin necesidad de un navegador en tu máquina. Para el protocolo en sí, ¿Qué es MCP? es la explicación, y LangChain + Scrapeless MCP conecta el mismo servidor en una pila de Python.

Requisitos previos

• Node.js 22 o posterior.
• Una clave de API de Scrapeless del panel de control, exportada como SCRAPELESS_API_KEY.
• Una clave de proveedor de modelo como OPENAI_API_KEY solo para el paso de generación. Cargar y llamar a las herramientas no necesita una.

Instalación

Instala el núcleo del SDK de IA y el paquete del cliente MCP.

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

Establece tu clave de Scrapeless en el shell, y mantén el marcador fuera de tu código fuente.

export SCRAPELESS_API_KEY="sk_your_key_here"

Conectar y cargar las herramientas

createMCPClient abre la conexión. El transporte http lleva el endpoint y los encabezados, y client.tools() realiza el apretón de manos y devuelve las herramientas agrupadas por nombre.

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("cantidad de herramientas:", names.length);
console.log("herramientas:", names.join(", "));

await client.close();

El servidor en vivo devuelve 21 herramientas, cargadas solo con la clave de Scrapeless establecida.

cantidad de herramientas: 21
herramientas: 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

La capa de transporte y mensaje sigue la especificación del Protocolo de Contexto de Modelo, que se basa en la especificación JSON-RPC 2.0. El SDK de IA también acepta una instancia de transporte para servidores stdio o SSE; el servidor Scrapeless es un endpoint HTTP alojado, por lo que el transporte http es el correcto aquí.

Llamar a una herramienta directamente

Cada entrada en el objeto devuelto es una herramienta completa del SDK de IA con un método execute, por lo que puedes llamar a una tú mismo antes de que se conecte cualquier modelo. execute toma los argumentos y un contexto de llamada, y devuelve un resultado cuyo content es una lista de bloques.

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 en markdown:", text.length);
console.log("contiene una cita:", text.includes("Einstein"));

await client.close();

La llamada devuelve la página como Markdown, y la verificación de contenido confirma que se ha recibido texto real.

caracteres en markdown: 4308
contiene una cita: true

Esa es la forma en que un modelo recibe de la misma herramienta: contenido de página sobre el que puede razonar. La documentación de herramientas del SDK de IA MCP cubre las opciones de transporte y el client.close() que deberías llamar cuando el trabajo esté terminado.

Permitir que un modelo llame a las herramientas

Distribuye las herramientas en generateText y el modelo las llamará cuando las necesite. El uso de herramientas en múltiples pasos necesita una condición de parada: stepCountIs permite al modelo llamar a una herramienta, leer el resultado y responder. Este es el paso que necesita una clave de proveedor de modelo.

Nota: este bloque necesita el paquete de proveedor @ai-sdk/openai y una OPENAI_API_KEY, ninguno de los cuales está configurado aquí. Cargar las 21 herramientas y la llamada directa a scrape_markdown anterior funcionan sin ellas. El bloque se muestra con su forma exacta; solo el viaje de ida y vuelta del modelo es una brecha de requisito previo.

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:
    "Usa scrape_markdown para obtener https://quotes.toscrape.com/ y lista las primeras tres citas con autores.",
});
console.log(text);

await client.close();

En tiempo de ejecución, el modelo lee el aviso, llama a scrape_markdown con la URL, recibe el Markdown que la llamada directa ya devolvió y escribe la respuesta. Las herramientas son los mismos objetos, ya sea que el modelo las llame o tú lo hagas.

Conclusión

El SDK de IA de Vercel más el Servidor MCP de Scrapeless es un camino corto desde un modelo básico hasta uno que lee la web en vivo. createMCPClient abre la conexión, client.tools() devuelve todas las 21 herramientas, execute comprueba que una funcione, y distribuir tools en generateText entrega el conjunto al modelo. Solo el paso de generación necesita una clave de modelo, por lo que puedes configurar y probar toda la superficie de herramientas primero. Comienza desde los scripts anteriores, limita las herramientas a lo que la tarea necesita y deja que el modelo dirija.

Crea una cuenta gratuita de Scrapeless para obtener una clave API, y revisa los precios de Scrapeless cuando planees un agente recurrente.

Preguntas Frecuentes

Q: ¿El SDK de IA de Vercel necesita una clave de modelo para cargar herramientas MCP?

No. createMCPClient realiza el apretón de manos y client.tools() devuelve las herramientas con solo la clave de API de Scrapeless configurada, y el método execute de cada herramienta la llama directamente. Solo se requiere una clave de proveedor de modelo cuando distribuyes las herramientas en generateText o streamText, porque es entonces cuando el modelo decide qué herramientas llamar.

Q: ¿Qué importo debo usar: createMCPClient o experimental_createMCPClient?

Usa createMCPClient de @ai-sdk/mcp. Los tutoriales más antiguos importan experimental_createMCPClient del paquete ai; el cliente MCP se trasladó a su propio paquete @ai-sdk/mcp, y se eliminó la re-exportación de ai. Si un ejemplo no resuelve la importación, esta suele ser la razón.

Q: ¿Cómo llamo a una herramienta MCP sin un modelo?

Llama a await client.tools() y luego tools.<nombre>.execute(args, { toolCallId, messages: [] }). Devuelve un resultado cuyo content es una lista de bloques; lee el texto de los bloques de texto. Esta es la forma más rápida de confirmar la conexión e inspeccionar la salida de una herramienta antes de conectar un modelo.

Q: ¿Cómo me conecto a un servidor MCP local en su lugar?
Pasa una instancia de transporte para stdio o SSE en lugar del objeto de transporte http, luego llama a client.tools() de la misma manera. El Servidor MCP de Scrapeless es un endpoint HTTP alojado, así que esta guía utiliza el transporte http.

P: ¿Está el raspado a través de las herramientas sujeto a las reglas del objetivo?

Sí. Las herramientas obtienen páginas públicas, y sigues siendo responsable de cumplir los términos de cada objetivo y sus directrices del Protocolo de Exclusión de Robots. Mantén el volumen limitado, los datos públicos y el modelo limitado a las herramientas que realmente necesita la tarea.