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:
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:
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:
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.
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_ORIGINSPLAYWRIGHT_MCP_BLOCKED_ORIGINSPLAYWRIGHT_MCP_ALLOW_UNRESTRICTED_FILE_ACCESSPLAYWRIGHT_MCP_CAPSPLAYWRIGHT_MCP_CONSOLE_LEVELPLAYWRIGHT_MCP_FILE_PATHSPLAYWRIGHT_MCP_IDLE_TIMEOUTPLAYWRIGHT_MCP_IMAGE_RESPONSESPLAYWRIGHT_MCP_PROFILE_DIR_NAMEPLAYWRIGHT_MCP_SNAPSHOT_MODEPLAYWRIGHT_MCP_STORAGE_STATEPLAYWRIGHT_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 /healthzdevuelve metadatos sobre el estado del proceso:status,version,transportyuptimeMs.GET /readyzdevuelve metadatos de disponibilidad y capacidad de sesión:sessions.active,sessions.pending,sessions.maxysessions.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.