SDK de Agentes de OpenAI + Scrapeless: Herramientas Web para Tus Agentes a través de MCP

TL;DR:

• El SDK de OpenAI Agents se conecta al servidor Scrapeless MCP a través de un objeto, MCPServerStreamableHttp, que lleva el punto final y el encabezado x-api-token.
• await server.list_tools() devuelve todas las 21 herramientas: scrape_markdown, scrape_html, google_search, google_trends, scrape_screenshot y un conjunto de 16 herramientas browser_* — con solo la clave de Scrapeless configurada.
• A diferencia de los marcos que convierten las herramientas MCP en objetos independientes, el SDK mantiene el servidor como una conexión de primera clase: se entrega todo el server al agente, y este llama a list_tools y call_tool por ti.
• Puedes llamar a cualquier herramienta directamente con await server.call_tool("scrape_markdown", {"url": ...}) antes de que un agente esté involucrado — no se necesita clave de modelo para cargar o llamar a las herramientas.
• Solo Runner.run necesita una clave de proveedor de modelo, porque ese es el paso donde el modelo decide qué herramientas llamar.
• Comienza con el plan gratuito de Scrapeless y da a tus agentes del SDK de OpenAI Agents herramientas web reales.

El SDK de OpenAI Agents es el marco ligero de OpenAI para construir aplicaciones agénticas en Python, y un agente en él solo es tan útil como las herramientas que le des. Nada en la instalación base alcanza la web en vivo. El Protocolo de Contexto del Modelo soluciona eso: apunta el SDK a un servidor MCP y cada herramienta que ese servidor expone se vuelve llamable por tu agente a través de la misma interfaz que una función herramienta escrita a mano.

Esta guía conecta el SDK al Servidor MCP de Scrapeless, lista sus 21 herramientas, llama a una en vivo y luego adjunta todo el servidor a un Agente — verificado contra el punto final en vivo. El único paso que necesita una clave de proveedor de modelo es la llamada de generación del agente, y esta publicación marca exactamente dónde se sitúa esa línea.

Lo que el Servidor MCP de Scrapeless le ofrece a un agente

El Servidor MCP de Scrapeless expone herramientas de scraping web y de navegador que un agente puede llamar directamente, por lo que la capa de scraping no es algo que debas construir o alojar. Una conexión sirve 21 herramientas: scrape_markdown y scrape_html para contenido de página, 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 agente puede navegar por una página interactiva y leer lo que realmente se renderiza sin un navegador en tu máquina. Si deseas que el mismo servidor esté conectado a un stack diferente, la guía de LangChain + Scrapeless MCP cubre ese aspecto, y ¿Qué es MCP? explica el protocolo en sí.

Requisitos previos

• Python 3.10 o posterior.
• Una clave API de Scrapeless desde el panel de control, exportada como SCRAPELESS_API_KEY.
• Una clave de proveedor de modelo como OPENAI_API_KEY solo para la ejecución del agente. Cargar y llamar a las herramientas no necesita una.

Instalación

Instala el SDK. El cliente MCP se incluye dentro de él, por lo que no hay un extra separado que agregar.

pip install "openai-agents==0.18.3"

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

export SCRAPELESS_API_KEY="sk_tu_clave_aqui"

Conectar y cargar las herramientas

MCPServerStreamableHttp toma un diccionario params con el punto final y los encabezados, y es un administrador de contexto asíncrono, por lo que la conexión se abre y se cierra alrededor de un bloque with. list_tools ejecuta el saludo y devuelve las herramientas del servidor.

import asyncio
import os

from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        tools = await server.list_tools()
        names = sorted(tool.name for tool in tools)
        print("número de herramientas:", len(names))
        print("herramientas:", ", ".join(names))


asyncio.run(main())

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

número 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 mensajes sigue la especificación del Protocolo de Contexto de Modelo, que se basa en la especificación JSON-RPC 2.0. El SDK también incluye MCPServerStdio para un servidor de subproceso local; el servidor Scrapeless es un punto de HTTP alojado, por lo que la clase de HTTP transmitible es la correcta aquí.

Llamar a una herramienta directamente

Antes de que exista un agente, puedes llamar a cualquier herramienta en el servidor tú mismo. call_tool toma el nombre de la herramienta y un diccionario de argumentos y devuelve un CallToolResult cuyo content es una lista de bloques; el texto está en los bloques de texto.

import asyncio
import os

from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        result = await server.call_tool("scrape_markdown", {"url": "https://quotes.toscrape.com/"})
        text = "".join(block.text for block in result.content if block.type == "text")
        print("caracteres de markdown:", len(text))
        print("contiene una cita:", "Einstein" in text)


asyncio.run(main())

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

caracteres de markdown: 4308
contiene una cita: True

Esa es la forma en que un agente recibe de la misma herramienta: contenido de la página sobre la que puede razonar. La documentación del SDK de Agentes de OpenAI MCP cubre list_tools, call_tool y la opción cache_tools_list que omite apretón de manos repetidos cuando el conjunto de herramientas es estable.

Entregar las herramientas a un agente

Aquí el SDK difiere de los marcos de adaptador de herramientas. No conviertes las herramientas y pasas una lista; pasas todo el servidor al argumento mcp_servers del agente, y el agente llama a list_tools y call_tool en él durante la ejecución. Este es el paso que necesita una clave de proveedor de modelo.

Nota: Runner.run necesita una clave de proveedor de modelo como OPENAI_API_KEY, que no está configurada aquí. Cargar las 21 herramientas y la llamada directa a scrape_markdown anterior se ejecutan sin ella. Este bloque se muestra con su forma exacta; solo el viaje de ida y vuelta del modelo es una brecha de requisito.

import asyncio
import os

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp


async def main() -> None:
    params = {
        "url": "https://api.scrapeless.com/mcp",
        "headers": {"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    }
    async with MCPServerStreamableHttp(
        params=params, name="scrapeless", client_session_timeout_seconds=60
    ) as server:
        agent = Agent(
            name="web_agent",
            instructions="Usa las herramientas de Scrapeless para obtener y leer páginas.",
            mcp_servers=[server],
        )
        result = await Runner.run(
            agent,
            "Usa scrape_markdown para obtener https://quotes.toscrape.com/ y lista las primeras tres citas con autores.",
        )
        print(result.final_output)


asyncio.run(main())

En tiempo de ejecución, el modelo lee la tarea, llama a scrape_markdown con la URL, recibe el Markdown que la llamada directa ya devolvió y escribe la respuesta. Las herramientas son las mismas de cualquier manera: el único nuevo ingrediente es el modelo que decide cuándo llamarlas.

Conclusión

El SDK de OpenAI Agents más el Servidor MCP de Scrapeless es un camino corto desde un agente básico a uno que lee la web en vivo. Un objeto MCPServerStreamableHttp abre la conexión, list_tools devuelve todas las 21 herramientas, call_tool prueba que una funciona, y un solo argumento mcp_servers=[server] entrega el conjunto al agente. Solo el paso de generación necesita una clave de modelo, por lo que puedes cablear y probar toda la superficie de herramientas primero. Comienza desde los scripts anteriores, ajusta las herramientas a lo que la tarea necesita y deja que el modelo dirija.

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

FAQ

P: ¿El SDK de OpenAI Agents necesita una clave de modelo para cargar herramientas MCP?

No. MCPServerStreamableHttp ejecuta el apretón de manos y list_tools devuelve las herramientas con solo la clave de API de Scrapeless configurada, y call_tool invoca cualquiera de ellas directamente. Una clave de proveedor de modelo solo se requiere cuando pasas el servidor a un Agente y llamas a Runner.run, porque es entonces cuando el modelo decide qué herramientas llamar.
P: ¿Cómo llamo a una herramienta MCP sin construir un agente?

Abre el servidor como un administrador de contexto asíncrono y llama a await server.call_tool(name, arguments). Devuelve un CallToolResult 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 que intervenga cualquier modelo.

P: ¿Por qué pasar el servidor en lugar de una lista de herramientas?

El SDK mantiene el servidor MCP como una conexión activa y lo consulta durante la ejecución, por lo que lo adjuntas con mcp_servers=[server] en lugar de convertir cada herramienta. Si el conjunto de herramientas es estable, establece cache_tools_list=True en el servidor para que no vuelva a ejecutar el apretón de manos en cada turno.

P: ¿Puedo conectarme a un servidor MCP local en su lugar?

Sí. Cambia MCPServerStreamableHttp por MCPServerStdio y dale el comando que inicia tu servidor local, luego pásalo al agente de la misma manera. El Servidor MCP Scrapeless es un punto de enlace HTTP alojado, por lo que esta guía utiliza la clase HTTP transmitible.

P: ¿Está la extracción de datos a través de las herramientas sujeta 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, los datos públicos y el agente enfocado en las herramientas que la tarea realmente necesita.