Saltar a contenido

Configuración

Utiliza las variables PLAYWRIGHT_MCP_* de upstream para el comportamiento del MCP de Playwright. Utilice CLOAK_PLAYWRIGHT_MCP_* únicamente para el comportamiento del puente específico de Cloak.

Las antiguas variables CLOAKBROWSER_MCP_* ya no son compatibles. La Referencia de la CLI generada es la lista oficial de los indicadores de la CLI del puente y sus variables de entorno correspondientes.

Opciones de puente

Variable Valor predeterminado Descripción
CLOAK_PLAYWRIGHT_MCP_TRANSPORT stdio Transporte del puente: stdio o streamable-http.
CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL http Protocolo del servicio de escucha Streamable HTTP: http o https.
CLOAK_PLAYWRIGHT_MCP_HTTP_HOST 127.0.0.1 Dirección de enlace del servicio de escucha Streamable HTTP.
CLOAK_PLAYWRIGHT_MCP_HTTP_PORT 3000 Puerto de enlace del servicio de escucha Streamable HTTP. Use 0 para un puerto efímero en las pruebas.
CLOAK_PLAYWRIGHT_MCP_HTTP_ENDPOINT /mcp Ruta del punto de conexión Streamable HTTP. /healthz y /readyz están reservados para comprobaciones de estado.
CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN unset Token Bearer opcional que, cuando se configura, se exige en las solicitudes Streamable HTTP.
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_BACKEND memory Almacenamiento de metadatos de sesión. En esta versión solo está implementado memory.
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_IDLE_TTL_MS 3600000 Tiempo de vida de las sesiones Streamable HTTP inactivas. Las sesiones caducadas liberan los recursos de su puente y terminan el proceso hijo upstream.
CLOAK_PLAYWRIGHT_MCP_HTTP_SESSION_MAX 32 Número máximo de sesiones Streamable HTTP activas en un proceso.
CLOAK_PLAYWRIGHT_MCP_HTTPS_CERT unset Ruta al certificado TLS en formato PEM para Streamable HTTP mediante HTTPS.
CLOAK_PLAYWRIGHT_MCP_HTTPS_KEY unset Ruta a la clave privada TLS en formato PEM para Streamable HTTP mediante HTTPS.
CLOAK_PLAYWRIGHT_MCP_HTTPS_PFX unset Ruta al archivo TLS PFX/PKCS12 para Streamable HTTP mediante HTTPS.
CLOAK_PLAYWRIGHT_MCP_HTTPS_PASSPHRASE unset Frase de contraseña para una clave HTTPS cifrada o un archivo PFX.
CLOAK_PLAYWRIGHT_MCP_LOG_LEVEL info Nivel de los registros operativos de Streamable HTTP: trace, debug, info, warn, error, fatal o silent.
PLAYWRIGHT_MCP_PROXY_SERVER unset Servidor proxy de Playwright MCP upstream. Se utiliza como origen de GeoIP cuando la coincidencia está habilitada.
PLAYWRIGHT_MCP_PROXY_BYPASS unset Lista de excepciones del proxy upstream para los hosts que no deben usar PLAYWRIGHT_MCP_PROXY_SERVER.
CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH false Determina la ubicación GeoIP de PLAYWRIGHT_MCP_PROXY_SERVER y ajusta los parámetros de zona horaria y configuración regional de la huella de CloakBrowser a la ubicación de ese proxy.
CLOAK_PLAYWRIGHT_MCP_HUMANIZE false Habilita un comportamiento similar al humano para el ratón, el teclado y el desplazamiento en CloakBrowser.
CLOAK_PLAYWRIGHT_MCP_HUMAN_PRESET default Preajuste de comportamiento humano de CloakBrowser: default o careful. Solo se utiliza cuando la humanización está habilitada.
CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL stable Canal de lanzamiento del binario de CloakBrowser: stable o preview, solo para Pro.
CLOAKBROWSER_BINARY_PATH unset Ruta a un ejecutable personalizado de CloakBrowser. La opción de CLI --binary-path tiene prioridad.
CLOAKBROWSER_VERSION unset Versión fijada que se pasa al resolvedor de caché de CloakBrowser cuando no se selecciona un ejecutable personalizado. Una clave válida del plan gratuito ignora la versión fijada; CloakBrowser puede reutilizar un binario en caché.
PLAYWRIGHT_MCP_BROWSER_ENGINE cloak cloak usa el ejecutable de CloakBrowser. playwright omite la sustitución del ejecutable específica de Cloak.
PLAYWRIGHT_MCP_HEADLESS true Ejecuta Chromium sin interfaz gráfica.
PLAYWRIGHT_MCP_OUTPUT_DIR .playwright-mcp Directorio de artefactos para npm. Docker establece /data.
PLAYWRIGHT_MCP_CODEGEN typescript Destino de generación de código: typescript, python, java, csharp o none. El puente lo valida y escribe codegen en su configuración generada de Playwright MCP.
PLAYWRIGHT_MCP_SNAPSHOT_BOXES false true o false; incluye el rectángulo delimitador de cada elemento como [box=x,y,width,height] en las instantáneas. El puente lo valida y escribe snapshot.boxes en su configuración generada de Playwright MCP.
PLAYWRIGHT_MCP_TIMEOUT_SETTLE 500 Espera ascendente en milisegundos después de una acción para que se estabilice el trabajo activado. Se reenvía directamente a Playwright MCP.
PLAYWRIGHT_MCP_TIMEOUT_ACTION 5000 Tiempo de espera predeterminado para las acciones, en milisegundos.
PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION 60000 Tiempo de espera predeterminado para la navegación, en milisegundos.
PLAYWRIGHT_MCP_VIEWPORT_SIZE upstream default Área de visualización del navegador en formato WIDTHxHEIGHT.
PLAYWRIGHT_MCP_USER_DATA_DIR unset Directorio de perfil persistente de Chromium. El puente lo resuelve como una ruta absoluta, lo crea si falta, comprueba que se pueda escribir y lo escribe en el browser.userDataDir generado.
CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS unset Objeto JSON con opciones de contexto validadas. Los campos admitidos se enumeran más abajo.
CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS unset Matriz JSON o lista separada por comas de directorios de extensiones de Chrome existentes. Requiere PLAYWRIGHT_MCP_USER_DATA_DIR. Usa matrices JSON para rutas de Windows o rutas que contengan comas.
CLOAK_PLAYWRIGHT_MCP_CONSOLE_FALLBACK true Habilita el parche de compatibilidad de los mensajes de consola.
CLOAK_PLAYWRIGHT_MCP_STEALTH_ARGS true Añade los argumentos de inicio predeterminados de CloakBrowser para el modo sigiloso.
CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS unset Argumentos adicionales de Chromium como lista separada por comas o matriz JSON.
CLOAK_PLAYWRIGHT_MCP_NO_SANDBOX true Añade --no-sandbox y desactiva la zona aislada de Chromium.

CDP gestionado

El acceso administrado al Protocolo de Chrome DevTools (CDP) es una opción explícita de aceptación. Expone el misma generación de navegador Chromium controlada por MCP a través de una capacidad portadora descubrimiento URL. Configurar solo un grupo de puertos no habilita CDP.

Opción CLI Variable de entorno predeterminada Propósito
--cdp-enabled, --no-cdp-enabled CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED false Establezca el valor de stdio y la sesión predeterminada Streamable HTTP.
--cdp-port-range <port\|start-end> CLOAK_PLAYWRIGHT_MCP_CDP_PORT_RANGE desajustar Configure el grupo de puertos del proxy externo local del proceso. Una sesión habilitada ocupa un puerto.
--cdp-host <host> CLOAK_PLAYWRIGHT_MCP_CDP_HOST 127.0.0.1 Vincule el proxy gestionado CDP.
--cdp-allow-remote, --no-cdp-allow-remote CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE false Permitir o denegar una vinculación que no sea de bucle invertido.
--cdp-advertised-host <host> CLOAK_PLAYWRIGHT_MCP_CDP_ADVERTISED_HOST desactivar Coloca un host concreto accesible externamente en las URLs de descubrimiento. Requerido para enlaces comodín.
--cdp-advertised-scheme <http\|https> CLOAK_PLAYWRIGHT_MCP_CDP_ADVERTISED_SCHEME http Publicar las URLs http/ws o https/wss. Esto no habilita TLS.

Cada valor CLI anula únicamente su variable de entorno correspondiente. En particular, --no-cdp-enabled reemplaza a CLOAK_PLAYWRIGHT_MCP_CDP_ENABLED=true, y --no-cdp-allow-remote anula CLOAK_PLAYWRIGHT_MCP_CDP_ALLOW_REMOTE=true. Una sesión habilitada sin un grupo de puertos es rechazada antes de que su hijo ascendente comience. Un valor falso eficaz no crea ningún oyente, arrendamiento de puerto ni capacidad.

Para stdio, el valor del proceso se aplica directamente:

cloakbrowser-mcp \
  --cdp-enabled \
  --cdp-port-range 9222

Para Streamable HTTP, el booleano plano cdpEnabled en el autenticado Los metadatos initialize anulan el valor predeterminado del proceso para esa sesión. Omitir el el campo hereda el valor del proceso. Estos ejemplos optan explícitamente por una sesión y otro fuera:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": true
      }
    }
  }
}
{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "cdpEnabled": false
      }
    }
  }
}

Una sesión CDP habilitada con HTTP posee un arrendamiento de puerto externo. Las sesiones deshabilitadas no lo hacen consume la piscina. La asignación es local al proceso, selecciona el candidato no arrendado más bajo, y falla esa sesión inmediatamente si el puerto externo seleccionado ya está ocupado. Cierre sesiones para liberar puertos o configure un rango más grande cuando el grupo esté agotado.

Recupere el URL actual de cloakbrowser_bridge_info, luego pase su structuredContent.cdp.discoveryUrl a un cliente CDP como el de Playwright chromium.connectOverCDP(). Trata ese URL como una credencial: incluye un aleatorio capacidad por generación y se vuelve obsoleta después del reemplazo del navegador. CDP gestionado es no es un endpoint del servidor Playwright. chromium.connect() y el Open WebUI actual El flujo PLAYWRIGHT_WS_URL no es compatible.

--cdp-advertised-scheme https publica https descubrimiento y wss WebSocket URLs solo. El puente no proporciona TLS para CDP gestionado: su oyente externo y Chromium mantener la parte en texto claro HTTP/WebSocket. Un terminador TLS propiedad del operador debe escuchar en el mismo puerto arrendado anunciado, preservar los anuncios Host y Origin autoridad, y reenviar uno a uno a ese oyente de texto plano de la sesión.

La habilitación de CDP comienza Chromium durante la inicialización de MCP, por lo que la propiedad y externa se puede verificar la preparación. Configure el tiempo de espera de inicialización del cliente MCP a al menos 60 segundos. Cuando se habilita CDP gestionado, suministrado por el usuario CLOAK_PLAYWRIGHT_MCP_EXTRA_ARGS no debe contener --remote-debugging-port, --remote-debugging-address, o --remote-debugging-pipe (incluyendo las formas =). El propio Playwright mantiene interno --remote-debugging-pipe activado junto con el punto final TCP de bucle invertido gestionado por el puente.

Ver Herramientas, Docker, Seguridad, y Arquitectura para el estado de descubrimiento, despliegue, límites y comportamiento de reinicio.

Licencia de CloakBrowser e inicio de sesión con GitHub

La licencia se configura con la CLI original de CloakBrowser; cloakbrowser-mcp no añade comandos de inicio o cierre de sesión:

npx -y cloakbrowser@latest login
npx -y cloakbrowser@latest info
npx -y cloakbrowser@latest logout

login acepta una clave de pago o inicia la autenticación con GitHub para obtener una clave del nivel gratuito. La clave validada se guarda en ~/.cloakbrowser/license.key; logout elimina ese archivo. info muestra el nivel de licencia activo y, para las licencias Pro, el número de sesiones activas.

También puedes definir CLOAKBROWSER_LICENSE_KEY en el entorno del servidor MCP. El puente reenvía esa variable al proceso secundario ascendente/del navegador sin registrarla. Si CLOAKBROWSER_CACHE_DIR apunta a una caché personalizada que contiene license.key, CloakBrowser resuelve la clave y el puente reenvía únicamente esa clave resuelta desde el entorno generado del navegador. No se copian otras entradas de entorno generadas.

Si CloakBrowser rechaza la clave de licencia proporcionada o no puede validarla mediante el servidor de licencias ni la validación almacenada en caché, el inicio falla con el error explícito de CloakBrowser. El puente conserva ese error: no lo oculta ni cambia silenciosamente a otro navegador o nivel de licencia.

CloakBrowser puede reutilizar la validación en caché cuando el servidor de licencias no está disponible. Esto no garantiza un inicio sin conexión: la descarga del binario o el inicio del navegador aún pueden fallar.

Canal de lanzamiento de CloakBrowser

CLOAK_PLAYWRIGHT_MCP_RELEASE_CHANNEL selecciona el canal de publicación del binario de CloakBrowser. El valor predeterminado es stable. preview solicita una compilación preliminar del navegador Pro y solo está disponible con una licencia Pro. Una versión fijada explícitamente mediante CLOAKBROWSER_VERSION tiene prioridad en las descargas sin clave o con una clave de pago. Una clave válida del plan gratuito ignora la versión fijada y puede reutilizar un binario en caché. Si Preview no está disponible para la plataforma, CloakBrowser vuelve a Stable.

El canal de lanzamiento se selecciona cuando se inicia el proceso del puente. Se aplica a todas las sesiones de Streamable HTTP y no se puede establecer ni reemplazar en los metadatos de initialize. Reinicie el puente para cambiarlo.

Binario personalizado de CloakBrowser

--binary-path <path> selecciona un ejecutable personalizado de CloakBrowser para el proceso actual del puente. CLOAKBROWSER_BINARY_PATH ofrece el mismo ajuste para despliegues basados en variables de entorno; la opción de CLI tiene prioridad. El puente resuelve la ruta, exige un archivo regular legible y la escribe en browser.launchOptions.executablePath de la configuración generada de Playwright MCP.

npx -y cloakbrowser-mcp@latest --binary-path /opt/cloakbrowser/chrome

El puente no descarga ni actualiza un ejecutable personalizado. Si no se selecciona una ruta, CLOAKBROWSER_VERSION puede fijar la versión del binario administrado por CloakBrowser.

En Streamable HTTP, el binario seleccionado pertenece al proceso del puente y se usa en todas las sesiones MCP que crea. Los metadatos de initialize no pueden seleccionar ni reemplazar una ruta ejecutable; ejecute procesos separados para usar binarios distintos.

Si la compilación elegida proporciona document.modelContext o navigator.modelContext con el método getTools(), upstream Playwright MCP puede añadir herramientas webmcp_<page-tool> después de una captura de la página. Envía tools/list_changed; el puente reenvía la notificación y la lista actualizada. La página define el nombre y el esquema de cada herramienta dinámica.

Coincidencia de proxy GeoIP

Configura CLOAK_PLAYWRIGHT_MCP_GEOIP_PROXY_MATCH=true junto con PLAYWRIGHT_MCP_PROXY_SERVER para obtener los indicadores de zona horaria, idioma y configuración regional de CloakBrowser a partir de la ubicación de salida del proxy. CloakBrowser selecciona la autenticación nativa integrada en la URL para los binarios compatibles y conserva el objeto proxy de Playwright como alternativa para los binarios antiguos.

Consulta Coincidencia de proxies GeoIP para ver ejemplos de configuración, metadatos de proxy HTTP transmisibles en tiempo de ejecución, casos de uso, reglas de prioridad y limitaciones.

Para un procedimiento breve, consulte QA regional mediante proxy.

Comportamiento de entrada humanizado

Establece CLOAK_PLAYWRIGHT_MCP_HUMANIZE=true para activar la capa de CloakBrowser que simula el comportamiento humano del ratón, el teclado y el desplazamiento para las interacciones con la página. El puente aplica esto a través del gancho de inicialización de la página de Playwright MCP, de modo que los esquemas de las herramientas de navegador de origen permanecen inalterados.

Consulte Comportamiento de entrada humanizado para ver ejemplos de configuración, metadatos HTTP de Streamable en tiempo de ejecución, casos de uso y limitaciones.

Extensiones de Chrome

Las extensiones de Chrome se cargan cuando se inicia el navegador, así que configúralas antes de iniciar el puente o antes de crear una sesión Streamable HTTP. Las extensiones deben ser directorios descomprimidos y requieren un perfil persistente:

PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/default" \
  CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS='["/absolute/path/to/my-extension"]' \
  npx -y cloakbrowser-mcp@latest

Para Streamable HTTP, pasa los directorios del perfil y de la extensión en los metadatos de initialize:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "userDataDir": "/absolute/path/to/profile",
        "extensionPaths": ["/absolute/path/to/my-extension"]
      }
    }
  }
}

Reinicia el puente o crea una nueva sesión HTTP después de cambiar archivos o rutas de extensiones. Usa una matriz JSON para CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS cuando las rutas contengan comas, al pasar varias extensiones o al usar rutas de Windows con letras de unidad.

Para una configuración breve con ejemplos listos para copiar, consulte Cargar una extensión de Chrome.

Modo de conexión Playwright Extension

El modo de conexión mediante Playwright Extension es distinto de cargar una extensión descomprimida con CLOAK_PLAYWRIGHT_MCP_EXTENSION_PATHS. Se conecta mediante la extensión oficial Playwright Extension ya instalada en un perfil de Chrome o Edge; el puente no instala esa extensión.

Para stdio, configure el entorno del proceso:

PLAYWRIGHT_MCP_EXTENSION=true \
  PLAYWRIGHT_MCP_EXTENSION_TOKEN='<secret-from-the-extension>' \
  PLAYWRIGHT_MCP_USER_DATA_DIR="$PWD/.profiles/playwright-extension" \
  PLAYWRIGHT_MCP_PROFILE_DIR_NAME='Profile 1' \
  npx -y cloakbrowser-mcp@latest

Para Streamable HTTP, los metadatos de initialize extensionMode y profileDirName anulan sus valores a nivel de proceso. userDataDir también es específico de cada sesión. El token sigue aceptándose únicamente desde el entorno del proceso:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "extensionMode": true,
        "profileDirName": "Profile 1",
        "userDataDir": "/absolute/path/to/profile"
      }
    }
  }
}

El modo de extensión requiere un token no vacío y un perfil persistente. Las sesiones HTTP de extensión simultáneas deben usar valores de userDataDir diferentes. Antes de iniciar el proceso hijo upstream, el puente rechaza los puntos de conexión CDP administrados o externos, los puntos de conexión de navegadores remotos, la configuración de inicio sin interfaz gráfica o aislado, las opciones de proxy y GeoIP, la humanización, la modificación del contexto, las extensionPaths descomprimidas y las opciones de inicio de CloakBrowser proporcionadas explícitamente. La verificación de un escenario completo satisfactorio es manual, porque la extensión oficial Playwright Extension ya debe estar instalada en el perfil de navegador seleccionado.

Metadatos de tiempo de ejecución HTTP transmitibles

Los clientes HTTP de transmisión pueden seleccionar determinadas opciones de tiempo de ejecución para cada sesión de MCP añadiendo metadatos específicos del puente a la solicitud initialize:

{
  "params": {
    "_meta": {
      "io.github.swimmwatch/cloakbrowser-mcp": {
        "proxyServer": "http://user:pass@proxy.example:8080",
        "proxyBypass": ".internal,localhost",
        "geoipProxyMatch": true,
        "headless": false,
        "extensionMode": false,
        "profileDirName": "Profile 1",
        "humanize": true,
        "humanPreset": "careful",
        "userDataDir": "/absolute/path/to/profile",
        "contextOptions": {
          "viewport": { "width": 1280, "height": 720 },
          "locale": "en-US",
          "timezoneId": "America/New_York"
        },
        "extensionPaths": ["/absolute/path/to/extension"]
      }
    }
  }
}

proxyServer anula PLAYWRIGHT_MCP_PROXY_SERVER para esa sesión HTTP. proxyBypass sustituye a PLAYWRIGHT_MCP_PROXY_BYPASS únicamente cuando proxyServer está presente. geoipProxyMatch puede activar o desactivar la coincidencia de GeoIP para esa sesión sin reiniciar el servidor MCP. Las sesiones existentes conservan su proxy de inicio; crea una nueva sesión HTTP para cambiar de ubicación.

humanize puede activar o desactivar el comportamiento de entrada humanizado para esa sesión sin afectar a las demás sesiones. humanPreset puede seleccionar default o careful para esa sesión, pero no activa por sí mismo el comportamiento humanizado. Las sesiones existentes conservan el comportamiento capturado durante initialize.

headless puede habilitar o deshabilitar el modo del navegador sin interfaz gráfica para esa sesión. En la imagen Docker, establecer headless en false inicia bajo demanda una pantalla virtual privada del contenedor. Fuera de la imagen, una sesión con interfaz gráfica sigue necesitando un entorno de pantalla utilizable.

extensionMode y profileDirName anulan PLAYWRIGHT_MCP_EXTENSION y PLAYWRIGHT_MCP_PROFILE_DIR_NAME para esa sesión. PLAYWRIGHT_MCP_EXTENSION_TOKEN nunca se acepta en los metadatos.

userDataDir habilita un perfil persistente de Chromium para esa sesión y sobrescribe PLAYWRIGHT_MCP_USER_DATA_DIR. El puente resuelve el directorio como una ruta absoluta nativa de la plataforma, lo crea si falta, comprueba que se pueda escribir y lo escribe en el browser.userDataDir generado. Un perfil persistente deshabilita el perfil aislado predeterminado de Streamable HTTP para esa sesión. El puente rechaza el uso activo duplicado de directorios de perfil tanto dentro de un proceso como entre procesos del mismo espacio de identificadores de proceso. Consulta Perfil de inicio de sesión persistente para conocer la recuperación del bloqueo y sus límites.

contextOptions se validan y se fusionan superficialmente sobre CLOAK_PLAYWRIGHT_MCP_CONTEXT_OPTIONS; los objetos anidados se sustituyen por completo. Los campos admitidos son userAgent, viewport, locale, timezoneId, colorScheme, permissions, geolocation, extraHTTPHeaders, httpCredentials, ignoreHTTPSErrors, offline, deviceScaleFactor, isMobile y hasTouch. En esta versión no se admite el paso arbitrario de BrowserContextOptions.

extensionPaths deben apuntar a directorios existentes y requieren un userDataDir persistente. El puente resuelve las rutas de extensiones como rutas absolutas nativas de la plataforma, las pasa a CloakBrowser y escribe los argumentos de Chromium generados --load-extension y --disable-extensions-except en la configuración generada de Playwright MCP.

Las credenciales de proxy HTTP autenticadas se pueden incrustar en proxyServer, por ejemplo http://user:pass@proxy.example:8080. Codifica en formato «percent» los caracteres de las credenciales que tengan significado en una URL, como @, :, /, ?, #, y %.

En los binarios de CloakBrowser compatibles, los proxies HTTP autenticados utilizan la autenticación nativa integrada en la URL y el puente elimina el objeto proxy duplicado de Playwright. Los binarios antiguos conservan el objeto proxy de Playwright como alternativa de compatibilidad.

Para los patrones de control de calidad en múltiples ubicaciones, consulta Coincidencia de proxy GeoIP. Para los patrones de realismo en la interacción, véase Comportamiento de entrada humanizado.

Para reutilizar el inicio de sesión y configurar extensiones, consulte Perfil de inicio de sesión persistente y Cargar una extensión de Chrome.

Opciones de Playwright MCP upstream

El puente reenvía la configuración de PLAYWRIGHT_MCP_* al MCP de Playwright situado en la parte superior de la cadena. Esto incluye opciones de la parte superior de la cadena como:

  • PLAYWRIGHT_MCP_ALLOWED_ORIGINS
  • PLAYWRIGHT_MCP_BLOCKED_ORIGINS
  • PLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESS
  • PLAYWRIGHT_MCP_CAPS
  • PLAYWRIGHT_MCP_CONSOLE_LEVEL
  • PLAYWRIGHT_MCP_FILE_PATHS
  • PLAYWRIGHT_MCP_IDLE_TIMEOUT
  • PLAYWRIGHT_MCP_IMAGE_RESPONSES
  • PLAYWRIGHT_MCP_PROFILE_DIR_NAME
  • PLAYWRIGHT_MCP_SNAPSHOT_MODE
  • PLAYWRIGHT_MCP_STORAGE_STATE
  • PLAYWRIGHT_MCP_WEBMCP

Consulta la documentación de Playwright MCP del proyecto original para conocer todas las opciones disponibles.

PLAYWRIGHT_MCP_CAPS=devtools se hereda en el proceso hijo upstream y habilita las herramientas controladas por esa capacidad sin una opción --caps propia del puente.

Registro

El modo HTTP «Streamable» escribe registros de inicio y de solicitudes legibles para el usuario en stdout. El modo «stdio» no genera registros operativos rutinarios, por lo que la salida stdout de MCP JSON-RPC se mantiene libre de datos del protocolo. Los errores graves de inicio de la CLI siguen registrándose en stderr.

HTTPS

Streamable HTTP utiliza HTTP local de forma predeterminada. Selecciona TLS directo con --http-protocol https o CLOAK_PLAYWRIGHT_MCP_HTTP_PROTOCOL=https y, a continuación, facilite un par de certificado y clave o un archivo PFX:

cloakbrowser-mcp --transport streamable-http \
  --http-protocol https \
  --https-cert ./cert.pem \
  --https-key ./key.pem

Para una exposición externa o sin bucle cerrado, utiliza HTTPS junto con --http-auth-token, o bien termina el TLS en un proxy inverso de confianza que también aplique controles de autenticación y de acceso a la red.

Sesiones HTTP transmisibles

Cada sesión de Streamable HTTP MCP tiene su propio entorno de ejecución del puente y proceso secundario de upstream Playwright MCP. Las sesiones HTTP usan perfiles de navegador aislados por defecto, salvo que se configure un perfil persistente. Un perfil persistente explícito se bloquea; las sesiones simultáneas necesitan directorios de perfil diferentes. El backend integrado memory solo guarda metadatos: ID de sesión, marcas de tiempo, caducidad y estado. El estado del navegador permanece en el proceso secundario upstream activo y los artefactos se controlan mediante PLAYWRIGHT_MCP_OUTPUT_DIR.

Para el escalado horizontal, ejecuta varias réplicas del servidor detrás de un equilibrador de carga con sesiones persistentes identificadas mediante el encabezado mcp-session-id. Los futuros backends de Redis, Postgres o SQLite podrán coordinar metadatos y bloqueos, pero no podrán restaurar una sesión de navegador activa una vez que se haya cerrado el proceso al que pertenece.

Sondas HTTP con transmisión continua

Cuando el puente funciona con --transport streamable-http, expone puntos finales de sonda fijos en el mismo host y puerto que el punto final del MCP:

  • GET /healthz devuelve metadatos sobre el estado del proceso: status, version, transport y uptimeMs.
  • GET /readyz devuelve metadatos de disponibilidad y capacidad de sesión: sessions.active, sessions.pending, sessions.max y sessions.available.

La disponibilidad devuelve HTTP 200 mientras haya capacidad de sesión disponible y HTTP 503 cuando active + pending >= max. Si se configura --http-auth-token o CLOAK_PLAYWRIGHT_MCP_HTTP_AUTH_TOKEN, ambas sondas requieren el mismo encabezado Authorization: Bearer ... que las solicitudes MCP. Sin un token de autenticación, las sondas permanecen abiertas en la dirección de enlace HTTP configurada.

Más rutas prácticas

Para elegir entre Playwright MCP upstream y este paquete, consulta la comparación. Para tareas rápidas, usa las recetas: perfil persistente, extensiones, reverse proxy, QA regional, Claude Desktop, Codex CLI y prueba smoke de CI.