Por qué falla el código de integración de herramientas a medida

Los agentes necesitan herramientas web reales, no envoltorios personalizados de Python

Todos los equipos crean el mismo código de integración: una herramienta en Python por cada fuente de scraping, un almacén de sesiones a medio funcionar y un orquestador casero que pierde el contexto tras una sola llamada. Tres semanas después, el agente funciona una vez, falla dos veces y nadie recuerda qué proxy ha caducado. Suministramos las cuatro piezas que todo ciclo de agente necesita listas para usar, a través de MCP, con un único punto final HTTP.

Si a tu agente se le ha agotado alguna vez el tiempo de espera en el tercer paso de un rastreo de varios pasos, esto va para ti.

Una herramienta de Python personalizada para cada fuente

El problema. Cada nueva funcionalidad del agente supone otro @tool decorador: uno para Amazon, otro para eBay y otro para la wiki de la empresa. Desviaciones en los esquemas, discrepancias entre versiones y un registro de herramientas del que nadie se hace responsable. Incorporar un nuevo modelo implica volver a implementar los envoltorios desde cero.

Cómo lo soluciona Yozh Scraper. Un punto final HTTP MCP que localhost:8000/mcp expone automáticamente todas las capacidades — scrape_page, scrape_batch, crawl, sessions, presets. Basta con añadir una línea a la configuración de Claude, Cursor o Cline para que el modelo detecte las herramientas en tiempo de ejecución. El mismo punto final para todos los clientes.

Un único endpoint MCP
Descubrimiento automático
Cero código de integración

Las llamadas a herramientas sin estado pierden el contexto de inicio de sesión

El problema. Las llamadas a la herramienta carecen de estado: cada llamada abre un nuevo navegador, borra las cookies y falla en el segundo paso de la autenticación de dos factores. Los agentes, atrapados en un bucle de reinicio de sesión, agotan los tokens y se dan por vencidos en el tercer intento. El almacenamiento manual de cookies es inestable y se pierde entre ejecuciones.

Cómo lo soluciona Yozh Scraper. API de sesiones con un session_id que el agente transmite entre llamadas. Lenguaje de programación declarativo para el inicio de sesión (goto / fill / click / wait) o pegar las cookies exportadas una sola vez: storageState persiste durante 24 horas. Cada llamada posterior a la herramienta reutiliza la sesión, sin necesidad de volver a autenticarse.

session_id persistente
Login declarativo
TTL de 24h

Autenticación manual y configuración del proxy en el código del agente

El problema. Todos los agentes acaban teniendo que gestionar claves API, rotación de proxies, códigos de país y reintentos —una configuración que no tiene nada que ver con la función del modelo—. Los datos confidenciales se filtran en las instrucciones, el agente toma decisiones «creativas» sobre los reintentos y los presupuestos de los proxies se disparan en una semana.

Cómo lo soluciona Yozh Scraper. CYBERYOZH_API_KEY En el .env — el código del agente nunca ve las credenciales. Elige proxy: {country: "us", type: "mobile"} en la llamada a la herramienta, Yozh se encarga de la rotación, la huella digital y los reintentos del lado del servidor. El agente se centra en el razonamiento.

Auth en el servidor
Proxy declarativo
Sin secretos en los prompts

Rastreos de varios pasos dentro de un bucle de agente

El problema. «Encontrar todas las páginas de productos de este sitio web y extraer los precios» es una intención del usuario, pero en el código del agente supone 200 llamadas a herramientas, una cola, una capa de deduplicación y la gestión de los tiempos de espera. El modelo desperdicia una ventana de contexto en el seguimiento de las URL, algo que nunca debería tener que hacer.

Cómo lo soluciona Yozh Scraper. Yozh Crawler recorre el sitio web desde el lado del servidor, transmite las URL descubiertas a través de SSE y, cada vez que encuentra una coincidencia, las envía al scraper. El agente se activa crawl_and_scrape una sola vez y obtiene un único flujo de resultados estructurados. El servidor mantiene la cola y el modelo conserva su contexto.

Streaming SSE
Cola en el servidor
Una sola llamada de herramienta

Cómo funciona

De `docker compose up` a las herramientas de llamadas de los agentes: en 3 pasos

Un punto final de MCP, una línea de configuración en tu cliente, cero código de enlace. El mismo flujo funciona para Claude Desktop, Cursor, Cline o tu propio bucle de agente.

1 Iniciar el punto de conexión MCP

Clona el repositorio y docker compose up. El servidor MCP está disponible en localhost:8000/mcp — el scraper, el crawler, las sesiones y los ajustes preestablecidos se exponen automáticamente como herramientas.

# one-time setup
git clone 
  github.com/CyberYozh-data/yozh-scraper
cd yozh-scraper
docker compose up -d

2 Conéctalo a tu cliente

Una línea en claude_desktop_config.json (o su equivalente en Cursor / Cline). Reinicia el cliente: las herramientas se detectan automáticamente, sin necesidad de envoltorios específicos para cada fuente.

{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

3 Herramientas para que el agente realice llamadas

El modelo selecciona la herramienta, rellena los parámetros y obtiene un JSON estructurado como respuesta. Las sesiones se mantienen entre llamadas. Los rastreos de varios pasos se transmiten a través de SSE.

// claude calls scrape_page autonomously
{
  "tool":   "scrape_page",
  "input":  {"url": "…",
              "preset": "amazon_product"},
  "result": { /* structured JSON */ }
}

Ejemplo en vivo

Lo que obtienes a cambio: un único formato, para todos los mercados

Elige un ajuste preestablecido para ver cómo es la respuesta. El conjunto de campos varía según la fuente, pero la estructura de la solicitud es idéntica.

Recetas

Cómo lo conectan los agentes: en 10 líneas cada uno

Tres configuraciones concretas de agentes, listas para copiar y pegar. Desde líneas de comando de Claude Desktop hasta un bucle completo de LangChain: todas ellas comparten el mismo punto final de MCP.

1 Claude, agente de investigación de escritorio

Conecta Yozh a Claude Desktop una vez. Pídele al modelo que investigue un tema: este elige scrape_page / crawl de forma autónoma y sintetiza la respuesta.

# claude_desktop_config.json (~/Library/...)
{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url":  "http://localhost:8000/mcp"
    }
  }
}

# restart Claude · prompt:
# "compare ssd prices on amazon vs walmart"
# → claude calls scrape_page on each PDP

Transporte HTTP descubrimiento automático de herramientas sin código de integración

2 Cursor Copilot con herramientas web

Añade el mismo servidor MCP a Cursor: ahora tu agente del IDE puede recuperar documentación en tiempo real, consultar los precios de la competencia o extraer información de una respuesta de Stack Overflow mientras escribes el comando.

# .cursor/mcp.json (project root)
{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url":  "http://localhost:8000/mcp"
    }
  }
}

# prompt in Cmd+L composer:
# "fetch the latest pricing from acme.com/plans
#  and update PricingTable.tsx"

config por proyecto el mismo endpoint MCP llamadas de herramientas en el chat

3 Bucle de LangChain / SDK de Anthropic

Agente Plain Python — SDK de Anthropic con mcp_servers lista. Con una sola URL HTTP, el modelo obtiene todas las herramientas de Yozh. Funciona igual con el adaptador MCP de LangChain.

# anthropic SDK · plain python
client = Anthropic()
resp   = client.messages.create(
  model="claude-sonnet-4-5",
  mcp_servers=[{
    "type": "url",
    "url":  "https://your-host/mcp"
  }],
  messages=[{
    "role": "user",
    "content": "crawl docs.x.com, summarize"
  }],
)

Streaming SSE piloto automático multiherramienta tu orquestador

FAQ

Preguntas frecuentes sobre la integración de MCP y los agentes

¿Qué clientes MCP son compatibles?

Cualquier elemento que utilice el protocolo de contexto de modelos (MCP) con transporte HTTP: Claude Desktop, Cursor, Cline, Continue, Zed, el nodo MCP de n8n, el adaptador MCP de LangChain y el mcp_servers param del SDK de Anthropic. El punto final en localhost:8000/mcp es una única URL: basta con dirigir cualquiera de ellos hacia ella. No hay que mantener envoltorios específicos para cada cliente ni adaptadores stdio.

¿Cómo se registran las herramientas en el agente?

Detección automática a través de MCP. Cuando el cliente se conecta a /mcp, el servidor muestra todas las herramientas disponibles con su esquema JSON: scrape_page, scrape_batch, crawl, create_session, list_presets, generate_preset. El modelo las reconoce como herramientas nativas en tiempo de ejecución —sin decoradores ni esquemas manuales—. Las nuevas capacidades de la versión original yozh-scraper aparecen automáticamente tras la siguiente actualización.

¿Puede mi agente transmitir un rastreo de varios pasos?

Sí: Yozh Crawler rastrea el sitio desde el lado del servidor y transmite las URL detectadas a través de SSE. El agente se activa crawl una sola vez y recibe un único flujo de eventos con resultados estructurados a medida que van llegando. Cada rastreo admite filtros de alcance (mismo dominio / mismo host / lista de permitidos), RPS por dominio y encadenamiento opcional con el extractor, de modo que cada URL encontrada se analiza antes de llegar al flujo. La cancelación mediante DELETE /scrape/{id} — la parada suave permite que las páginas en curso terminen; la parada forzada se realiza mediante una segunda llamada.

¿Cómo se mantienen las sesiones entre las llamadas a las herramientas?

API de sesiones. Crea una sesión una sola vez mediante el lenguaje DSL declarativo de inicio de sesión (goto / fill / click / wait) o pegando las cookies exportadas. Yozh almacena las cookies y Playwright storageState del lado del servidor y te proporciona un identificador persistente session_id. Cada llamada posterior de la herramienta que pase ese ID reutiliza el mismo estado del navegador, incluidos los portales protegidos con autenticación de dos factores (2FA), LinkedIn y los administradores de socios. El tiempo de vida (TTL) es de 24 horas por defecto, pero se puede actualizar. El agente nunca maneja las credenciales; simplemente reenvía el ID de sesión que ha recibido.

¿Cómo puedo ampliarlo con herramientas personalizadas?

Tres opciones. (1) Preajuste personalizado: arrastra un archivo JSON a src/presets/custom/ o llama POST /api/v1/presets/generate con una URL de ejemplo y deja que un modelo de lenguaje grande (LLM) deduzca el esquema. La configuración preestablecida aparece como un parámetro en la scrape_page . (2) Herramienta MCP personalizada: registra tu propio controlador en src/mcp/tools/, y se añadirá a la lista de herramientas detectadas automáticamente. (3) Fork: el repositorio tiene licencia MIT, el servidor MCP reside en un único módulo de Python (src/mcp/server.py) y es muy sencillo de ampliar.

Herramientas a las que tu agente puede recurrir de verdad

Los agentes necesitan herramientas web reales, no envoltorios personalizados de Python

Una herramienta de Python personalizada para cada fuente

Las llamadas a herramientas sin estado pierden el contexto de inicio de sesión

Autenticación manual y configuración del proxy en el código del agente

Rastreos de varios pasos dentro de un bucle de agente

De `docker compose up` a las herramientas de llamadas de los agentes: en 3 pasos

Lo que obtienes a cambio: un único formato, para todos los mercados

Cómo lo conectan los agentes: en 10 líneas cada uno

Preguntas frecuentes sobre la integración de MCP y los agentes

¿Estás listo para proporcionar a tu agente herramientas de verdad?

Apreciado por los equipos de datos y los desarrolladores de IA

Herramientas a las que tu agente puede recurrir de verdad

Los agentes necesitan herramientas web reales, no envoltorios personalizados de Python

Una herramienta de Python personalizada para cada fuente

Las llamadas a herramientas sin estado pierden el contexto de inicio de sesión

Autenticación manual y configuración del proxy en el código del agente

Rastreos de varios pasos dentro de un bucle de agente

De docker compose up a las herramientas de llamadas de los agentes: en 3 pasos

Lo que obtienes a cambio: un único formato, para todos los mercados

Cómo lo conectan los agentes: en 10 líneas cada uno

Preguntas frecuentes sobre la integración de MCP y los agentes

¿Estás listo para proporcionar a tu agente herramientas de verdad?

Apreciado por los equipos de datos y los desarrolladores de IA

De `docker compose up` a las herramientas de llamadas de los agentes: en 3 pasos