Pydantic AI + Scrapeless: Da a tu Agente Herramientas Web en Vivo a través de MCP

Resumen:

• Pydantic AI se conecta al servidor MCP de Scrapeless a través de HTTP transmisible y proporciona a un agente 21 herramientas web en vivo, desde scrape_markdown hasta un conjunto completo de automatización de navegador.
• La conexión utiliza tres clases de pydantic_ai.mcp: un StreamableHttpTransport, un FastMCPClient, y un MCPToolset que se adjunta a un Agent.
• El apretón de manos, la lista de herramientas y una verdadera llamada a scrape_markdown se ejecutan sin una clave de proveedor de modelo; solo la generación final de agent.run necesita una.
• defer_model_check=True permite la construcción del Agent antes de que exista una clave de modelo, por lo que puedes conectar e inspeccionar el conjunto de herramientas primero.
• Una llamada a scrape_markdown devuelve la página objetivo como Markdown limpio, listo para devolver al modelo como contexto.
• Comienza con el plan gratuito de Scrapeless y conecta tu primer agente.

Pydantic AI le da a un agente estructura: salidas tipadas, argumentos de herramientas validadas y una forma clara de componer herramientas. Lo que no le da al agente es una forma de alcanzar la web en vivo. Esa brecha es exactamente lo que cierra el Protocolo de Contexto del Modelo. Apunta Pydantic AI a un servidor MCP y cada herramienta que ese servidor exponga se convierte en una herramienta que tu agente puede llamar, con los esquemas de argumentos validados de la misma manera que el resto de tu código de Pydantic AI.

Esta guía conecta Pydantic AI al Servidor MCP de Scrapeless, lista las herramientas que ofrece, llama a una de ellas de verdad y adjunta todo el conjunto a un Agent, todo verificado contra el servidor en vivo. El único paso que necesita una clave de proveedor de modelo es la llamada de generación al final, y esta publicación es explícita sobre dónde cae esa línea.

Por qué Scrapeless MCP

El Servidor MCP de Scrapeless expone herramientas de web-scraping y navegador que un agente puede llamar directamente, por lo que no tienes que construir o alojar la capa de scraping tú mismo. Una única 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 completo de browser_* que controla un navegador en la nube para clics, escritura, desplazamiento y navegación. La publicación sobre el Servidor MCP de Scrapeless cubre el servidor en sí; esta guía trata sobre integrarlo en Pydantic AI.

Debido a que las herramientas funcionan en la infraestructura de Scrapeless, el agente recibe páginas renderizadas y resultados de búsqueda sin un navegador local o un grupo de proxies. Las herramientas browser_* controlan el navegador en la nube de Scrapeless, por lo que un agente puede navegar por una página interactiva y leer lo que se renderiza.

Requisitos previos

• Python 3.10 o posterior.
• Una clave API de Scrapeless desde el panel, exportada como SCRAPELESS_API_KEY.
• Una clave de proveedor de modelo (como OPENAI_API_KEY) solo para el paso final de generación. El apretón de manos, la lista de herramientas y las llamadas a herramientas no necesitan una.

Instalación

Instala Pydantic AI con el extra de MCP, que incluye las clases de cliente de MCP.

pip install "pydantic-ai-slim[mcp]"

Configura tu clave de Scrapeless en la terminal. Usa la clave real en tiempo de ejecución y mantén el marcador fuera de tu código fuente.

export SCRAPELESS_API_KEY="sk_your_key_here"

Conectar y listar las herramientas

La conexión consiste en tres objetos. Un StreamableHttpTransport nombra el punto final y lleva la clave API en el encabezado x-api-token, un FastMCPClient habla el protocolo a través de ese transporte, y un MCPToolset envuelve al cliente para que Pydantic AI pueda usarlo. Ingresar al contexto asíncrono del conjunto de herramientas ejecuta el apretón de manos; list_tools devuelve lo que el servidor ofrece.

import asyncio
import os

from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))


async def main() -> None:
    async with scrapeless:
        tools = await scrapeless.list_tools()
        names = sorted(t.name for t in tools)
        print("conteo de herramientas:", len(names))
        print("herramientas:", ", ".join(names))


asyncio.run(main())

El servidor en vivo devuelve 21 herramientas, y no se estableció ninguna clave de proveedor de modelo para llegar aquí.

conteo 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

Los nombres de las herramientas son planos, sin prefijo de servidor, así que scrape_markdown es accesible exactamente por ese nombre. La capa de transporte y la de mensajes siguen la especificación del Protocolo de Contexto del Modelo, que a su vez se basa en la especificación JSON-RPC 2.0.

Llamar a una Herramienta Directamente

Antes de entregar las herramientas a un agente, llama a una tú mismo para ver qué devuelve. direct_call_tool invoca una herramienta por nombre con sus argumentos, que es la forma más rápida de confirmar que una herramienta funciona e inspeccionar su salida.

import asyncio
import os

from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))


async def main() -> None:
    async with scrapeless:
        result = await scrapeless.direct_call_tool("scrape_markdown", {"url": "https://quotes.toscrape.com/"})
        markdown = result if isinstance(result, str) else str(result)
        print("caracteres markdown:", len(markdown))
        print("contiene una cita:", "El mundo tal como lo hemos creado" in markdown)


asyncio.run(main())

La llamada devuelve la página como Markdown, y la verificación del contenido confirma que una cita real de la página objetivo está presente.

caracteres markdown: 4308
contiene una cita: True

Esta es la forma en que tu agente recibe: un Markdown limpio sobre el que puede razonar, en lugar de HTML sin procesar que tiene que eliminar. La documentación del cliente Pydantic AI MCP cubre los métodos del conjunto de herramientas en su totalidad.

Adjuntar las Herramientas a un Agente

Adjuntar es un argumento: pasa el conjunto de herramientas al Agente en toolsets. Debido a que una construcción normal de Agente valida el modelo de inmediato, defer_model_check=True permite que se construya antes de que se establezca una clave de modelo, para que puedas conectar e inspeccionar el conjunto de herramientas primero.

import asyncio
import os

from pydantic_ai import Agent
from pydantic_ai.mcp import FastMCPClient, MCPToolset, StreamableHttpTransport

transport = StreamableHttpTransport(
    url="https://api.scrapeless.com/mcp",
    headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
)
scrapeless = MCPToolset(FastMCPClient(transport))

# defer_model_check permite que el agente se construya antes de que se establezca la clave de modelo,
# así que el conjunto de herramientas puede ser conectado e inspeccionado primero.
agent = Agent("openai:gpt-4o", toolsets=[scrapeless], defer_model_check=True)


async def main() -> None:
    async with scrapeless:
        names = sorted(t.name for t in await scrapeless.list_tools())
    web = [n for n in names if n.startswith(("scrape_", "google_"))]
    print("agente conectado con", len(names), "herramientas Scrapeless")
    print("herramientas web:", web)


asyncio.run(main())

El agente ahora lleva cada herramienta de Scrapeless, y el subconjunto de raspado web es la parte que la mayoría de los tutoriales busca primero.

agente conectado con 21 herramientas Scrapeless
herramientas web: ['google_search', 'google_trends', 'scrape_html', 'scrape_markdown', 'scrape_screenshot']

Para entregar al agente solo unas pocas herramientas en lugar de las 21, MCPToolset expone filtered y renamed, para que puedas limitar un agente a scrape_markdown y google_search solo en lugar de todo el conjunto de navegación.

Ejecutar un Prompt

Con el conjunto de herramientas adjunto, el agente decide cuándo llamar a una herramienta. Este es el único paso que necesita una clave de proveedor de modelo.

Nota: agent.run necesita una clave de proveedor de modelo como OPENAI_API_KEY. Todo lo anterior — el apretón de manos, la lista de 21 herramientas, la llamada a scrape_markdown, y la conexión — se ejecuta sin ella. Solo esta llamada de generación es un requisito previo; se muestra aquí con la forma exacta que toma, no como un resultado capturado.

async def run_prompt() -> None:
    async with agent:
        result = await agent.run(
            "Usa scrape_markdown para obtener https://quotes.toscrape.com/ "
            "y lista las primeras tres citas con sus autores."
        )
    print(result.output)


asyncio.run(run_prompt())

En tiempo de ejecución, el modelo lee el prompt, llama a scrape_markdown con la URL, recibe el Markdown que la llamada anterior ya demostró, y escribe la respuesta. La capa de herramientas es idéntica, ya sea que la llames directamente o dejes que el modelo la llame.

Conclusión

Pydantic AI más el Servidor MCP de Scrapeless es un camino corto desde un agente básico a uno que lee la web en vivo. Tres clases hacen la conexión, list_tools muestra las 21 herramientas, direct_call_tool prueba que una funcione, y un argumento toolsets las adjunta todas. Solo el paso de generación necesita una clave de modelo, lo que mantiene toda la integración exploratoria antes de que te comprometas con un proveedor. Comienza con los scripts anteriores, limita el conjunto de herramientas a las herramientas que necesita tu agente y deja que el modelo haga el resto.
Crear una cuenta gratis en Scrapeless para obtener una clave API y consultar los precios de Scrapeless cuando planees un agente recurrente.

Preguntas Frecuentes

P: ¿Necesita Pydantic AI una clave de modelo para listar herramientas de MCP?

No. El apretón de manos, list_tools y direct_call_tool funcionan solo con la clave API de Scrapeless. Se requiere una clave de proveedor de modelo únicamente para agent.run, cuando el modelo decide qué herramientas llamar, para que puedas explorar y probar toda la superficie de herramientas antes de comprometer un proveedor.

P: ¿Cuál es la diferencia entre FastMCPClient y MCPToolset?

FastMCPClient usa el protocolo MCP a través de un transporte y expone operaciones de bajo nivel como list_tools. MCPToolset envuelve ese cliente para que Pydantic AI pueda tratar las herramientas del servidor como herramientas de agente, y agrega características de conjunto de herramientas como filtered y renamed. Debes adjuntar el MCPToolset, no el cliente, a un Agente.

P: ¿Cómo me conecto a un servidor MCP de stdio en lugar de HTTP?

Cambia el transporte. Usa StdioTransport con el comando del servidor en lugar de StreamableHttpTransport con una URL, luego envuélvelo en el mismo FastMCPClient y MCPToolset. El Servidor MCP de Scrapeless es un punto final HTTP alojado, así que esta guía utiliza StreamableHttpTransport.

P: ¿Por qué usar defer_model_check al construir el Agente?

Construir un Agente normalmente valida el proveedor de modelo de inmediato, lo que falla si no se establece ninguna clave. defer_model_check=True pospone esa verificación hasta el momento de ejecución, para que puedas construir el agente, conectar el conjunto de herramientas e inspeccionar las herramientas disponibles sin que esté presente una clave de modelo.

P: ¿Cómo le doy a un agente solo algunas de las herramientas?

Usa MCPToolset.filtered para exponer un subconjunto, o renamed para cambiar cómo aparecen las herramientas al modelo. Abocar un agente a scrape_markdown y google_search solo es más seguro que entregarle las 21 herramientas cuando la tarea solo necesita contenido y búsqueda.

P: ¿Qué devuelve scrape_markdown?

Devuelve la página objetivo renderizada como Markdown, que en la llamada verificada tenía 4,308 caracteres para la página de citas y contenía el texto real de la página. El Markdown es más fácil de razonar para un modelo que el HTML en bruto, así que es un buen valor predeterminado para alimentar el contenido de la página de nuevo en un aviso.

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 tú sigues siendo responsable de honrar los términos de cada objetivo y sus directrices del Protocolo de Exclusión de Robots. Mantén el volumen limitado y los datos públicos, y delimita el agente a las herramientas que realmente necesita la tarea.