Automatiza los navegadores con el servidor remoto MCP de Espacios de trabajo de dramaturgo

El servidor remoto MCP de Espacios de trabajo de dramaturgo ofrece a los agentes de IA un navegador remoto gestionado y un conjunto de herramientas de automatización de navegadores. Un agente puede abrir una sesión del navegador, navegar por páginas, encontrar e interactuar con elementos, inspeccionar la actividad del navegador, tomar capturas de pantalla y cerrar la sesión. No necesitas instalar Playwright ni un navegador en el entorno del agente.

El servidor utiliza Model Context Protocol sobre Streamable HTTP. Soporta autenticación Microsoft Entra ID y tokens de acceso al espacio de trabajo. Funciona con clientes MCP remotos, incluyendo Microsoft Foundry Agent Service y Visual Studio Code.

En este artículo aprenderá a:

• Crea el endpoint de MCP para un espacio de trabajo de Playwright.
• Autentica usando Microsoft Entra ID o un token de acceso al espacio de trabajo.
• Conecta el servidor a Microsoft Foundry Agent Service o Visual Studio Code.
• Ejecuta flujos completos de automatización agentica del navegador.
• Selecciona y utiliza de forma segura las herramientas de navegador disponibles.
• Gestiona la expiración de la sesión, los tiempos de espera y otros errores comunes.

Prerequisites

Antes de empezar, asegúrese de que tiene lo siguiente:

• Una cuenta de Azure con una suscripción activa.
• Un espacio de trabajo de Playwright que tiene acceso a la vista previa remota de MCP.
• El ID del área de trabajo y la región de Azure del área de trabajo.
• Una identidad con permiso para crear y usar sesiones de navegador en el espacio de trabajo.
• Para Microsoft Foundry, un proyecto de Foundry y permiso para crear conexiones de proyecto y configurar agentes.
• Para Visual Studio Code, una versión actual de Visual Studio Code con acceso a GitHub Copilot y soporte MCP activados.

Elección de un método de autenticación

Utiliza Microsoft Entra ID cuando tu cliente MCP soporte OAuth o identidad gestionada. El servidor MCP remoto utiliza este identificador de recurso y el alcance delegado:

Resource: https://mcp.playwright.microsoft.com
Scope: https://mcp.playwright.microsoft.com/Playwright.Mcp.Tools

El servidor publica metadatos de recursos protegidos OAuth. Los clientes que admiten el descubrimiento de OAuth, entre ellos Visual Studio Code, pueden detectar el servidor de autorización y el ámbito requerido a partir del punto de conexión MCP con ámbito de espacio de trabajo. La identidad que ha iniciado sesión debe tener acceso al espacio de trabajo de Playwright mediante el control de acceso basado en roles (RBAC) de Azure.

Crea un token de acceso al espacio de trabajo para compatibilidad

Omite esta sección cuando uses Microsoft Entra ID. Si la autenticación con token de acceso no está ya habilitada para el espacio de trabajo:

1. Inicie sesión en Azure Portal.
2. Abre tu espacio de trabajo de Dramaturgo.
3. En Configuración, selecciona Gestión de acceso.
4. Activar el token de acceso al servicio de dramaturgo.
5. Seleccione Generar token.
6. Introduce un nombre y una fecha de caducidad, y luego genera el token.
7. Copie el token inmediatamente. No puedes recuperar su valor más adelante.

Guarda el token en un almacén secreto gestionado o en la facilidad de credenciales segura proporcionada por tu cliente MCP. Revócalo y sustitúyelo si podría haber quedado expuesto. Para crear un token de acceso al espacio de trabajo, consulta Gestionar tokens de acceso al espacio de trabajo.

Crea el extremo remoto de MCP

El punto final está asignado a un solo espacio de trabajo y región:

https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp

Reemplazar:

• <region>con la región Azure del espacio de trabajo.
• <workspace-id> con el ID del espacio de trabajo mostrado en el portal de Azure.

Por ejemplo:

https://eastus.mcp.playwright.microsoft.com/playwrightworkspaces/00000000-0000-0000-0000-000000000000/mcp

El valor en la x-api-key cabecera de la solicitud debe ser un token de acceso creado para el mismo espacio de trabajo que <workspace-id>. Utiliza el endpoint para la región del workspace, no la región más cercana al cliente MCP.

Comprender el ciclo de vida de las sesiones del navegador

Un flujo de automatización de navegador tiene tres etapas:

1. Llame a create_browser_session. El resultado contiene una URL opaca browserSessionId y podría contener una URL de visualización en vivo.
2. Pase ese browserSessionId a todas las herramientas del navegador utilizadas en el flujo.
3. Llama close_browser_session para un paso de limpieza, incluso cuando el flujo falla.

El transporte HTTP MCP no conserva el estado del navegador. El browserSessionId identifica el navegador remoto en distintas llamadas a herramientas. Manténlo privado y úsalo solo con el espacio de trabajo y la identidad que lo creó.

El comportamiento actual de la vista previa incluye estas restricciones:

• Una sesión pertenece a su creador y no puede compartirse con otro principal.
• Las llamadas de una sesión se procesan en orden. No emitas acciones concurrentes contra la misma sesión.
• Una sesión inactiva se limpia tras 15 minutos. Se requiere una limpieza explícita.
• Una sesión cerrada o caducada no puede reabrirse.
• La pérdida de conexión pone fin a la sesión. Crea una nueva sesión para continuar.
• Un resultado podría contener un liveViewUrl. La disponibilidad de la vista en directo depende de la sesión.

Conectarse desde el servicio de agentes Microsoft Foundry

Utiliza Microsoft Entra Agent Identity para autenticar al agente con la identidad gestionada del proyecto Foundry. Concede a esa identidad acceso al espacio de trabajo de Playwright antes de conectar la herramienta MCP.

Creación de la conexión del proyecto

1. Abre tu proyecto en el portal de Microsoft Foundry.
2. Abre la experiencia de gestión del proyecto y luego selecciona Recursos conectados.
3. Crea una conexión para un servidor MCP remoto.
4. Introduce un nombre descriptivo de conexión, como playwright-mcp-connection.
5. Selecciona Microsoft Entra Agent Identity como método de autenticación.
6. Introduzca https://mcp.playwright.microsoft.com como audiencia.
7. Guarde la conexión.

La identidad gestionada del proyecto debe tener un rol que permita operaciones de sesión de navegador en el espacio de trabajo objetivo de Playwright. No uses un token de identidad de un proyecto como secreto compartido en otro proyecto.

Si Microsoft Entra Agent Identity no está disponible para el cliente o el entorno, crea una conexión de claves personalizadas con una clave nombrada x-api-key y un token de acceso al espacio de trabajo como valor.

Añadir la herramienta MCP remota

1. Crea o abre un agente en el portal de Foundry.

2. Añade un servidor MCP remoto o una herramienta MCP.

3. Use la configuración siguiente:

   Setting	Value
   Etiqueta del servidor	Una etiqueta única, como playwrightWorkspace
   Dirección URL del servidor	El punto final remoto MCP con alcance de espacio de trabajo
   Conexión de proyecto	La conexión de Microsoft Entra Agent Identity creada anteriormente
   Aprobación	Exigir la aprobación de cada llamada mientras evalúas la integración
   Herramientas permitidas	Empieza solo con las herramientas necesarias para el flujo

4. Guarde la configuración del agente.

5. En las instrucciones del agente, se requiere que el agente cree una sesión, reutilice su browserSessionId, y cierre la sesión cuando termine la tarea.

Una lista mínima de herramientas para un flujo de navegación orientado a lectura es:

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

Añade herramientas de interacción como browser_click o browser_type solo cuando el escenario las requiera. No lo habilites browser_evaluate ni browser_run_code por defecto.

Prueba el flujo de la fundición

Utiliza un prompt que indique el objetivo y el requisito de limpieza. Por ejemplo:

Create a browser session, open https://example.com, inspect the page snapshot,
report the main heading and destination URL, and close the browser session.
Always close the session, including when a browser step fails.

Cuando el agente solicita aprobación:

1. Verifica que la etiqueta del servidor sea la del servidor de Playwright configurado.
2. Revisa el nombre de la herramienta y todos los argumentos, especialmente URLs, selectores, texto, datos subidos y código.
3. Aprueba solo la operación esperada.
4. Verifica que la respuesta final se base en el resultado de la página.
5. Confirma que el flujo se llama close_browser_session.

Para los campos de conexión actuales de Foundry, gestión de aprobaciones, ejemplos de SDK y límites de clientes, consulte Conectar agentes a endpoints de servidor MCP.

Conexión desde Visual Studio Code

Visual Studio Code puede descubrir la configuración OAuth del servidor remoto e iniciar sesión contigo con Microsoft Entra ID. La configuración solo necesita el punto de conexión con ámbito del espacio de trabajo.

1. En Visual Studio Code, ejecuta MCP: Open User Configuration desde la Paleta de Comandos.
2. Añade la siguiente configuración y sustituye los marcadores de posición de los extremos.

{
  "servers": {
    "playwrightWorkspace": {
      "type": "http",
      "url": "https://<region>.mcp.playwright.microsoft.com/playwrightworkspaces/<workspace-id>/mcp"
    }
  }
}

3. Inicia el servidor desde el editor de configuración o ejecuta MCP: List Servers.
4. Cuando se lo pida, inicia sesión con la cuenta de Microsoft Entra que tiene acceso al espacio de trabajo de Playwright.
5. Aprueba el permiso solicitado Playwright.Mcp.Tools si tu inquilino requiere el consentimiento.
6. Revisa la URL y la configuración del servidor, y luego confirma que confías en él.
7. Abre el chat y selecciona Configurar herramientas. Activa solo las herramientas de dramaturgo necesarias para la tarea.
8. Ejecuta el prompt de ejemplo de la sección anterior sobre Foundry.
9. Revisa las confirmaciones de la herramienta y verifica que la sesión esté cerrada al final.

Utiliza una configuración de usuario cuando la conexión sea personal. Se puede compartir una configuración de espacio de trabajo que contenga solo el endpoint. Visual Studio Code almacena en caché las credenciales OAuth de forma segura y puede reutilizarlas al reconectarse.

Si la autenticación Microsoft Entra no está disponible en el entorno cliente, configura un x-api-key encabezado con una entrada protegida como se describe en las entradas de configuración MCP. Nunca pongas el valor del token de acceso del espacio de trabajo directamente en mcp.json.

Para ubicaciones de configuración, entradas secretas, confianza en servidores y diagnósticos, consulte Añadir y gestionar servidores MCP en Visual Studio Code y la referencia de configuración MCP.

Diseñar un flujo de automatización basada en agentes

Utiliza un bucle observar-actuar-verificar en lugar de pedir al agente que realice una secuencia larga sin comprobar el estado de la página.

1. Crear: Llame a create_browser_session y conserve su browserSessionId.
2. Navegar: Llama browser_navigate con una URL explícita y aprobada.
3. Observa lo siguiente: Usa browser_find para una búsqueda más precisa o browser_snapshot para obtener una visión más amplia de la accesibilidad.
4. Acción: Utiliza una referencia a una instantánea o un selector único mediante una herramienta de interacción.
5. Espera: Usa browser_wait_for para texto esperado, texto que desaparece o una espera limitada.
6. Verificar: Captura otra instantánea o inspecciona la actividad de la consola y la red.
7. Gestionar bifurcaciones: Gestiona un cuadro de diálogo, cambia de pestaña o carga archivos solo cuando el estado de la página lo requiera.
8. Captura pruebas: Llama browser_take_screenshot si un resultado visual es útil. No uses capturas de pantalla para seleccionar objetivos de acción.
9. Limpieza: Llame a close_browser_session en una ruta de limpieza de estilo finally.

Elige objetivos de acción estable

Preferir referencias devueltas por browser_snapshot o browser_find. Describen elementos de página accesibles y reducen la dependencia del marcado específico de la implementación. Usa un selector único cuando no haya una referencia de instantánea estable disponible.

Actualiza la instantánea tras la navegación o tras una acción de cambio de página. Un objetivo devuelto anteriormente puede volverse obsoleto cuando la página vuelve a renderizarse.

Gestionar los diálogos de forma segura

Una acción puede devolver un dialog-opened resultado después de haber cambiado el estado de la página. Este resultado no es un fallo normal de acción.

1. No repitas la acción original.
2. Llame a browser_handle_dialog con accept establecido en true o false.
3. En un cuadro de diálogo de solicitud, incluya promptText solo al aceptarlo.
4. Observa la página de nuevo antes de continuar.

Gestionar fallos ambiguos

Que se agote el tiempo de espera o que la llamada se interrumpa no demuestra que una acción no haya tenido efecto. Antes de volver a intentar una operación no idempotente como un clic, envío de formularios, subida o ejecución de código:

1. Llama a browser_snapshot, browser_find o a otra herramienta de observación si la sesión sigue disponible.
2. Determina si el cambio de estado esperado se produjo.
3. Inténtalo solo si repetir la acción es seguro.
4. Si la sesión expiró, crea una nueva sesión y reinicia desde un estado de aplicación conocido.

Referencia de herramientas

Todas las herramientas del navegador requieren browserSessionId. Los límites de cadenas y colecciones que se muestran aquí son los límites actuales de previsualización.

Herramientas de sesión

Herramientas de navegación y observación

Herramientas de interacción

Pestañas, archivos y herramientas de código

Después de cada flujo de trabajo de automatización, invoca a close_browser_session con el browserSessionId activo.

Forma del campo de formulario

Cada browser_fill_form campo tiene esta forma:

{
  "target": "<snapshot-reference-or-selector>",
  "value": "<string-or-boolean>",
  "name": "<optional-display-name>",
  "type": "<optional-field-type>"
}

El valor de la cadena de un campo puede contener como máximo 100 KiB de caracteres. name puede contener como máximo 1.024 caracteres, y type puede contener como máximo 128 caracteres.

Forma de carga del archivo

Cada browser_file_upload archivo utiliza esta forma:

{
  "name": "example.txt",
  "data": "SGVsbG8sIHdvcmxkIQ==",
  "mimeType": "text/plain"
}

mimeType es opcional y el valor predeterminado es application/octet-stream.

Límites de subida de archivos

• De 1 a 20 archivos por llamada a la herramienta.
• Tamaño máximo decodificado de 10 MiB para cada archivo.
• 50 MiB tamaño máximo combinado decodificado.
• Nombre máximo de archivo de 4.096 caracteres.
• Tipo MIME máximo de 1.024 caracteres.
• Se requieren datos válidos de base64.

Formas de herramientas JavaScript

Para browser_evaluate, pasa una expresión de función:

() => document.title

Cuando proporcionas target, la función recibe el elemento correspondiente:

element => element.textContent

Para browser_run_code, pase instrucciones que formen el cuerpo de una función asincrónica cuyo parámetro page sea una página de Playwright. Devuelve solo datos serializables en JSON y mantenlos dentro del límite de respuesta en línea.

Límites y comportamiento actual

Las respuestas se devuelven en línea. Esta vista previa no ofrece recursos MCP ni almacenamiento persistente de artefactos para instantáneas de gran tamaño, capturas de pantalla o descargas. Las redefiniciones del navegador, del sistema operativo, del área gráfica, de la configuración regional y del agente de usuario no se exponen como parámetros de creación de sesión.

Gestión de errores

Un error de herramienta incluye un código de error estable, un mensaje seguro para el cliente, un retryable valor e información de correlación. Utiliza el valor devuelto retryable como señal primaria, junto con los efectos secundarios de la operación.

Solución de problemas comunes

El cliente MCP muestra «No autorizado»

• Confirma que la autenticación por token de acceso está habilitada para el espacio de trabajo.
• Confirma que el token no está caducado ni revocado.
• Utiliza el valor sin procesar del token como el valor de x-api-key. No añadas un Bearer prefijo.
• Confirma que el token y el endpoint pertenecen al mismo espacio de trabajo.
• Si copiaste un secreto incorrectamente, crea un token nuevo porque no puedes recuperar valores existentes del portal.

El cliente de MCP muestra “Acceso prohibido”

• Confirma que el usuario asociado al token aún tiene permiso para crear sesiones de navegador.
• Utiliza la misma conexión o token de proyecto para todas las llamadas en una sesión de navegador.
• No pases browserSessionId entre usuarios, agentes que usan diferentes credenciales o espacios de trabajo.

No se descubren herramientas

• Verifica el endpoint completo, incluyendo /playwrightworkspaces/<workspace-id>/mcp.
• Verifica que la región del endpoint coincida con la región del espacio de trabajo.
• Confirma que el cliente utiliza un transporte MCP sobre HTTP y envía x-api-key en el descubrimiento y en las llamadas a herramientas.
• En Visual Studio Code, ejecuta MCP: List Servers, selecciona el servidor y luego selecciona Mostrar salida.
• Reinicia la conexión MCP o reinicia las herramientas almacenadas en caché después de cambiar el endpoint.

El agente no llama a una herramienta de navegador

• Dile explícitamente al agente que use el servidor MCP configurado de Playwright.
• Verifica que la herramienta requerida aparezca en la lista de herramientas habilitadas o permitidas del cliente.
• Incluya el ciclo de vida de crear, usar y cerrar en las instrucciones del agente.
• Utiliza una primera tarea enfocada con un objetivo de navegación y un resultado esperado.

Un objetivo ya no funciona

La página podría haber cambiado o haberse renderizado de nuevo. Vuelve a llamar a browser_snapshot o a browser_find y usa una referencia vigente. Evita los selectores vinculados a clases generadas o que cambien la estructura del documento.

Una herramienta con tiempo agotado

No asumas que la acción falló sin que se produjera un cambio de estado. Si la sesión está activa, inspecciona la página actual antes de volver a intentarlo. Si la sesión ha expirado, crea una nueva sesión y devuelve la solicitud a un estado conocido.

Una captura de pantalla es demasiado grande

Usa type: "jpeg", captura solo el viewport, o proporciona un objetivo para una captura de pantalla a nivel de elemento. Úsala browser_snapshot cuando el objetivo es identificar un elemento en lugar de preservar evidencia visual.

La sesión caducó durante un flujo

Crea una nueva sesión en el navegador. Las sesiones no se reconectan tras la pérdida de conexión del navegador, la pérdida del propietario del servicio, el cierre explícito o la limpieza por inactividad. Diseña el flujo para que pueda reiniciarse desde una URL y estado de aplicación conocidos.

Recomendaciones de seguridad

• Permite solo las herramientas requeridas por la tarea del agente.
• Requerir aprobación humana para las herramientas que modifican el estado, los archivos y el código.
• Trata el contenido de la página, las instantáneas de accesibilidad, la salida de consola y la salida de red como algo no confiable. Una página puede contener instrucciones para inyectar solicitudes.
• Mantén las instrucciones del sistema separadas del texto derivado de la página. No permitas que el contenido de la página cambie la política de seguridad ni las normas de aprobación.
• Valida las URLs de destino frente a una lista de permisos al automatizar aplicaciones sensibles.
• Revisa texto, selectores, contenido de archivos y código antes de aprobar una llamada a una herramienta.
• No utilices tokens de acceso en indicaciones, archivos fuente, capturas de pantalla, archivos cargados ni fragmentos de JavaScript.
• Utiliza tokens de corta duración, renuévalos periódicamente y revoca las conexiones que no se utilicen.
• Utiliza un espacio de trabajo dedicado y una identidad de mínimo privilegio para cada límite de confianza.
• Registra aprobaciones y nombres de herramientas para auditorías, pero no registres credenciales, contenido subido ni datos sensibles de páginas.

Disponibilidad regional

Espacios de trabajo de dramaturgo está disponible en las siguientes regiones de Azure:

Contenido relacionado

• Gestionar tokens de acceso al espacio de trabajo
• Gestionar el acceso a un espacio de trabajo de dramaturgo
• Conectar agentes de Microsoft Foundry a los endpoints del servidor MCP
• Añadir y gestionar servidores MCP en Visual Studio Code
• Documentación del protocolo de contexto de modelo