Integración de agentes MCP

El servidor MCP de Sa2web expone el navegador remoto como herramientas MCP estándar para Claude Code, Claude Desktop, Cursor, Windsurf, VS Code Copilot, Cline, Roo Code, opencode, Gemini CLI, Zed, Hermes Agent y OpenClaw.

El proyecto MCP es open source en sa2web/sa2web-mcp y está publicado en npm como @sa2web/mcp.

Para utilizarlo directamente desde el terminal, consulte CLI del navegador remoto.

El sitio de destino se muestra dentro de iframe#rbi-frame y el servidor lo controla mediante Playwright.

Instalación

Instale Node.js 18 o posterior y luego instale el paquete npm de forma global:

npm install @sa2web/mcp -g
npx playwright install --with-deps

Esto añade sa2, sa2-browser y la entrada MCP sa2-mcp al PATH.

Para desarrollar desde el código fuente, clone el repositorio público y compile:

git clone https://github.com/sa2web/sa2web-mcp.git
cd sa2web-mcp
npm install
npx playwright install --with-deps
npm run build

Configuración del cliente

Después de la instalación global, use sa2-mcp directamente:

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "sa2-mcp",
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

Si el cliente no resuelve comandos globales, use la ruta completa de sa2-mcp o node /absolute/path/to/sa2web-mcp/dist/server.js desde una compilación local.

{
  "mcpServers": {
    "sa2-remote-browser": {
      "command": "node",
      "args": ["/absolute/path/to/sa2web-mcp/dist/server.js"],
      "env": {
        "SA2_LOGIN_URL": "https://<APP_DOMAIN>/agent/login?clientId=...&clientSecret=...",
        "SA2_LOGIN_REDIRECT_PATH": "/app/login",
        "SA2_HEADLESS": "false",
        "SA2_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

VS Code Copilot usa el campo raíz servers, opencode usa mcp y Zed usa context_servers. Hermes Agent utiliza mcp_servers en ~/.hermes/config.yaml; OpenClaw utiliza mcp.servers en la configuración de Gateway. Reinicie el cliente y compruebe que aparece sa2_help.

Credenciales

No guarde un clientSecret real en Git ni en la documentación. Rote inmediatamente cualquier credencial expuesta.

Variables principales

Variable	Predeterminado	Uso
SA2_LOGIN_URL	ninguno	URL de acceso obligatoria; de ella se deduce el origen del navegador remoto
SA2_AUTO_LOGIN_BEFORE_NAVIGATE	true	Iniciar sesión antes de abrir un destino
SA2_HEADLESS	false	Ejecutar Playwright sin interfaz
SA2_BROWSER	chromium	chromium, firefox o webkit
SA2_IGNORE_HTTPS_ERRORS	true	Ignora errores de certificado HTTPS; use false para exigir certificados válidos
SA2_RBI_FRAME_CONTENT_WAIT_MS	15000	Espera del contenido del iframe
SA2_NAVIGATION_TIMEOUT_MS	45000	Tiempo límite de navegación
SA2_ACTION_TIMEOUT_MS	15000	Tiempo límite de acciones
SA2_LOG_STDERR	true	Envía registros a stderr y reserva stdout para MCP
SA2_LOG_FILE	ninguno	Archivo de registro opcional

No configure las variables antiguas SA2_REMOTE_BROWSER_PREFIX ni SA2_REMOTE_BROWSER_BASE_URL.

Flujo recomendado

sa2_help
  -> sa2_list_available_targets    # solo para SaaS, workspace o sitio interno
  -> sa2_open_target
  -> browser_snapshot / browser_extract_text
  -> browser_click / browser_type / browser_press / browser_wait

URL pública:

{ "type": "cloud", "url": "https://example.com" }

Destino guardado:

{ "targetId": "workspace:123" }

Después de abrir la página, use preferentemente browser_snapshot y pase sus referencias ref=eN a las herramientas de interacción. id=tN y context=[tN] son referencias de texto del snapshot, no selectores CSS ni refs accionables.

Referencia completa de herramientas

Se describen todas las herramientas registradas por el servidor actual. Los parámetros pertenecen al objeto MCP arguments.

Herramienta	Uso, parámetros principales y resultado
sa2_help	Sin parámetros. Devuelve el flujo recomendado, ejemplos y herramientas compatibles.
sa2_list_available_targets	Lista proxies, SaaS, cuentas workspace y sitios internos con targetId estables.
sa2_open_target	Navegación preferida: type=cloud + url, o targetId/tipo + id/name; acepta surf y waitUntil.
browser_open_login	Abre SA2_LOGIN_URL, con waitUntil opcional, para diagnosticar el acceso.
browser_navigate	Navegación URL compatible: requiere url; surf y waitUntil son opcionales.
browser_navigate_back	Retrocede mediante la barra externa. Tome otro snapshot.
browser_navigate_forward	Avanza mediante la barra externa.
browser_reload	Recarga mediante la barra externa e invalida refs anteriores.
browser_list_proxies	Devuelve configuración free-browse, proxies y opciones con direct.
browser_list_saas_sites	Devuelve categorías SaaS y una lista sites plana.
browser_enter_saas_site	Abre un SaaS por id o name, con waitUntil opcional.
browser_list_workspaces	Devuelve datos workspace y destinos a nivel de cuenta.
browser_enter_workspace	Abre una cuenta por accountId, o siteId + username.
browser_list_inner_sites	Devuelve los sitios internos accesibles.
browser_enter_inner_site	Abre un sitio interno por id o name.
browser_snapshot	filter CSS real opcional. Devuelve snapshot semántico; use ref=eN, nunca id=tN, para actuar.
browser_extract_text	selector CSS real opcional. Devuelve texto visible del árbol de iframes.
browser_click	Hace clic por ref, selector, role/name, text o coordenadas x/y.
browser_type	Requiere text; destino por ref/selector/role, con append y pressEnter.
browser_press	Requiere key, como Enter, Escape o Control+A.
browser_press_key	Alias compatible de browser_press, mismos parámetros.
browser_wait	Espera selector, text, urlIncludes o ms (1000 predeterminado).
browser_scroll	Desplaza raíz/elemento con by, to o intoView; sin argumentos baja 600 px.
browser_hover	Pasa el puntero por un elemento usando ref, selector, role/name o texto.
browser_drag	Arrastra de startRef/startSelector a endRef/endSelector.
browser_fill_form	Rellena en orden un array fields con locator y value obligatorio.
browser_select_option	Ubica select por ref/selector y selecciona por values, value, label o index.
browser_check	Marca checkbox/radio por ref, selector, role/name o texto.
browser_uncheck	Desmarca checkbox; no admite radio.
browser_file_upload	Sube path/paths legibles por el servidor a un file input localizado.
browser_paste	Pega text, html, rtf y/o archivos en un destino o elemento enfocado.
browser_handle_dialog	Acepta/rechaza alert, confirm o prompt; accept es true por defecto, promptText y timeoutMs opcionales.
browser_resize	Requiere width y height positivos; cambia desktop o dimensiones del modo dispositivo activo.
browser_list_devices	Sin parámetros ni apertura de página. Lista Desktop y dispositivos Playwright con viewport, pantalla, DPR, touch/mobile y navegador.
browser_toggle_device	Cambia emulación sin recrear contexto. Acepta enabled, device, dimensiones, DPR, touch, UA, orientación y reload; devuelve state, observed, targetObserved, warnings.
browser_screenshot	Devuelve PNG; fullPage predeterminado false.
browser_take_screenshot	Alias de captura; fullPage predeterminado true.
browser_evaluate	Ejecuta expression y arg opcional en el iframe; devuelve JSON.
browser_run_code	Ejecuta code asíncrono con page, rootFrame y helpers. Solo código fiable.
browser_close	Cierra browser/context y borra refs, acceso, diálogos, CDP y estado del dispositivo.

Cambio de dispositivo

Llame primero a browser_list_devices y luego, por ejemplo, a browser_toggle_device con { "device": "Pixel 7", "orientation": "portrait" }. Conserva cookies y sesión. Use reload: true para aplicar el nuevo UA a solicitudes posteriores y { "device": "Desktop" } para restaurar el viewport anterior.

Chromium aplica viewport, pantalla, DPR, touch, orientación y UA mediante CDP. Firefox/WebKit solo cambian dinámicamente el viewport y explican la limitación en warnings. observed mide la cubierta externa y targetObserved el iframe objetivo. Tome un snapshot nuevo tras cada cambio.

Seguridad y solución de problemas

Obtenga confirmación explícita antes de publicar, enviar, eliminar, comprar, autorizar, transferir dinero o enviar mensajes.

• No aparecen herramientas: verifique la compilación y las rutas absolutas de node y dist/server.js; reinicie el cliente.
• Falla el acceso: verifique SA2_LOGIN_URL, las credenciales y el estado de la cuenta.
• Solo aparece la barra: llame a browser_wait o aumente la espera del iframe.
• No se encuentra un elemento: tome un snapshot nuevo y use el último ref=eN.