Composio + Scrapeless: Añadir un Kit de Herramientas MCP Personalizado

TL;DR:

• Scrapeless no está en el catálogo de herramientas de Composio, por lo que se une como una herramienta MCP Personalizada. El panel de Composio tiene un diálogo de Agregar MCP Personalizado, marcado como Beta, que crea uno a partir de un servidor MCP remoto.
• El diálogo toma cuatro valores. Un nombre de visualización, la URL del servidor https://api.scrapeless.com/mcp, clave API como el tipo de autenticación, y x-api-token como el nombre del encabezado en Configuraciones avanzadas.
• Deja el prefijo del encabezado vacío. Scrapeless espera la clave sin formato en x-api-token. Con un prefijo como token, el apretón de manos y la lista de 25 herramientas aún tienen éxito, y cada llamada a la herramienta falla.
• Composio verifica que se ingresó una clave, no que Scrapeless la acepte. Verifica la clave y el valor del encabezado antes de agregar la herramienta, y confirma con una llamada a la herramienta después.
• La herramienta pertenece a un proyecto de Composio. Agrega su CUSTOM_ slug a una sesión y pasa session.mcp.url a cualquier cliente MCP.
• Obtén una clave en el plan gratuito de Scrapeless y agrega la herramienta en unos minutos.

Las sesiones de Composio dan a un agente herramientas autenticadas a través de una larga lista de aplicaciones, con las credenciales mantenidas del lado de Composio. Lo que una sesión no incluye es la web en vivo, como una página tal como se renderiza hoy o los resultados de una búsqueda en Google. El servidor MCP de Scrapeless proporciona esos como herramientas, y la función MCP Personalizada de Composio permite que una sesión las llame junto a sus herramientas integradas.

Esta guía añade Scrapeless a través del diálogo del panel, después utiliza la herramienta en una sesión. La mayor parte del trabajo es un solo formulario. La parte que necesita cuidado es el encabezado, porque un formato de encabezado incorrecto parece conectado hasta que una herramienta realmente se ejecuta.

Por qué Scrapeless se une a Composio como una herramienta MCP personalizada

El catálogo de Composio contiene las herramientas que Composio publica, y Scrapeless no es una de ellas. Para un servicio fuera del catálogo, la guía de MCP personalizada de Composio describe el camino. Registras un servidor MCP remoto por su URL HTTPS pública y esquema de autenticación, y Composio crea una herramienta con un slug CUSTOM_, sincroniza las herramientas del servidor y reenvía cada llamada a la herramienta al servidor con las credenciales de la cuenta conectada.

Tres límites vienen con ello. El MCP personalizado es experimental, y Composio dice que su flujo de configuración y contratos pueden cambiar. La herramienta está limitada al proyecto de Composio que la registra. Y Composio no alberga el servidor, por lo que el servidor debe ser accesible a través de HTTPS; Scrapeless es un punto de contacto alojado, por lo que nada se ejecuta en tu máquina.

La misma guía aún describe el registro como solo API y menciona que la gestión del panel llegará pronto. El panel de Composio en septiembre de 2026 ya mostraba un diálogo de Agregar MCP Personalizado, etiquetado como Beta y Solo MCP, y ese diálogo es el camino que sigue esta guía. La ruta de la API se cubre en las FAQ.

Qué añade Scrapeless a una sesión de Composio

El servidor expone 25 herramientas, agrupadas por trabajo:

• scrape_markdown, scrape_html y scrape_screenshot devuelven una página renderizada como Markdown, HTML crudo o una imagen en una sola llamada.
• Dieciséis herramientas browser_*, desde browser_create y browser_goto hasta browser_click, browser_type y browser_snapshot, manejan una sesión de navegador en la nube paso a paso.
• crawl_start, crawl_result y crawl_cancel ejecutan un rastreo en segundo plano y lo recogen más tarde.
• google_search y google_trends devuelven resultados de búsqueda y datos de tendencias, y ai_scraper captura respuestas de asistentes de IA como ChatGPT, Gemini y Perplexity.

Las 25 llegan como una sola herramienta. En una sesión predeterminada, la guía de Composio dice que un agente descubre herramientas personalizadas a través de su búsqueda de herramientas y las ejecuta a través del enrutador de herramientas, de la misma manera que accede a las herramientas integradas.

Requisitos previos

• Una cuenta de Composio con un proyecto. Las herramientas MCP personalizadas pertenecen a un proyecto.
• Una clave API de Scrapeless del panel de Scrapeless. Una clave que solo sirva para Composio puede rotarse sin afectar tus otras integraciones.
• Python 3 para la verificación en el Paso 1, que utiliza solo la biblioteca estándar.
• Para el Paso 4, el SDK de Python de Composio (esta guía utilizó composio 0.21.1) y tu clave API del proyecto Composio. El código de la sesión del Paso 4 aún no se ha ejecutado contra un proyecto de Composio para esta guía.

Paso 1: Verifica la clave y el valor del encabezado

La guía de Composio enumera una brecha conocida que vale la pena planificar: cuando conectas un servidor de clave API, la configuración verifica que se proporcionó una clave, no que el servidor remoto la acepte. Scrapeless añade un segundo punto ciego, porque responde al apretón de manos MCP y lista sus herramientas para cualquier valor de clave. Una clave incorrecta o un formato de encabezado incorrecto solo se muestra cuando se ejecuta una herramienta.
Este script envía las solicitudes que un cliente MCP envía, con la clave en el encabezado x-api-token, lista las herramientas y luego llama a scrape_markdown una vez. Sigue el transporte HTTP transmisible de MCP, JSON-RPC a través de POST a un único punto final, y no necesita nada más allá de la biblioteca estándar de Python:

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
PREFIX = os.environ.get("HEADER_PREFIX", "")
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": f"{PREFIX} {os.environ['SCRAPELESS_API_KEY']}".strip(),
}


def post(payload, session_id=None):
    headers = dict(HEADERS)
    if session_id:
        headers["Mcp-Session-Id"] = session_id
    request = urllib.request.Request(URL, data=json.dumps(payload).encode(), headers=headers)
    with urllib.request.urlopen(request, timeout=120) as response:
        body = response.read().decode()
        session_id = response.headers.get("Mcp-Session-Id") or session_id
    events = [line[5:].strip() for line in body.splitlines() if line.startswith("data:")]
    return session_id, json.loads(events[-1]) if events else None


session, init = post({
    "jsonrpc": "2.0", "id": 1, "method": "initialize",
    "params": {"protocolVersion": "2025-06-18", "capabilities": {},
               "clientInfo": {"name": "header-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, listing = post({"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 3, "method": "tools/call",
    "params": {"name": "scrape_markdown", "arguments": {"url": "https://example.com"}},
}, session)

server = init["result"]["serverInfo"]
text = "".join(part.get("text", "") for part in result["result"]["content"])
print(server["name"], server["version"])
print("tools listed:", len(listing["result"]["tools"]))
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:20])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

Con tu clave exportada como SCRAPELESS_API_KEY, imprime:

scrapeless-mcp-server 0.2.0
tools listed: 25
key accepted: 184 characters of Markdown

Ahora exporta HEADER_PREFIX=token y ejecútalo nuevamente. El script pone token y un espacio delante de la clave, la forma que toma un valor de encabezado prefijado:

scrapeless-mcp-server 0.2.0
tools listed: 25
key rejected: Failed to fetch data

El apretón de manos y el conteo de herramientas son idénticos en ambas ejecuciones. Solo la llamada a la herramienta los distingue, y Bearer como prefijo falla de la misma manera.

Paso 2: Agregar Scrapeless Con Agregar MCP Personalizado

En el panel de Composio, abre Agregar MCP Personalizado, el diálogo titulado "Crear un kit de herramientas desde un servidor MCP remoto", y complétalo:

Luego elige Agregar.

El prefijo del encabezado es el campo a tener en cuenta. Existen para las API que esperan una palabra de esquema delante de la credencial, como Bearer. Scrapeless lee el valor completo de x-api-token como la clave, por lo que cualquier prefijo convierte una clave válida en una que rechaza, como mostró la segunda ejecución en el Paso 1.

Asegúrate de que estas configuraciones sean correctas antes de guardar. En la API de Composio, el formato del encabezado es parte del esquema de autenticación del kit de herramientas, y la guía de MCP Personalizado dice que la URL del servidor y el esquema de autenticación no pueden cambiar después del registro; un intento devuelve 409 Conflict. Para corregir un kit de herramientas guardado con un prefijo, usa Eliminar en su página y agrégalo de nuevo. Eliminar un kit de herramientas personalizado también elimina sus configuraciones de autenticación y cuentas conectadas, así que debes volver a conectar la cuenta después.

¿Estás configurando esto ahora? El plan gratuito de Scrapeless cubre la conexión y tus primeras llamadas a herramientas.

Paso 3: Conectar una Cuenta y Dejar que las Herramientas se Sincronicen

Un kit de herramientas de clave API no tiene nada que llamar hasta que se conecta una cuenta, y aquí es donde va la clave. El prefijo de encabezado vacío del Paso 2 solo significa que nada se coloca delante de la clave. Conectar abre una página titulada "Composio quiere conectarse a tu" seguido del nombre del kit de herramientas, con un único campo Clave API requerido. Pega tu clave API de Scrapeless allí y elige Conectar Cuenta. Composio almacena la clave en la cuenta conectada y la coloca en el encabezado x-api-token de cada solicitud que envía a Scrapeless.

La primera sincronización comienza en segundo plano una vez que esa cuenta se activa. De vuelta en la página de Scrapeless, Cuentas Conectadas lista la cuenta como Activa, y Acciones Disponibles muestra 25, una para cada herramienta de Scrapeless, bajo nombres como "Ai scraper" y "Clic en navegador". Conexiones posteriores no sincronizan el kit de herramientas nuevamente, por lo que cuando Scrapeless agrega herramientas, usa Sincronizar en esa página. Un kit de herramientas personalizado tiene como máximo 500 herramientas.

Una lista de herramientas sincronizadas prueba que Composio alcanzó el servidor. No prueba la clave, por la razón que mostró el Paso 1, que es por qué el último paso termina en una llamada a la herramienta.

La clave ahora también vive con un tercero. La guía de gestión de secretos de OWASP trata la rotación como rutinaria, y una clave dedicada a Composio es una que puedes rotar sin romper nada más.

Paso 4: Usar el Kit de Herramientas en una Sesión

Agrega el slug del kit de herramientas a una sesión. Con mcp=True, la sesión también expone un servidor MCP hospedado que cualquier cliente MCP puede usar.

Nota: este código sigue el SDK de Python de Composio 0.21.1 y las guías de sesiones de Composio; aún no se ha ejecutado contra un proyecto de Composio para esta guía. Necesita que COMPOSIO_API_KEY esté configurado con tu clave API del proyecto.

from composio import Composio

composio = Composio()  # reads COMPOSIO_API_KEY from the environment

session = composio.sessions.create(
    user_id="user_123",
    toolkits=["CUSTOM_SCRAPELESS"],
    connected_accounts={"CUSTOM_SCRAPELESS": ["ca_your_connected_account_id"]},
    mcp=True,
)

print(session.mcp.url)

Usa el slug mostrado en la página de tu kit de herramientas si difiere de CUSTOM_SCRAPELESS; Composio agrega el prefijo CUSTOM_ cuando registra el kit de herramientas. La entrada connected_accounts vincula la cuenta en la que se ejecutan las llamadas. Las sesiones coinciden con cuentas por user_id por sí solas solo cuando la configuración de autenticación del kit de herramientas tiene habilitado el enrutamiento de herramientas que coincide, y sin él las llamadas fallan con NoActiveConnection. Vincular la cuenta funciona de cualquier manera.
Guía de Composio sobre sesiones a través de MCP pasa session.mcp.url y session.mcp.headers a la configuración MCP del cliente, para marcos como el OpenAI Agents SDK y el Claude Agent SDK. Los encabezados llevan las credenciales para esa URL, así que entrégaselos al cliente sin registrarlos.

Luego, da al agente un trabajo verificable:

Use the Scrapeless scrape_markdown tool to fetch https://example.com
and reply with the first heading of the returned page, quoted exactly.

Una configuración funcional responde con "# Example Domain". Una respuesta que cita Failed to fetch data señala de vuelta la clave o el prefijo del encabezado.

Soluciona los Problemas Comunes

Para más información sobre lo que expone el servidor, lee el anuncio del servidor MCP de Scrapeless. La documentación de MCP del Navegador lleva la referencia de configuración, la página de la API de Scraping cubre los actores detrás de las herramientas, y los precios listan lo que cuesta una llamada.

Conclusión

Agregar Scrapeless a Composio toma un diálogo: un nombre de visualización, https://api.scrapeless.com/mcp, autenticación de clave API, x-api-token como el nombre del encabezado y un prefijo de encabezado vacío. Conecta una cuenta con tu clave, deja que las herramientas se sincronicen, y añade el kit de herramientas CUSTOM_ a una sesión.

Lo que necesita cuidado es la brecha entre sincronizado y funcionando. Composio confirma que se ingresó una clave, y Scrapeless lista sus herramientas para cualquier clave, así que un error de prefijo pasa ambas verificaciones. Ejecuta la verificación de clave antes de agregar el kit de herramientas y una llamada de herramienta real después de ello, y la configuración está probada de extremo a extremo.

¿Listo para darle a tus agentes de Composio una vista en vivo de la web? Comienza con el plan gratuito de Scrapeless y añade el kit de herramientas.

Preguntas Frecuentes

P: ¿Puedo añadir un servidor MCP personalizado a Composio?

Sí. MCP personalizado registra un servidor remoto por su URL HTTPS y esquema de autenticación y lo convierte en un kit de herramientas con alcance de proyecto con un CUSTOM_ slug. El panel tiene un diálogo Añadir MCP personalizadopara ello, y la API de Composio ofrece el mismo registro a través de sus puntos finales de kit de herramientas personalizados.

P: ¿Qué debe ir en el prefijo de Encabezado para Scrapeless?

Nada. Establece el nombre del encabezado a x-api-token y deja el prefijo vacío, porque Scrapeless lee todo el valor del encabezado como la clave. Un prefijo token o Bearer hace que cada llamada de herramienta falle, aunque las herramientas sigan sincronizándose.

P: ¿Dónde ingreso la clave API de Scrapeless en Composio?

En la página de conexión, cuando conectas una cuenta en el kit de herramientas. El diálogo Añadir MCP personalizado solo define el nombre del encabezado y el prefijo; la página de conexión pide la Clave API, y Composio envía ese valor como el encabezado x-api-token.

P: ¿Por qué se sincronizan mis herramientas de Scrapeless en Composio pero todas las llamadas fallan?

La lista de herramientas funciona con cualquier valor de clave, así que un kit de herramientas sincronizado no prueba la credencial. Las llamadas que devuelven Failed to fetch data significan que el valor del encabezado es incorrecto: un prefijo de encabezado lleno o una clave inválida. Ejecuta la verificación del Paso 1 con tu clave para ver cuál.

P: ¿Puedo cambiar la configuración del encabezado después de añadir el kit de herramientas?

No en el lugar. Composio trata la URL del servidor y el esquema de autenticación como fijos después del registro. Elimina el kit de herramientas, añádelo de nuevo con la configuración correcta y vuelve a conectar la cuenta, ya que la eliminación elimina sus conexiones.

P: ¿Puedo registrar Scrapeless a través de la API de Composio en lugar del panel?
Sí. POST /api/v3.1/custom/toolkits/upsert toma la URL del servidor y un esquema de autenticación API_KEY con un objeto headers. Composio permite nombres de encabezados diferentes a Authorization siempre que un valor de encabezado contenga {{generic_api_key}}, por lo que la entrada para Scrapeless es "x-api-token": "{{generic_api_key}}". Para los servidores de clave API, la guía agrega un paso de configuración de autenticación separado antes de que las cuentas puedan conectarse.

Q: ¿Está disponible el kit de herramientas Scrapeless en todos mis proyectos de Composio?

No. Un kit de herramientas MCP personalizado está limitado al proyecto que lo registra. Agrega Scrapeless en cada proyecto que lo necesite.

Q: ¿Pueden Claude, Cursor u otro cliente MCP usar Scrapeless a través de Composio?

Sí. Crea una sesión con mcp=True y da al cliente session.mcp.url y session.mcp.headers. El cliente luego accede a las herramientas Scrapeless a través de la sesión de Composio.

Q: ¿Cuántas herramientas agrega Scrapeless a Composio?

25: tres herramientas scrape_*, dieciséis herramientas browser_*, tres herramientas crawl_*, más google_search, google_trends y ai_scraper.