Warp + Scrapeless: Conectar un servidor MCP remoto

TL;DR:

• Warp se conecta a Scrapeless como un servidor MCP remoto a través de HTTP transmisible. Un archivo .warp/.mcp.json en la raíz de tu proyecto con un encabezado url y x-api-token es toda la configuración.
• Escribe ${SCRAPELESS_API_KEY}, incluidas las llaves. Warp expande esa forma cuando lee el archivo. $SCRAPELESS_API_KEY y {{SCRAPELESS_API_KEY}} llegan a Scrapeless como texto literal, y el servidor sigue pareciendo saludable en /mcp.
• Una variable no establecida cierra todo el archivo. Cada servidor en él es reemplazado por Warp config error … Missing or empty environment variable: SCRAPELESS_API_KEY.
• Los servidores del proyecto se inician a mano. Abre /mcp, selecciona scrapeless y presiona Enter; la fila se mueve de offline a running · 25 tools.
• running · 25 tools no prueba la clave. Una clave inventada alcanza el mismo estado. Una llamada a la herramienta, o la verificación corta en el Paso 5, separa una clave válida de una inválida.
• El nombre del encabezado es x-api-token. Una entrada Authorization: Bearer falla con "rechazó las credenciales configuradas (HTTP 401)", incluso cuando el token en sí es válido.
• Obtén una clave en el plan gratuito de Scrapeless y agrega el servidor en unos minutos.

El Agente Warp ejecuta comandos en un terminal real y lee tu código, pero no tiene vista de lo que una página web renderiza en este momento. Un servidor MCP cierra esa brecha: herramientas que el agente llama en medio de la tarea, respondidas por un servicio que recupera y renderiza la página para él.

Esta guía agrega el servidor MCP de Scrapeless alojado al CLI del Agente Warp, el binario warp. La configuración es unas pocas líneas de JSON. La funcionalidad depende de tres detalles: qué archivo lee Warp, cómo se hace referencia a la clave dentro de él y qué hace y no te dice la línea de estado /mcp.

Qué Añade Scrapeless a una Sesión del Agente Warp

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, conducen 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.

Nada se ejecuta en tu máquina para esto. El transporte HTTP transmisible MCP es un único endpoint HTTPS que recibe JSON-RPC sobre POST, y Warp lo habla de manera nativa. Su registro MCP registra MCP: Using Streaming HTTP transport para este servidor sin ninguna configuración de transporte en el archivo.

Dónde Busca Warp las Definiciones del Servidor MCP

Warp lee definiciones de servidores desde archivos de configuración así como desde su página de configuración. La documentación MCP de Warp enumera estas ubicaciones:

Los servidores específicos del proyecto de cualquier proveedor nunca se inician por sí solos. Warp los detecta y espera a que inicies cada uno, y la elección dura solo para la sesión, así que después de un reinicio, los inicias de nuevo.

El CLI también mantiene una configuración separada de la aplicación Warp. La página de configuración del CLI del Agente Warp da ~/.warp_cli/.mcp.json como ese archivo en macOS. En Linux, Warp Agent CLI v0.2026.09.09.08.26.stable_02 no detectó un servidor de ~/.warp_cli/.mcp.json o de ~/.warp/.mcp.json, mientras descubrió los tres archivos específicos del proyecto y los etiquetó como Warp (.warp/.mcp.json), Claude (.mcp.json) y Other Agents (.agents/.mcp.json). Esta guía usa .warp/.mcp.json, el archivo que Warp denomina como el suyo.

Si trabajas en la aplicación de escritorio Warp en su lugar, el mismo JSON mcpServers se introduce en Configuración > Agentes > Servidores MCP a través del botón + Agregar.

Requisitos Previos

• El CLI del Agente Warp, con una cuenta Warp iniciada. Esta guía usa la versión v0.2026.09.09.08.26.stable_02, que warp --version imprime.
• Créditos de IA en esa cuenta Warp, para el paso en el que el agente llama a una herramienta.
• Una clave API de Scrapeless desde el panel de control de Scrapeless.
• Una carpeta de proyecto para contener el archivo de configuración. Las pruebas aquí usaron un repositorio Git.

Paso 1: Agregar .warp/.mcp.json a Tu Proyecto

Crea .warp/.mcp.json en la raíz del proyecto:

{
  "mcpServers": {
    "scrapeless": {
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "${SCRAPELESS_API_KEY}"
      }
    }
  }
}

Un servidor URL toma dos propiedades en Warp: url, que es requerido, y headers, un objeto clave-valor que es opcional en general y requerido aquí, porque Scrapeless autentica cada solicitud por el encabezado x-api-token. No hay un campo type para establecer.

El archivo contiene una referencia de variable, no una clave, por lo que puede vivir en el control de versiones. Cada persona que abre el proyecto exporta su propia clave. Eso mantiene la credencial fuera del repositorio, que la guía de gestión de secretos de OWASP trata como un lugar donde un secreto nunca debería estar.

Paso 2: Exporta la Clave Con el Marcador Correcto

Exporta la variable en el shell que inicia Warp, luego lanza la CLI desde la carpeta del proyecto:

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
cd path/to/your-project
warp

Warp expande las referencias ${VAR} cuando lee un archivo de configuración desde el disco. La forma importa, y una forma incorrecta falla silenciosamente. Cada variante a continuación fue enviada a través de un proxy de registro local para ver qué llegó realmente a Scrapeless:

Las segunda y tercera filas son la trampa. Se ven exactamente como una configuración de trabajo hasta que la primera llamada de la herramienta del agente devuelve un fallo de autenticación.

El caso no exportado es ruidoso, pero llega más allá que un solo servidor. Warp rechaza todo el archivo y lista una única fila de error en lugar de cada servidor definido en él:

Warp config error  /path/to/your-project/.warp/.mcp.json · Missing or empty environment variable: SCRAPELESS_API_KEY

En las pruebas, un segundo servidor válido definido en el mismo archivo también desapareció de la lista. Exporta la variable en tu perfil de shell, o en lo que sea que inicie tus sesiones de terminal, para que cada proceso warp lo herede.

¿Configurando esto ahora? El plan gratuito de Scrapeless cubre la conexión y tus primeras llamadas de herramienta.

Paso 3: Inicia el Servidor Desde /mcp

Escribe /mcp en la entrada de CLI para abrir la vista de gestión de MCP, luego escribe scrapeless en su cuadro de búsqueda. La fila nombra la etiqueta del proveedor, el proyecto y el transporte:

scrapeless  Warp · scrapeless-demo · HTTP/SSE · offline

Presiona Enter en la fila. Dentro de unos segundos, Warp ejecuta el apretón de manos de MCP, lista las herramientas y actualiza la fila:

scrapeless  Warp · scrapeless-demo · HTTP/SSE · running · 25 tools

Entrar en una fila en ejecución detiene el servidor. Debido a que los servidores con ámbito de proyecto tienen ámbito de sesión, repite este inicio cada vez que abras la CLI en ese proyecto.

Paso 4: Lee el Estado Antes de Solicitar

Cada estado en /mcp apunta a una solución diferente:

La fila failed merece un examen más cercano, porque su consejo apunta en dirección opuesta a la causa. Con Authorization: Bearer ${SCRAPELESS_API_KEY} como el encabezado, Warp registra:

[error] MCP: Failed to connect to server: Transport creation error: MCP server 'scrapeless' rejected the configured credentials (HTTP 401). The request included the credential header(s) you configured, so the server did not accept that value — check the token itself, its expiry, and its scope. The server did not ask for OAuth.

El token en esa solicitud era válido. Scrapeless rechazó la solicitud porque el nombre del encabezado era incorrecto, y su cuerpo de respuesta así lo indica: Unauthorized: Missing x-api-token header. Cambia el nombre del encabezado y deja la clave sola.

Warp escribe un archivo de registro por cada inicio del servidor bajo ${XDG_STATE_HOME:-$HOME/.local/state}/warp-terminal/mcp en Linux. Cada archivo se abre con un recordatorio de que puede contener información sensible como claves API, así que léelo localmente y redacta antes de compartirlo.

Paso 5: Prueba la Clave, Luego Solicita el Agente

Un servidor en funcionamiento con 25 herramientas solo muestra que un encabezado llegó. Scrapeless responde initialize y tools/list para cualquier valor de clave, incluyendo uno inventado. La diferencia aparece en tools/call: con una clave mala, la llamada aún devuelve HTTP 200, y el texto del resultado comienza con Failed to fetch data.

Esta verificación ejecuta el mismo apretón de manos que ejecuta Warp y luego llama a scrape_markdown una vez, utilizando nada más allá de la biblioteca estándar de Python:

import json
import os
import urllib.request

URL = "https://api.scrapeless.com/mcp"
HEADERS = {
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
    "x-api-token": os.environ["SCRAPELESS_API_KEY"],
}


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": "key-check", "version": "1.0"}},
})
post({"jsonrpc": "2.0", "method": "notifications/initialized"}, session)
_, result = post({
    "jsonrpc": "2.0", "id": 2, "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"])
if text.startswith("Failed to fetch data"):
    print("key rejected:", text[:60])
else:
    print(f"key accepted: {len(text)} characters of Markdown")

Con una clave válida exportada, imprime:

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

Una vez que la clave se valida, nombra el servidor y la herramienta cuando el trabajo sea una única recuperación:
Nota: el turno del agente necesita créditos de IA en tu cuenta de Warp, y no se ejecutó para este artículo porque la cuenta de prueba no tenía más; Warp respondió "No tienes créditos de IA." El inicio del servidor, el apretón de manos y la verificación de la clave anterior se ejecutaron contra el mismo punto final con la misma configuración.

Use the scrapeless MCP server's scrape_markdown tool to fetch
https://books.toscrape.com/catalogue/category/books/mystery_3/index.html
and list the first three book titles with their prices.

En esa página de categoría scrape_markdown devuelve 8,940 caracteres donde scrape_html devuelve 53,800, por lo que Markdown le cuesta al agente aproximadamente un sexto del contexto para el mismo contenido. Usa scrape_html cuando tu propio código analiza el resultado y scrape_markdown cuando el agente lo lee.

Las llamadas a la herramienta MCP siguen tu perfil de ejecución activo. mcp_permissions por defecto es agent_decides, y los mcp_allowlist y mcp_denylist del perfil toman IDs de servidor MCP que pueden ejecutarse sin aprobación o deben preguntar siempre.

El anuncio del servidor MCP de Scrapeless describe lo que el servidor expone, la documentación de Browser MCP contiene la referencia de configuración, la página de Scraping API cubre a los actores detrás de las herramientas y la tarificación lista lo que cuesta una llamada.

Conclusión

El conector es una entrada en .warp/.mcp.json con tres condiciones: el encabezado se llama x-api-token, su valor es ${SCRAPELESS_API_KEY} con las llaves, y la variable se exporta en la terminal que inicia warp. Después de eso, inicia el servidor desde /mcp una vez por sesión.

Dos resultados necesitan cuidado porque se ven bien. Una forma de marcador de posición incorrecta y una clave incorrecta ambas muestran running · 25 tools, y solo una llamada a la herramienta las expone. Las fallas que sí aparecen se leen de manera diferente: un encabezado Bearer produce failed … rejected the configured credentials, y una variable no exportada produce un error de configuración que oculta cada servidor en el archivo.

¿Listo para darle al agente Warp una vista en vivo de la web? Comienza con el plan gratuito de Scrapeless y añade el servidor.

FAQ

P: ¿Cómo añado un servidor MCP remoto con un encabezado de clave API a Warp?

Crea .warp/.mcp.json en la raíz del proyecto con una entrada mcpServers que tenga un objeto url y un objeto headers, por ejemplo "x-api-token": "${SCRAPELESS_API_KEY}". Exporta la variable, inicia warp en esa carpeta, luego inicia el servidor desde /mcp. En la aplicación de escritorio de Warp, pega el mismo JSON bajo Configuración > Agentes > Servidores MCP > + Añadir.

P: ¿Warp expande las variables de entorno en los encabezados MCP?

Sí, en la forma ${VAR}. Un valor de encabezado de ${SCRAPELESS_API_KEY} llegó al servidor como la clave exportada. $SCRAPELESS_API_KEY sin llaves y {{SCRAPELESS_API_KEY}} se enviaron como texto literal.

P: ¿Por qué mi servidor MCP de Warp muestra que está en ejecución con una clave API incorrecta?

running · 25 tools significa que el apretón de manos y la lista de herramientas funcionaron, y Scrapeless responde ambos para cualquier valor de clave. Una clave incorrecta aparece solo cuando se ejecuta una herramienta: la llamada devuelve texto que comienza con Failed to fetch data.

P: ¿Por qué Warp dice que el servidor MCP rechazó las credenciales configuradas?

Para Scrapeless, la causa usual es el nombre del encabezado, no el token. Un encabezado Authorization: Bearer produce rejected the configured credentials (HTTP 401), porque el servidor busca x-api-token y responde Missing x-api-token header.

P: ¿Qué significa "Error de configuración de Warp … Variable de entorno faltante o vacía"?

El archivo hace referencia a una variable que no está configurada en la terminal que inició warp. Warp rechaza todo el archivo, por lo que cada servidor definido en él desaparece de /mcp hasta que exportes la variable y vuelvas a iniciar la CLI.

P: ¿Los servidores MCP limitados al proyecto se inician automáticamente en Warp?

No. Warp detecta .warp/.mcp.json, .mcp.json y .agents/.mcp.json en un proyecto pero lista sus servidores como offline hasta que inicies cada uno desde /mcp, y esa elección dura solo para la sesión actual.

P: ¿Por qué la CLI del agente Warp no lista mi servidor de ~/.warp_cli/.mcp.json?

La documentación de la CLI da esa ruta para macOS. En Linux, la CLI del agente Warp v0.2026.09.09.08.26.stable_02 no leyó ~/.warp_cli/.mcp.json o ~/.warp/.mcp.json, y /mcp respondió No matching MCP servers. El archivo del proyecto .warp/.mcp.json fue descubierto.

P: ¿Cuántas herramientas añade el servidor MCP de Scrapeless a Warp?
25: tres scrape_* herramientas, dieciséis browser_* herramientas, tres crawl_* herramientas, más google_search, google_trends y ai_scraper.