Droid de Fábrica + Sin Chatarra: Agregar un Servidor MCP Remoto

TL;DR:

• droid mcp add conecta Scrapeless en un comando. Usa --type http, un encabezado x-api-token y --no-oauth; la entrada se coloca en ~/.factory/mcp.json.
• Escribe la clave como ${SCRAPELESS_API_KEY}, con llaves. Droid expande esa forma y nombra la variable cuando no está configurada, pero envía un $SCRAPELESS_API_KEY sin formato como texto literal.
• Un proyecto .factory/mcp.json puede llevar la referencia de forma segura. La clave permanece en el entorno de cada desarrollador, y el servidor se lista como connected [project].
• droid mcp list separa cuatro problemas diferentes. connected, needs authentication, failed: Failed to connect to MCP server y un fallo por variable no establecida apuntan cada uno a una solución diferente.
• connected prueba que el encabezado llegó, no que la clave funcione. Una clave inventada también se lista como conectada, así que confirma con una llamada a la herramienta.
• Una llamada a la herramienta sin encabezado necesita --auto high, así que defínela. droid exec --auto high --only-tools 'MCP:scrapeless/scrape_markdown' permite que la llamada de ejecución llame a esa herramienta y nada más.
• Consigue una clave en el plan gratuito de Scrapeless y añade el servidor en un par de minutos.

Factory Droid planea y edita el código desde tu terminal, y droid exec ejecuta el mismo agente sin encabezado en scripts y CI. Ninguno de los modos puede mirar una página web por sí mismo. Un servidor MCP le proporciona a Droid herramientas que llama durante una tarea, y el servidor MCP Scrapeless alojado suministra la recuperación de páginas, un navegador en la nube y búsqueda.

La configuración es un comando. Lo que decide si se mantiene es cómo la clave alcanza el encabezado, en qué archivo de configuración vive la entrada, y qué droid mcp list está reportando realmente.

Lo Que Droid Puede Llamar Una Vez Agregado Scrapeless

El servidor Scrapeless expone 25 herramientas. scrape_markdown, scrape_html y scrape_screenshot devuelven una página en una llamada. Dieciséis herramientas browser_*, desde browser_create hasta browser_close, ejecutan una sesión de navegador en la nube paso a paso. crawl_start, crawl_result y crawl_cancel gestionan un rastreo. google_search y google_trends devuelven datos de búsqueda y tendencias, y ai_scraper captura respuestas de asistentes de IA como ChatGPT y Perplexity.

La arquitectura MCP separa al cliente que llama a las herramientas del servidor que las proporciona, razón por la cual Droid necesita solo una URL y un encabezado para usar un servidor alojado en otro lugar.

Requisitos Previos

• Factory Droid CLI. Esta guía utilizó las versiones 0.213.0 y 0.220.0.
• Una cuenta Factory iniciada sesión, o FACTORY_API_KEY establecida, para el paso donde el modelo ejecuta un aviso.
• Una clave API de Scrapeless del panel de control de Scrapeless.

Paso 1: Agregar el Servidor

droid mcp add scrapeless https://api.scrapeless.com/mcp --type http --header "x-api-token: YOUR_SCRAPELESS_API_KEY" --no-oauth

--type http selecciona el transporte HTTP transmitible; el tipo predeterminado es stdio, que trataría la URL como un comando para lanzar. --no-oauth desactiva el flujo OAuth que Droid ofrece de otra manera para un servidor remoto autenticado por encabezado.

Added HTTP MCP server scrapeless with URL: https://api.scrapeless.com/mcp

La entrada escrita en ~/.factory/mcp.json:

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

"oauth": false es lo que --no-oauth agregó. "disabled": false mantiene el servidor activo.

Paso 2: Poner una Referencia de Variable en el Encabezado

El comando anterior deja una clave literal en el archivo. Reemplázala con ${SCRAPELESS_API_KEY} para que el archivo contenga un nombre y tu shell contenga el valor. Las llaves importan: Droid expande la forma con llaves de expansión de parámetros POSIX y pasa un $SCRAPELESS_API_KEY sin modificar.

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

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

Configured MCP servers:
  scrapeless  http  connected  [user]

Cuando la variable no está establecida en esa shell, Droid la nombra en lugar de fallar vagamente:

  scrapeless  http  failed: MCP server credential references an unset environment variable "SCRAPELESS_API_KEY"  [user]

Deja las llaves fuera y esa advertencia nunca aparece. Droid envía el texto literal $SCRAPELESS_API_KEY, el servidor aún se lista como connected, y el problema surge solo en la primera llamada a la herramienta.

Paso 3: Compartir el Servidor a Través de un Proyecto mcp.json

Droid también lee .factory/mcp.json de un proyecto, por lo que el servidor puede vivir en el repositorio para todos los que lo clonen. Una clave literal en ese archivo sería comprometida junto con él, y credenciales codificadas son una debilidad de software catalogada por esa razón. La referencia con llaves es segura para comprometer porque cada desarrollador proporciona una clave desde su propio entorno. Guarda el mismo JSON como .factory/mcp.json en la raíz del repositorio:

  scrapeless  http  connected  [project]

La etiqueta entre corchetes es el alcance desde el cual Droid cargó la entrada, que es la forma más rápida de confirmar que el archivo del proyecto es el que está en efecto. Sin la variable, la entrada del proyecto informa el mismo fallo por variable no establecida, etiquetado como [project].
¿Configurándolo ahora? El plan gratuito de Scrapeless cubre la conexión y tus primeras llamadas de herramientas.

Paso 4: Leer lo que informa la lista droid mcp

Las filas de Bearer aparecen más porque casi todos los ejemplos de MCP se autentican de esa manera. Scrapeless responde a una solicitud sin x-api-token con una respuesta 401 No autorizado, y con OAuth activado, Droid lo lee como una solicitud de inicio de sesión:

  scrapeless  http  needs authentication  [user]
Some servers need authentication. Start droid and run /mcp to authenticate.

Ejecutar /mcp no lo resuelve, porque el punto final de Scrapeless no tiene un flujo OAuth que completar. Cambia el encabezado en su lugar.

El estado que puede llevar a confusión es connected. El apretón de manos de Scrapeless acepta cualquier valor x-api-token no vacío, por lo que una clave mal escrita o revocada se lista exactamente como una buena.

Paso 5: Ejecutar Droid sólo con herramientas Scrapeless

droid exec ejecuta un aviso sin cabeza, y comienza en modo sólo lectura. Una llamada a una herramienta MCP está más allá de ese modo: en Droid 0.220.0 la ejecución se detiene con "permiso insuficiente para continuar", y --auto medium aún responde "Reejecuta con --auto high". La bandera --only-tools acepta selectores de MCP, así que empareja el nivel de autonomía más alto con un selector que permita una herramienta:

droid exec --auto high --only-tools 'MCP:scrapeless/scrape_markdown' "Use the scrapeless MCP server's scrape_markdown tool on https://example.com and reply with the first heading of the page, quoted exactly."

Droid responde:

The first heading of the page is:

"Example Domain"

Añadir --list-tools al mismo selector muestra a qué puede llegar esa ejecución. Droid nombra a las herramientas MCP <server>___<tool>, y scrapeless___scrape_markdown es la única marcada como permitida, y las otras 24 herramientas Scrapeless y las herramientas de archivo y shell integradas de Droid están marcadas como bloqueadas. 'MCP:scrapeless' permite las 25 herramientas Scrapeless en su lugar, y --add-tools y --remove-tools aceptan los mismos selectores.

El contenido de la página en el resultado es la confirmación. Con una clave incorrecta la misma llamada aún devuelve HTTP 200, y el texto del resultado comienza con Failed to fetch data; Scrapeless no lo marca como un error de MCP, así que lee el texto en lugar del estado.

Para más información sobre el servidor en sí, el anuncio del servidor MCP de Scrapeless cubre lo que expone y nuestra guía de integración de MCP compara cómo los agentes acceden a un navegador. La documentación de Browser MCP tiene la referencia de configuración, la página de API de Scraping describe a los actores detrás de las herramientas, y precios enumera cuánto cuesta una llamada.

Conclusión

Agregar Scrapeless a Droid es un comando. Mantener la configuración confiable se reduce a lo que droid mcp list puede y no puede ver: la referencia ${SCRAPELESS_API_KEY} entre llaves permite a Droid nombrar una variable faltante, --no-oauth convierte un error de encabezado en un fallo en lugar de un aviso de inicio de sesión, y sólo una llamada a la herramienta, no un estado connected, prueba que la clave funciona.

Coloca la referencia entre llaves en un .factory/mcp.json de proyecto y todo el equipo obtiene el servidor sin que nadie comprometa una clave.

¿Listo para darle a Droid una vista en vivo de la web? Empieza con el plan gratuito de Scrapeless y añade el servidor.

Preguntas frecuentes

Q: ¿Cómo añado un servidor MCP remoto con una clave API a Factory Droid?

Ejecuta droid mcp add scrapeless https://api.scrapeless.com/mcp --type http --header "x-api-token: YOUR_SCRAPELESS_API_KEY" --no-oauth. La entrada se va a ~/.factory/mcp.json, donde puedes reemplazar la clave literal con ${SCRAPELESS_API_KEY}.

Q: ¿Droid expande variables de entorno en los encabezados de MCP?

Sí, en la forma entre llaves. ${SCRAPELESS_API_KEY} se reemplaza con el valor de la variable, y una variable no establecida produce un estado fallido que la nombra. Un $SCRAPELESS_API_KEY desnudo se envía como texto literal.
Q: ¿Por qué dice la lista de droid mcp que se necesita autenticación?

El servidor devolvió un 401 mientras OAuth estaba habilitado, así que Droid ofrece un inicio de sesión. Para Scrapeless, eso casi siempre significa un Authorization: Bearer encabezado. Usa x-api-token y agrega --no-oauth; ejecutar /mcp no puede arreglar un desajuste de encabezado.

Q: ¿Cuál es la diferencia entre ~/.factory/mcp.json y .factory/mcp.json?

~/.factory/mcp.json es tu configuración de usuario y se aplica en cada proyecto. .factory/mcp.json en un repositorio se aplica a ese proyecto, aparece como [project] en droid mcp list, y puede ser comprometido siempre que la clave sea una referencia ${SCRAPELESS_API_KEY}.

Q: ¿Conectado significa que mi clave de Scrapeless es válida?

No. El apretón de manos de Scrapeless acepta cualquier valor x-api-token no vacío, así que una clave incorrecta también se lista como connected. Una llamada a la herramienta que devuelve el contenido de la página es la prueba; una clave mala devuelve texto que comienza con Failed to fetch data.

Q: ¿Cómo limito la ejecución de droid a herramientas de Scrapeless?

Pasa --only-tools 'MCP:scrapeless' para cada herramienta de Scrapeless, o 'MCP:scrapeless/scrape_markdown' para una, junto con --auto high, que es lo que necesita una llamada a la herramienta MCP. --add-tools y --remove-tools toman los mismos selectores.

Q: ¿Cómo elimino el servidor de Scrapeless de Droid?

Ejecuta droid mcp remove scrapeless. El comando elimina la entrada del archivo de configuración que lo define.