OpenCode + Scrapeless: Conectar un servidor MCP remoto

TL;DR:

• OpenCode toma Scrapeless como un remote servidor MCP en opencode.json. La entrada necesita un url, un encabezado x-api-token y "oauth": false.
• Escribe la clave como {env:SCRAPELESS_API_KEY}, no ${SCRAPELESS_API_KEY}. OpenCode sustituye la primera forma y envía la segunda como texto literal, y el servidor sigue apareciendo como conectado mientras cada llamada a la herramienta falla con un 401.
• ✓ connected solo demuestra que el encabezado está presente. El apretón de manos de Scrapeless acepta cualquier valor de x-api-token y aún lista todas las 25 herramientas, así que lee un resultado de herramienta antes de confiar en la configuración.
• La configuración oauth decide cómo se ve un error de Bearer. Si se deja en su valor por defecto, un encabezado Authorization: Bearer muestra ⚠ needs authentication; con "oauth": false el mismo encabezado muestra ✗ failed con un 401.
• Las herramientas llegan nombradas <server>_<tool>. Una entrada de servidor llamada scrapeless da el modelo scrapeless_scrape_markdown, y las 25 definiciones regresan como una respuesta tools/list de alrededor de 30 KB.
• Consigue una clave en el plan gratuito de Scrapeless y conecta OpenCode en un par de minutos.

OpenCode ejecuta un agente de codificación en tu terminal contra el proveedor de modelo que configures. Lee archivos y ejecuta comandos, pero una pregunta sobre una página web en vivo necesita una herramienta que obtenga una, y un servidor MCP es cómo OpenCode recoge herramientas que no envía con él.

El servidor MCP de Scrapeless está alojado, así que conectarlo es configuración, no instalación. Esta guía cubre la entrada de configuración, la sintaxis de sustitución que falla silenciosamente, qué significa cada estado opencode mcp list, y cómo distinguir una clave que funciona de un servidor que solo se conectó.

Lo que OpenCode obtiene de Scrapeless

El servidor lista 25 herramientas. Tres devuelven una página en una llamada: scrape_markdown, scrape_html y scrape_screenshot. Dieciséis herramientas browser_*, como browser_create, browser_goto, browser_click y browser_type, manejan una sesión de navegador en la nube un paso a la vez. crawl_start, crawl_result y crawl_cancel gestionan una exploración, y google_search, google_trends y ai_scraper completan el conjunto.

Para la mayoría de las solicitudes, la útil es scrape_markdown. Devuelve la página renderizada como Markdown, que es la forma en que un modelo lee más barato, y no necesita nada más que una URL.

Requisitos

• OpenCode, con un proveedor de modelo ya configurado. Esta guía utiliza OpenCode 1.17.19.
• Una clave API de Scrapeless del panel de control de Scrapeless.
• Nada que instalar para el servidor. Se ejecuta en https://api.scrapeless.com/mcp y OpenCode se conecta a través de HTTP.

Paso 1: Agregar el servidor a opencode.json

OpenCode lee los servidores MCP del bloque mcp de su configuración. El archivo global es ~/.config/opencode/opencode.json, y un opencode.json en la raíz de un proyecto se aplica a ese proyecto:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "scrapeless": {
      "type": "remote",
      "url": "https://api.scrapeless.com/mcp",
      "oauth": false,
      "headers": {
        "x-api-token": "{env:SCRAPELESS_API_KEY}"
      }
    }
  }
}

"type": "remote" hace que OpenCode se conecte a través de HTTP en lugar de lanzar un comando local. "oauth": false impide que inicie un flujo de OAuth, que el punto final de Scrapeless no ofrece; sus rutas de descubrimiento de OAuth devuelven 404, y se autentica solo en el encabezado. opencode mcp add también puede escribir una entrada y acepta banderas --url y --header, pero editar el archivo directamente es la forma confiable de obtener la referencia {env:} exactamente correcta.

Paso 2: Usar {env:} sustitución, no ${}

OpenCode sustituye {env:VARIABLE_NAME} con el valor de esa variable de entorno cuando carga la configuración. Las variables de entorno son el hogar habitual para credenciales que cambian entre máquinas, la misma división que la guía de configuración de la aplicación de doce factores recomienda, y {env:} es cómo OpenCode las lee. Exporta la clave en la terminal que inicia OpenCode:

export SCRAPELESS_API_KEY="your-scrapeless-api-key"
opencode mcp list

●  ✓ scrapeless connected
│      https://api.scrapeless.com/mcp

El estilo de terminal ${SCRAPELESS_API_KEY} parece equivalente y no lo es. OpenCode lo pasa como texto literal, y dado que el apretón de manos de Scrapeless acepta cualquier token no vacío, el servidor aún lista ✓ connected. El problema solo se presenta cuando el modelo llama a una herramienta:

Failed to fetch data. Error: [Scrapeless]: Request POST /api/v1/unlocker/request failed with status 401

Dejar la variable no exportada falla antes y de manera más visible. Con {env:SCRAPELESS_API_KEY} apuntando a nada, el apretón de manos en sí es rechazado:

●  ✗ scrapeless failed
│      SSE error: Non-200 status code (401)
│      https://api.scrapeless.com/mcp

¿Configurándolo ahora? El plan gratuito de Scrapeless cubre la conexión y tus primeras llamadas a herramientas.

Paso 3: Leer cada estado de la lista mcp de opencode

La línea de estado dice si OpenCode pudo abrir la conexión. No dice si la clave funciona.

Un modo de falla se comporta como una clave mala y no lo es. Si la línea de estado dice conectado y una llamada a la herramienta responde Failed to fetch data, verifique si otro servidor MCP en la máquina expone las mismas herramientas Scrapeless, como una puerta de enlace que enruta varios proveedores detrás de una sola credencial. El agente puede haber llamado a ese en su lugar. OpenCode antepone cada herramienta con el nombre de su servidor, por lo que la línea del transcripción nombra el servidor que respondió.

La mayoría de los ejemplos de MCP se autentican con Authorization: Bearer, el esquema la especificación del token Bearer de OAuth 2.0 define. Scrapeless lee x-api-token en su lugar, por lo que un encabezado Bearer recibe una respuesta 401 No autorizado. Con oauth en su valor predeterminado, OpenCode trata ese 401 como un aviso para iniciar sesión:

●  ⚠ scrapeless needs authentication
│      https://api.scrapeless.com/mcp

Con "oauth": false, el mismo encabezado se lee ✗ failed con el 401, que describe un encabezado incorrecto de manera más precisa que una invitación a autenticarse.

Paso 4: Llamar a una herramienta desde un aviso

Nombra el servidor y la herramienta la primera vez, para que el resultado tenga solo una fuente posible:

Use the scrapeless MCP server's scrape_markdown tool on https://example.com
and reply with the first markdown heading line.

opencode run --format json imprime cada paso como un evento JSON. El evento de la herramienta de ese aviso:

type: tool_use
tool: scrapeless_scrape_markdown
status: completed
output: Response: "# Example Domain\n\nThis domain is for use in documentation ...

La respuesta del modelo fue # Example Domain. El nombre de la herramienta sigue el patrón <server>_<tool> de OpenCode, por lo que una entrada llamada scrapeless coloca el mismo prefijo en las 25 herramientas.

Esa salida es la verificación que opencode mcp list no puede darte. Un resultado que comienza con contenido de página significa que la clave funciona. Un resultado que comienza con Failed to fetch data significa que la conexión está bien y que la clave no lo está. La especificación de herramientas MCP proporciona una isError bandera para llamadas fallidas, pero Scrapeless devuelve ambos resultados como texto de herramienta ordinario sin ella, así que el texto es lo que se debe leer.

Cada servidor conectado también agrega sus definiciones de herramientas al contexto del modelo, y la respuesta Scrapeless tools/list para todas las 25 herramientas es de aproximadamente 30 KB. Configurar "enabled": false en la entrada mantiene su configuración pero fuera de sesiones que no necesitan la web.

Para lo que el servidor expone, el anuncio del servidor MCP Scrapeless cubre el lanzamiento, y nuestra guía de integración MCP compara las formas en que los agentes acceden a un navegador. La documentación de Browser MCP contiene la referencia de configuración, la página de API de scraping describe a los actores detrás de las herramientas, y precios enumera el costo de una llamada.

Conclusión

OpenCode necesita cuatro cosas de la entrada: "type": "remote", la URL de Scrapeless, un encabezado x-api-token escrito como {env:SCRAPELESS_API_KEY}, y "oauth": false. La sintaxis de sustitución es el detalle más propenso a fallar, porque la forma rota aún conecta.

opencode mcp list captura un encabezado faltante, una variable no exportada y un error de mezcla de Bearer. Solo un resultado de herramienta captura una clave mala, así que haz una llamada y lee lo que vuelve antes de construir algo sobre la conexión.

¿Listo para darle a OpenCode una vista en vivo de la web? Comienza con el plan gratuito de Scrapeless y agrega el servidor.

FAQ

P: ¿Cómo agrego un servidor MCP remoto con un encabezado de clave API a OpenCode?

Agrega una entrada bajo mcp en opencode.json con "type": "remote", el servidor url, "oauth": false y un objeto headers. Para Scrapeless el encabezado es x-api-token, escrito como {env:SCRAPELESS_API_KEY} para que la clave se mantenga fuera del archivo.

P: ¿Por qué no funciona ${SCRAPELESS_API_KEY} en opencode.json?
La sintaxis de sustitución de OpenCode es {env:SCRAPELESS_API_KEY}. La forma estilo shell se envía como texto literal, por lo que el servidor sigue apareciendo como conectado y las llamadas a herramientas regresan con failed with status 401.

P: ¿Por qué dice la lista de mcp de opencode que necesita autenticación?

El servidor devolvió un 401 mientras oauth estaba habilitado, por lo que OpenCode ofrece un inicio de sesión. Para Scrapeless eso casi siempre significa un encabezado Authorization: Bearer; cambia a x-api-token y establece "oauth": false.

P: ¿Significa "conectado" que mi clave de Scrapeless es válida?

No. El apretón de manos de Scrapeless y la lista de herramientas tienen éxito con cualquier valor de x-api-token que no esté vacío. Solo una llamada a la herramienta revela una clave incorrecta, como resultado que comienza con Failed to fetch data.

P: ¿Cuáles son los nombres de las herramientas de Scrapeless dentro de OpenCode?

OpenCode nombra las herramientas MCP <server>_<tool>. Con la entrada llamada scrapeless, el modelo ve scrapeless_scrape_markdown y el mismo prefijo en las otras 24 herramientas.

P: ¿De dónde lee OpenCode opencode.json?

La configuración global es ~/.config/opencode/opencode.json, y un proyecto puede agregar su propio opencode.json en su raíz. La variable de entorno OPENCODE_CONFIG apunta a OpenCode a un archivo de configuración específico en su lugar.

P: ¿Necesito instalar un paquete para el servidor MCP de Scrapeless?

No. El servidor está alojado en https://api.scrapeless.com/mcp, y OpenCode se conecta a él a través de HTTP, por lo que no hay paquete, ni proceso local y ninguna versión que mantener actualizada.