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

TL;DR:

• La CLI de Grok habla MCP, por lo que conectar Scrapeless es una tabla TOML: un url y un x-api-token encabezado.
• grok mcp doctor responde si funcionó — ✓ server started (1.0s), ✓ handshake OK (protocol 2025-06-18), ✓ 25 tools discovered.
• El alcance decide si el servidor se ejecuta en absoluto. Un .grok/config.toml local en un carpeta no confiable informa ✗ folder untrusted y se cuenta como 0 servidores; la misma tabla en el alcance del usuario comienza.
• El encabezado es x-api-token, no Authorization: Bearer. Un encabezado Bearer falla el apretón de manos: grok mcp doctor informa ✗ handshake failed con HTTP 401.
• grok mcp add --header "..." escribe la configuración correcta y coloca tu clave en el historial de shell; escribir la tabla tú mismo no lo hace.
• 25 tools discovered prueba que el encabezado llegó, no que la clave es válida — Scrapeless lista todas las 25 herramientas para cualquier valor de clave. Una tools/call real que devuelve contenido de página es la única prueba de que la credencial funciona.
• Consigue una clave en el plan gratuito de Scrapeless primero.

Un agente en una terminal es bueno leyendo archivos y ejecutando comandos, y ciego a cualquier cosa en la web abierta. MCP es cómo se cierra esa brecha: el cliente acuña definiciones de herramientas de un servidor, el modelo elige una en medio de la vuelta, y "¿qué dice esta página en este momento?" se convierte en una llamada en lugar de un copiar-pegar.

La CLI de Grok tiene una implementación de MCP de primera clase, incluyendo un subcomando de diagnóstico que informa qué etapa de una conexión falló en lugar de un único rojo o verde. Configurar el conector requiere dos tablas TOML; leer ese diagnóstico es la parte que ahorra tiempo más tarde.

Lo Que Obtienes

Veinticinco herramientas, enumeradas desde un tools/list en vivo en lugar de copiadas de la documentación:

scrape_markdown cubre la mayoría de lo que un agente pide — una llamada, un documento. El grupo browser_* es una sesión que el modelo impulsa a través de varias vueltas, que es lo que cualquier cosa detrás de un clic o un inicio de sesión necesita.

Prerrequisitos

• La CLI de Grok. La versión utilizada aquí es grok 0.2.118 (1e1687c1cf).
• Una clave de API de Scrapeless.
• Nada que instalar para el servidor. Está alojado, por lo que no hay paquete ni proceso local — el cliente se conecta a una URL a través de HTTP transmitible, uno de los dos transportes la especificación del Protocolo de Contexto del Modelo define.

Paso 1: Agregar el Servidor

La CLI tiene un subcomando para ello:

grok mcp add -t http -s user scrapeless https://api.scrapeless.com/mcp \
  --header "x-api-token: YOUR_SCRAPELESS_API_KEY"

Added HTTP MCP server 'scrapeless' with URL: https://api.scrapeless.com/mcp to user config
File modified: ~/.grok/config.toml

-t http selecciona el transporte (las alternativas son stdio y el sse obsoleto), y -s user escribe en ~/.grok/config.toml en lugar del repositorio.

Lo que escribe es un par de tablas TOML:

[mcp_servers.scrapeless]
url = "https://api.scrapeless.com/mcp"
enabled = true

[mcp_servers.scrapeless.headers]
x-api-token = "YOUR_SCRAPELESS_API_KEY"

Sabiendo que la forma importa, porque la bandera --header coloca tu clave en el historial de shell y en la lista de procesos mientras se ejecuta el comando. Escribir esas seis líneas tú mismo evita ambas cosas, y te permite añadir los tiempos de espera que la CLI no establece:

[mcp_servers.scrapeless]
url = "https://api.scrapeless.com/mcp"
startup_timeout_sec = 30
tool_timeout_sec = 120

[mcp_servers.scrapeless.headers]
x-api-token = "YOUR_SCRAPELESS_API_KEY"

El nombre del encabezado es el detalle a acertar. Scrapeless lee x-api-token; la mayoría de los ejemplos de MCP muestran Authorization: Bearer porque eso es lo que el marco de autenticación HTTP especifica para credenciales de portador. Un encabezado Bearer aquí falla antes de que se complete el apretón de manos — la solicitud initialize regresa HTTP 401 Unauthorized: Missing x-api-token header, y el doctor cuenta el servidor como fallido.

Paso 2: Leer el Diagnóstico

Esta es la parte que vale la pena aprender. grok mcp doctor informa cada etapa por separado:

MCP Doctor

  Config sources
    ~/.grok/config.toml                      1 server
    ~/.claude.json                           not found
    .mcp.json                                not found
    grok.com                                 skipped (not logged in)

  scrapeless (http: https://api.scrapeless.com/mcp)
    ✓ server started (1.0s)
    ✓ handshake OK (protocol 2025-06-18)
    ✓ 25 tools discovered

Cuatro hechos independientes en esa salida. Qué archivos de configuración se leyeron y cuántos servidores contribuyeron a cada uno. Si la conexión se abrió, y cuánto tiempo tardó. Si el apretón de manos de MCP se completó, y en qué versión del protocolo. Y cuántas herramientas regresaron del descubrimiento.

Esos últimos dos son intercambios ordinarios JSON-RPC 2.0 — una solicitud initialize seguida de un tools/list — que es por qué pueden tener éxito o fallar independientemente el uno del otro.
Un fallo en cualquiera de esos puntos se debe a una causa diferente, razón por la cual la salida en etapas supera a un solo rojo o verde. También hay un modo --json cuando deseas afirmar esto en un script en lugar de leerlo.

grok mcp list es la verificación más rápida una vez que está funcionando:

  scrapeless: https://api.scrapeless.com/mcp

Paso 3: Entender el Alcance, O No Empezará

Grok lee la configuración de MCP desde el alcance del usuario y desde un .grok/config.toml local del repositorio. La segunda tiene una condición adjunta que produce una primera ejecución confusa.

La misma tabla de servidor, colocada en una carpeta de proyecto:

  Config sources
    ~/.grok/config.toml                      not found
    /root/verify-grok-proj/.grok/config.toml 0 servers

  scrapeless (http: https://api.scrapeless.com/mcp)
    ✗ folder untrusted (repo-local (project-scoped) server not started for an untrusted folder)

Dos cosas a notar. El servidor no se inició: un servidor MCP en el ámbito del proyecto no se lanza hasta que la carpeta es de confianza, porque un archivo de configuración en un repositorio revisado puede de otro modo dirigir a tu agente a cualquier punto final que el autor elija. Y la línea de la fuente de configuración indica 0 servidores a pesar de que el archivo define uno, por lo que contar fuentes no es suficiente para decirte que la configuración fue aceptada.

Utiliza el alcance del usuario para una clave que es tuya. Utiliza el alcance del proyecto para compartir un servidor con un equipo, y espera el paso de confianza de la carpeta por máquina.

Paso 4: Confirmar la Capacidad, No la Insignia

25 tools discovered es el resultado de un tools/list, y esa llamada es respondida por el propio servidor MCP; nunca llega a la API ascendente. Así que el descubrimiento tiene éxito independientemente de si la credencial detrás de esto es buena o no.

Esa no es una distinción teórica. Una puerta de enlace de enrutamiento que enfrenta este mismo punto final con un token almacenado obsoleto descubrió su conjunto completo de herramientas y luego devolvió un error de token inválido en la primera llamada real, mientras que el mismo punto final con una clave en funcionamiento devolvió HTTP 200.

La verificación que lo establece es una llamada de herramienta:

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 ese resultado es la evidencia. Todo lo anterior es un informe de configuración sobre sí mismo: con una clave incorrecta la llamada aún devuelve HTTP 200, sin una isError bandera, y su texto comienza con Failed to fetch data.

Nota: hacer esa llamada desde dentro de un giro de Grok necesita autenticación xAI, que el entorno de este tutorial no tenía — grok -p "..." devuelve Not signed in. El conector, el apretón de manos, el descubrimiento y la llamada de herramienta anterior están todos verificados; el giro final autorizado por el modelo es el único paso tomado en confianza aquí. Inicia sesión con grok login o configura XAI_API_KEY y las mismas herramientas están disponibles para el modelo.

Paso 5: Provocarlo

Una vez que las herramientas son descubiertas, el modelo elige entre ellas. Nombrar la herramienta elimina una ronda de adivinanzas:

Use the scrapeless scrape_markdown tool on
https://books.toscrape.com/catalogue/category/books/mystery_3/index.html
and give me the first five titles with their prices as a table.

Dos hábitos ayudan. Nombra la herramienta cuando el trabajo es una sola obtención, y describe la secuencia cuando no lo es — las herramientas browser_* comparten una sesión, por lo que "crear una sesión, ir a la URL, hacer clic en el filtro, luego leer el texto" es una instrucción diferente de cuatro no relacionadas.

Y pide la forma de salida que deseas. scrape_markdown devuelve un documento; si obtienes una tabla o un párrafo lo decide el aviso, no la herramienta.

¿Estableciendo esto ahora? El plan gratuito de Scrapeless cubre suficientes llamadas para atravesar el apretón de manos y las primeras llamadas de herramientas.

Lo Que Regresa

scrape_markdown devuelve la página en Markdown en el bloque de contenido:

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 el predeterminado correcto para un modelo. La misma página tiene 8,940 caracteres desde scrape_markdown frente a 53,800 desde scrape_html, así que scrape_html gasta aproximadamente seis veces el contexto en un marcado que nadie lee. Utiliza scrape_html cuando tu propio código parseará el resultado, y scrape_markdown cuando el modelo es el consumidor.

Un Enrutador Cambia el Conteo de Herramientas

Si el cliente apunta a una puerta de enlace que enfrenta varios servidores MCP detrás de una URL, la lista descubierta son las propias herramientas de despacho del enrutador en lugar de las del proveedor. El mismo cliente, el mismo comando: 3 herramientas a través de una puerta de enlace de enrutamiento inteligente, 25 contra https://api.scrapeless.com/mcp directamente.

Ambos arreglos son legítimos. Un enrutador mantiene una credencial y un registro de auditoría a través de muchos proveedores; una conexión directa le da al modelo la verdadera superficie de herramientas. La cantidad de herramientas de grok mcp doctor te dice cuál estás ejecutando, lo cual es razón suficiente para leerlo después de cualquier cambio en la configuración.
Para el mismo producto impulsado por código en lugar de un agente, nuestra guía de web scraping de Grok cubre el patrón modelo-plus-fetch, y el post de lanzamiento del servidor MCP cubre lo que expone el servidor. La página de la API de Scraping describe la familia de actores detrás de estas herramientas, los documentos llevan la referencia por actor, y precios enumeran lo que cuesta una llamada.

Conclusión

Dos tablas TOML y un nombre de encabezado son el conector completo. grok mcp doctor te dice cuál de las cuatro etapas funcionó, y su línea 25 tools discovered es la que debes verificar después de cualquier cambio — porque 3 significa que estás hablando con un enrutador y 0 servidores de un archivo que tiene uno significa que la carpeta no es de confianza.

Los dos errores que vale la pena evitar son ambos baratos. Usa x-api-token en lugar de un encabezado Bearer, ya que la versión Bearer es rechazada con un 401 durante el apretón de manos y grok mcp doctor la marca inmediatamente. Y trata el descubrimiento como un informe de configuración sobre sí mismo: un tools/call que devuelve contenido de página real es lo que realmente prueba que la credencial funciona.

¿Listo para dar a Grok un fetch que pueda llamar? Comienza con el plan gratuito de Scrapeless y añade el servidor.

FAQ

Q: ¿Grok soporta servidores MCP?

Sí. La CLI tiene un subcomando dedicado grok mcp con add, list, remove, enable, disable y doctor, y soporta los transportes stdio, http y sse. HTTP remoto es el que se debe usar para un servidor alojado como este, ya que no necesita ningún proceso local.

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

grok mcp add -t http -s user scrapeless https://api.scrapeless.com/mcp --header "x-api-token: ...", o escribe las tablas equivalentes [mcp_servers.scrapeless] y [mcp_servers.scrapeless.headers] en ~/.grok/config.toml tú mismo. La ruta escrita mantiene la clave fuera del historial de la shell y te permite establecer startup_timeout_sec y tool_timeout_sec.

Q: ¿Por qué no se inicia mi servidor MCP de ámbito del proyecto?

Porque la carpeta no es de confianza. Un .grok/config.toml local en el repositorio no se lanza hasta que confías en la carpeta, y el diagnóstico lo dice explícitamente: ✗ folder untrusted (repo-local (project-scoped) server not started for an untrusted folder). La línea de config-source también lo cuenta como 0 servidores, lo que hace que el archivo parezca vacío cuando no lo está. Mover la entrada al ámbito del usuario evita la puerta cuando la clave es tuya.

Q: ¿Debería el encabezado ser x-api-token o Authorization: Bearer?

x-api-token. Una solicitud sin él devuelve 401 Unauthorized: Missing x-api-token header. Un encabezado Bearer es rechazado de la misma manera en el apretón de manos, así que grok mcp doctor muestra ✗ handshake failed y Found 0 healthy, 1 failing — el doctor atrapa el error de una palabra antes de cualquier llamada a la herramienta.

Q: ¿Cómo puedo comprobar qué herramientas puede ver Grok?

grok mcp doctor imprime la cuenta descubierta por servidor, y --json da lo mismo de manera legible por máquina. Contra este endpoint informa 25. Si ves 3, el cliente está apuntando a una puerta de enlace de enrutamiento en lugar del servidor, y esas tres son las herramientas de despacho del enrutador.

Q: ¿Es 25 tools discovered suficiente para saber si funciona?

No. El descubrimiento es un tools/list, al que el servidor MCP responde localmente sin contactar a la API upstream, por lo que tiene éxito incluso contra una credencial rechazada. Haz una llamada a la herramienta y busca contenido de página real; una clave incorrecta devuelve texto que comienza con Failed to fetch data, y Scrapeless no establece isError en él.

Q: ¿Necesito estar conectado a xAI para que el conector funcione?

El conector en sí no lo necesita: el apretón de manos y el descubrimiento de herramientas funcionan sin ninguna credencial de xAI. Hacer que el modelo realmente llame a una herramienta sí lo requiere, porque ese es un giro de inferencia de Grok — sin él, grok -p "..." devuelve Not signed in. Ejecuta grok login o establece XAI_API_KEY.

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

Sí, del lado del cliente. La CLI expone reglas de permiso de permitir y denegar más --tools y --disallowed-tools para las integradas, por lo 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. Enfócalo en el trabajo.