Cómo conectar Scrapeless a Claude: configuración del conector MCP

TL;DR:

• Agregar Scrapeless a Claude es una entrada de configuración: un servidor MCP HTTP remoto en https://api.scrapeless.com/mcp con tu clave en un encabezado x-api-token.
• El apretón de manos devuelve scrapeless-mcp-server v0.2.0 en el protocolo 2025-06-18, y tools/list devuelve 25 herramientas — scrape_markdown, el conjunto browser_*, crawl_*, google_search, google_trends y ai_scraper.
• El ámbito decide si se conecta. La misma entrada en el ámbito de usuario informa ✔ Connected; en un proyecto .mcp.json informa ⏸ Pending approval y permanece desconectada hasta que lo apruebes de forma interactiva.
• Scrapeless se autentica en x-api-token, no Authorization: Bearer. Un encabezado Bearer falla en el momento de la conexión: Claude informa ✘ Failed to connect con HTTP 401.
• Pasar la clave con --header la coloca en tu historial de shell y la lista de procesos; escribir el archivo de configuración directamente no lo hace.
• Un estado Connected solo prueba que el encabezado está presente — Scrapeless acepta cualquier valor de clave en el apretón de manos y aún lista todas las 25 herramientas. Prueba la clave con una llamada de herramienta real que devuelva contenido de página.
• Obtén una clave en el plan gratuito de Scrapeless y conéctate en aproximadamente un minuto.

Claude puede razonar sobre una página web en detalle y no puede obtener una. Un servidor MCP cambia eso: el modelo obtiene herramientas que puede llamar en medio de la conversación, por lo que "ver qué dice esta página ahora" deja de ser una solicitud que respondes pegando.

Conectar a Claude al servidor MCP de Scrapeless a través de HTTP remoto requiere una entrada de configuración. Las partes que valen la pena cuidar son los dos ámbitos que se comportan de manera diferente y la diferencia entre una conexión que informa verde y una que realmente funciona.

Lo que obtienes una vez que está conectado

El servidor expone 25 herramientas, enumeradas en vivo en lugar de copiadas de un documento:

Dos grupos son importantes para diferentes trabajos. scrape_markdown responde "¿qué dice esta página?" en una sola llamada. El conjunto browser_* es una sesión que conduces paso a paso, para cualquier cosa detrás de un clic o un formulario.

Cada una de esas llamadas viaja como una solicitud JSON-RPC bajo el capó — MCP es un transporte y un esquema sobre la especificación JSON-RPC 2.0, que es por lo que una secuencia initialize / tools/list / tools/call es todo lo que hay en la superficie del protocolo.

Requisitos previos

• Código Claude instalado, o otro cliente MCP que soporte servidores HTTP remotos.
• Una clave API de Scrapeless desde el panel de control.
• Nada que instalar para el servidor en sí. Está alojado, así que no hay paquete, no hay tiempo de ejecución y no hay proceso local.

Ese último punto es la diferencia entre los dos transportes. Un servidor stdio es un comando local que el cliente lanza, lo que significa un paquete para instalar y mantener actualizado. Un servidor HTTP remoto es una URL, y la especificación del Protocolo de Contexto de Modelo define ambos; el transporte HTTP transmisible es el que no necesita ningún proceso local en absoluto.

Paso 1: Agregar el servidor

La referencia del MCP de Claude Code documenta el comando como una línea:

claude mcp add --transport http scrapeless https://api.scrapeless.com/mcp \
  --header "x-api-token: YOUR_SCRAPELESS_API_KEY"

Eso funciona, y tiene un costo que vale la pena conocer: todo después de --header aparece en tu historial de shell y es visible en la lista de procesos mientras se ejecuta el comando. Escribir el archivo de configuración directamente evita ambos.

Para el ámbito de usuario, agrega la entrada a ~/.claude.json:

{
  "mcpServers": {
    "scrapeless": {
      "type": "http",
      "url": "https://api.scrapeless.com/mcp",
      "headers": { "x-api-token": "YOUR_SCRAPELESS_API_KEY" }
    }
  }
}

Nota el nombre del encabezado. Scrapeless se autentica en x-api-token, y la mayoría de las guías de configuración de MCP muestran Authorization: Bearer porque eso es lo que el marco de autenticación HTTP define para credenciales de portador. Copiar esa forma aquí falla antes de que complete el apretón de manos: claude mcp list informa ✘ Failed to connect — Server rejected the configured Authorization header (HTTP 401), con el detalle Unauthorized: Missing x-api-token header.

Paso 2: Entender qué ámbito usaste

Claude lee la configuración de MCP desde más de un lugar, y los dos se comportan de manera diferente de una manera que produce una confusa primera ejecución.

En el ámbito de usuario, el servidor está en vivo de inmediato:

scrapeless:
  Scope: User config (available in all your projects)
  Status: ✔ Connected
  Type: http
  URL: https://api.scrapeless.com/mcp

La entrada idéntica en un proyecto .mcp.json no se conecta:

scrapeless:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: http
  URL: https://api.scrapeless.com/mcp

Un archivo de ámbito de proyecto se comparte con todos los que sacan el repositorio, por lo que está sujeto a una aprobación interactiva antes de que el cliente pueda comunicarse con él. Esa es la opción predeterminada correcta: un archivo de configuración en un repositorio puede, de otro modo, señalar a tu cliente cualquier cosa, pero significa que una entrada de proyecto parece estar rota hasta que alguien abra una sesión y la apruebe.

Usa el ámbito de usuario para una clave que sea tuya. Usa el ámbito de proyecto cuando todo el equipo deba tener acceso al servidor y espera que cada persona lo apruebe una vez.

Paso 3: Confirma que realmente funcione

✔ Connected significa que el apretón de manos tuvo éxito. No significa que una llamada lo hará.

La lista de herramientas es proporcionada por el servidor MCP y nunca alcanza la API de upstream, por lo que un servidor puede anunciar un conjunto de herramientas completo y saludable mientras falla cada llamada real por una credencial. Eso no es hipotético: una puerta de enlace que presenta este mismo punto final con un token almacenado obsoleto enumeró su conjunto completo de herramientas y devolvió un error de token no válido en la primera llamada real, mientras que el mismo punto final con una buena clave devolvió HTTP 200.

Así que verifica con una llamada, no con una insignia. Dentro de una sesión de Claude, /mcp enumera los servidores conectados y sus herramientas; pedir una página ejerce el camino de extremo a extremo:

Use scrapeless to fetch https://books.toscrape.com/catalogue/category/books/mystery_3/index.html
as markdown and list the first five book titles with their prices.

La llamada subyacente y su resultado, capturados directamente contra el punto final:

initialize   HTTP 200   server=scrapeless-mcp-server v0.2.0
tools/list   HTTP 200   25 tools
tools/call scrape_markdown  HTTP 200  8940 chars of page content

El contenido de la página en el resultado es la confirmación que vale la pena tener. Con una clave incorrecta, la misma llamada aún devuelve HTTP 200 y no hay isError bandera; el texto del resultado comienza con Failed to fetch data en su lugar.

Lo que vuelve

scrape_markdown devuelve la página como Markdown en el bloque de contenido, que es la forma que un modelo puede realmente usar:

Response:  "-   [Home](https://books.toscrape.com/index.html)
-   [Books](https://books.toscrape.com/catalogue/category/books_1/index.html)
...

Markdown en lugar de HTML es intencional. A través de las herramientas MCP, la misma página tiene 8,940 caracteres desde scrape_markdown contra 53,800 desde scrape_html, así que pedir HTML gasta aproximadamente seis veces el contexto en marcado que el modelo no necesita. Alcanza scrape_html cuando vas a analizarlo tú mismo, y scrape_markdown cuando el modelo es el consumidor.

¿Trabajando en la configuración de un conector en este momento? El plan gratuito de Scrapeless incluye suficientes llamadas para completar el apretón de manos y las primeras llamadas a las herramientas.

Un router al frente cambia lo que Claude ve

Si tu cliente apunta a una puerta de enlace que enruta varios servidores MCP detrás de una URL en lugar de al punto final directamente, la lista de herramientas cambia de forma. Apuntado a una puerta de enlace de enrutamiento inteligente, el mismo cliente descubrió 3 herramientas: las herramientas meta de búsqueda y despacho del enrutador. Apuntado a https://api.scrapeless.com/mcp, descubrió todas 25.

Ninguno de los dos es incorrecto. Un enrutador mantiene una credencial y un registro de auditoría a través de muchos proveedores, a costa de que el modelo vea los nombres de las herramientas a una indirección de distancia. Conectar directamente le da al modelo la superficie real de herramientas. Elige según la configuración y verifica el conteo descubierto para que sepas cuál obtuviste.

Sugerirlo bien

Dos hábitos marcan la diferencia entre un servidor conectado y uno útil.

Nombra la herramienta cuando el trabajo sea inequívoco. "Usa scrape_markdown en esta URL" omite una ronda de decisión del modelo sobre cómo obtener la información. Para trabajos de varios pasos — iniciar sesión, filtrar, leer el resultado — describe la secuencia en su lugar, porque las herramientas browser_* comparten una sesión y el orden importa.

Pide la forma que deseas que vuelva. Un modelo que recibe 8,940 caracteres de Markdown resumirá, a menos que le indiques que devuelva una tabla de títulos y precios. La herramienta devuelve un documento; la salida útil es lo que le pediste al modelo que hiciera de él.

Para la imagen más amplia de MCP, nuestra guía de integración de MCP cubre el protocolo y el panorama del cliente, y la página de API de Scraping describe la familia de actores que presentan estas herramientas. La documentación lleva la referencia por actor, y precios enumera cuánto cuesta cada llamada.

Conclusión

Todo el conector es una URL, un nombre de encabezado y una decisión de ámbito. https://api.scrapeless.com/mcp con x-api-token en ámbito de usuario informa ✔ Connected y le entrega a Claude 25 herramientas; la misma entrada en un archivo de proyecto espera una aprobación que es fácil de confundir con una configuración rota.
Dos cosas valen la pena llevar más allá de la configuración. El encabezado es x-api-token, no Bearer; la forma Bearer es rechazada con un 401 en el tiempo de conexión, así que claude mcp list muestra que falla de inmediato. Y un estado verde es un apretón de manos: un tools/call que devuelve contenido real de la página es la única evidencia de que la credencial detrás de él es buena.

¿Listo para darle a Claude una búsqueda que pueda llamar? Comienza con el plan gratuito de Scrapeless y añade el servidor.

FAQ

Q: ¿Cómo agrego el servidor MCP de Scrapeless a Claude?

Agrega una entrada remota HTTP apuntando a https://api.scrapeless.com/mcp con tu clave en un encabezado x-api-token. Puedes ejecutar claude mcp add --transport http scrapeless https://api.scrapeless.com/mcp --header "x-api-token: ...", o escribir el mismo objeto type/url/headers en tu archivo de configuración, lo que mantiene la clave fuera del historial de la terminal.

Q: ¿Por qué mi servidor MCP muestra como pendiente de aprobación?

Porque está definido en un proyecto .mcp.json en lugar de en la configuración de tu usuario. Un archivo de proyecto viaja con el repositorio, así que el cliente requiere una aprobación interactiva antes de conectarse a él. La misma entrada en el ámbito del usuario se conecta inmediatamente. Abre una sesión y apruébalo, o mueve la entrada al ámbito del usuario si la clave es solo tuya.

Q: ¿Debería usar Authorization: Bearer o x-api-token?

x-api-token. Scrapeless lee ese encabezado específicamente; una solicitud sin él devuelve 401 Unauthorized: Missing x-api-token header. Una entrada sólo Bearer es rechazada de la misma manera en el tiempo de conexión, así que Claude muestra ✘ Failed to connect en lugar de ✔ Connected.

Q: ¿Cómo sé que la conexión realmente está funcionando?

Haz una llamada de herramienta. La salida del estado te dice que el apretón de manos fue exitoso, y las listas de herramientas son servidas por el servidor MCP sin contactar la API upstream, así que ambas pueden parecer saludables frente a una credencial rechazada. Un tools/call que devuelve contenido real de la página es la prueba; una clave incorrecta produce un resultado que comienza con Failed to fetch data, aún sin una bandera isError.

Q: ¿Cuál es la diferencia entre los transportes stdio y HTTP aquí?

Un servidor stdio es un proceso local que el cliente inicia, así que necesita un paquete instalado y mantenido actualizado. El servidor MCP de Scrapeless está alojado, así que el transporte HTTP necesita solo una URL y un encabezado; sin instalación, sin tiempo de ejecución local y sin versión que rastrear en tu máquina.

Q: ¿Cuántas herramientas debería esperar ver?

25 desde el endpoint directamente. Si ves 3, tu cliente está apuntando a una puerta de enlace de enrutamiento en lugar del endpoint, y esas tres son las propias herramientas de despacho del enrutador. Si ves una lista que nombra Mapas, Trabajos, Hoteles o Vuelos, ese es un conjunto de herramientas más antiguo; verifica el conteo contra un tools/list fresco.

Q: ¿Esto funciona en Claude Desktop así como en Claude Code?

Ambos soportan MCP, pero leen diferentes archivos de configuración, y la configuración de Desktop comúnmente se muestra con un comando local stdio en lugar de una URL. La entrada HTTP remota anterior es la forma de Claude Code; para el recorrido de Desktop, consulta nuestra publicación anterior sobre cómo ejecutar el servidor MCP de Scrapeless en Claude, y nota que su lista de herramientas es anterior a los actuales 25.

Q: ¿Puedo limitar qué herramientas puede llamar el modelo?

Sí, eso es una cuestión de permisos del lado del cliente en lugar de una configuración del servidor. Claude Code expone reglas de permitir y denegar para herramientas, así que una configuración que solo necesita contenido de página puede permitir scrape_markdown y dejar las herramientas de sesión del navegador no disponibles. Redúcelo a lo que el trabajo necesita.