Automatize navegadores com o servidor MCP remoto do Workspaces do dramaturgo

O servidor remoto MCP do Workspaces do dramaturgo oferece aos agentes de IA um navegador remoto gerenciado e um conjunto de ferramentas de automação de navegadores. Um agente pode abrir uma sessão do navegador, navegar por páginas, encontrar e interagir com elementos, inspecionar a atividade do navegador, tirar capturas de tela e fechar a sessão. Você não precisa instalar o Playwright ou um navegador no ambiente do agente.

O servidor utiliza o Protocolo de Contexto de Modelo sobre HTTP Streamable. Ele suporta a autenticação do Microsoft Entra ID e tokens de acesso ao espaço de trabalho. Ele funciona com clientes MCP remotos, incluindo Microsoft Foundry Agent Service e Visual Studio Code.

Neste artigo, você aprenderá como:

• Crie o endpoint do MCP para um espaço de trabalho do Playwright.
• Autentique usando o Microsoft Entra ID ou um token de acesso ao espaço de trabalho.
• Conecte o servidor ao Microsoft Foundry Agent Service ou ao Visual Studio Code.
• Execute fluxos completos de automação de navegador baseada em agentes.
• Selecione e use com segurança as ferramentas de navegador disponíveis.
• Trate do vencimento da sessão, tempos de espera e outros erros comuns.

Pré-requisitos

Antes de começar, verifique se você tem:

• Uma conta do Azure com uma assinatura ativa.
• Um ambiente de trabalho do Playwright que tem acesso à versão prévia remota do MCP.
• A ID do espaço de trabalho e a região do Azure do espaço de trabalho.
• Uma identidade com permissão para criar e usar sessões de navegador no espaço de trabalho.
• Para o Microsoft Foundry, um projeto do Foundry e permissão para criar conexões de projeto e configurar agentes.
• Para o Visual Studio Code, uma versão atual do Visual Studio Code com acesso ao GitHub Copilot e com suporte ao MCP habilitado.

Escolher um método de autenticação

Use o Microsoft Entra ID quando seu cliente MCP oferecer suporte ao OAuth ou à identidade gerenciada. O servidor MCP remoto usa este identificador de recurso e escopo delegado:

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

O servidor publica metadados de recursos protegidos OAuth. Clientes que oferecem suporte à descoberta do OAuth, incluindo o Visual Studio Code, podem descobrir o servidor de autorização e o escopo necessário a partir do endpoint MCP com escopo no workspace. A identidade logada deve ter acesso ao espaço de trabalho Playwright por meio do controle de acesso baseado em função (RBAC) do Azure.

Crie um token de acesso ao espaço de trabalho para compatibilidade

Pule esta seção quando usar o Microsoft Entra ID. Se a autenticação por token de acesso ainda não estiver ativada para o workspace:

1. Entre no portal do Azure.
2. Abra seu espaço de trabalho de Playwright.
3. Em Configurações, selecione Gerenciamento de Acesso.
4. Ative o Token de Acesso ao Serviço de Playwright.
5. Selecione Gerar token.
6. Insira um nome e data de validade, e então gere o token.
7. Copie o token imediatamente. Você não pode recuperar seu valor depois.

Armazene o token em um armazenamento secreto gerenciado ou na facilidade de credencial segura fornecida pelo seu cliente MCP. Revogue e substitua-o se ele tiver sido exposto. Para criar um token de acesso ao espaço de trabalho, veja Gerenciar tokens de acesso ao espaço de trabalho.

Construa o endpoint remoto do MCP

O endpoint está restrito a um único espaço de trabalho e região:

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

Substituir:

• <region>com a região Azure do espaço de trabalho.
• <workspace-id> com o ID do espaço de trabalho mostrado no portal do Azure.

Por exemplo:

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

O valor no cabeçalho da requisição x-api-key deve ser um token de acesso criado para o mesmo workspace do que <workspace-id>. Use o ponto de extremidade para a região do espaço de trabalho, não a região mais próxima do cliente MCP.

Entenda o ciclo de vida das sessões do navegador

Um fluxo de automação de navegador possui três etapas:

1. Chame create_browser_session. O resultado contém um browserSessionId opaco e pode conter uma URL de visualização em tempo real.
2. Passe browserSessionId para todas as ferramentas de navegador usadas no fluxo.
3. Chame close_browser_session em uma etapa de limpeza, mesmo quando o fluxo falhar.

O transporte HTTP MCP não preserva o estado do navegador. O browserSessionId identifica o navegador remoto em diferentes chamadas da ferramenta. Mantenha isso em sigilo e use-o apenas com o espaço de trabalho e a identidade que o criaram.

O comportamento atual de pré-visualização inclui estas restrições:

• Uma sessão pertence ao seu criador e não pode ser compartilhada com outro principal.
• As chamadas de uma sessão são processadas em ordem. Não emita ações simultâneas contra a mesma sessão.
• Uma sessão inativa é limpa após 15 minutos. É necessário um processo explícito de limpeza.
• Uma sessão fechada ou expirada não pode ser reaberta.
• A perda de conexão encerra a sessão. Crie uma nova sessão para continuar.
• Um resultado pode conter um liveViewUrl. A disponibilidade da visualização ao vivo depende da sessão.

Conecte-se pelo Serviço de Agentes Microsoft Foundry

Use o Microsoft Entra Agent Identity para autenticar o agente com a identidade gerenciada do projeto Foundry. Conceda a essa identidade acesso ao espaço de trabalho do Playwright antes de conectar a ferramenta MCP.

Criar a conexão do projeto

1. Abra seu projeto no portal do Microsoft Foundry.
2. Abra a experiência de gestão do projeto e então selecione Recursos conectados.
3. Crie uma conexão para um servidor MCP remoto.
4. Insira um nome de conexão descritiva, como playwright-mcp-connection.
5. Selecione Microsoft Entra Agent Identity como método de autenticação.
6. Insira https://mcp.playwright.microsoft.com como público-alvo.
7. Salve a conexão.

A identidade gerenciada do projeto deve ter uma função que permita operações de sessão do navegador no workspace do Playwright de destino. Não use um token de identidade de um projeto como segredo compartilhado em outro projeto.

Se o Microsoft Entra Agent Identity não estiver disponível para o cliente ou ambiente, crie uma conexão de chaves personalizadas com uma chave nomeada x-api-key e um token de acesso ao espaço de trabalho como seu valor.

Adicionar a ferramenta MCP remota

1. Crie ou abra um agente no portal da Foundry.

2. Adicione um servidor MCP remoto ou uma ferramenta MCP.

3. Use as configurações a seguir:

   Setting	Value
   Rótulo do servidor	Um rótulo único, como playwrightWorkspace
   URL do servidor	O endpoint remoto do MCP com escopo no espaço de trabalho
   Conexão de projeto	A conexão de Microsoft Entra Agent Identity criada anteriormente
   Aprovação	Exigir aprovação para cada chamada ao avaliar a integração
   Ferramentas permitidas	Comece apenas com as ferramentas necessárias para o fluxo

4. Salve a configuração do agente.

5. Nas instruções do agente, exija que o agente crie uma sessão, reutilize seu browserSessionId, e feche a sessão quando a tarefa terminar.

Uma lista mínima de ferramentas para um fluxo de navegação orientado à leitura é:

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

Adicione ferramentas de interação, como browser_click ou browser_type somente quando o cenário exigir. Não ative browser_evaluate ou browser_run_code por padrão.

Teste o escoamento da fundição

Use um prompt que indique o objetivo e a necessidade de limpeza. Por exemplo:

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.

Quando o agente solicita aprovação:

1. Verifique se o rótulo do servidor corresponde ao servidor Playwright configurado.
2. Revise o nome da ferramenta e todos os argumentos, especialmente URLs, seletores, texto, dados enviados e código.
3. Aprove apenas a operação esperada.
4. Verifique se a resposta final é baseada no resultado da página.
5. Confirme que o fluxo se chama close_browser_session.

Para campos de conexão atuais do Foundry, gerenciamento de aprovação, exemplos de SDK e limites de clientes, veja Conectar agentes aos endpoints do servidor MCP.

Conectar-se a partir do Visual Studio Code

O Visual Studio Code pode detectar a configuração OAuth do servidor remoto e conectar você usando o Microsoft Entra ID. A configuração precisa apenas do endpoint no escopo do workspace.

1. No Visual Studio Code, execute o comando MCP: Open User Configuration na Paleta de Comandos.
2. Adicione a seguinte configuração e substitua os marcadores de posição dos endpoints.

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

3. Inicie o servidor pelo editor de configuração ou execute o MCP: List Servers.
4. Quando solicitado, faça login com a conta Microsoft Entra que tem acesso ao espaço de trabalho do Playwright.
5. Aprove a permissão solicitada Playwright.Mcp.Tools se o consentimento for necessário para seu locatário.
6. Revise a URL do servidor e a configuração, e então confirme que você confia no servidor.
7. Abra o Chat e selecione Configurar Ferramentas. Ative apenas as ferramentas de Dramaturgo necessárias para a tarefa.
8. Execute o prompt de exemplo da seção anterior do Foundry.
9. Revise as confirmações da ferramenta e verifique se a sessão está encerrada ao final.

Use uma configuração de usuário quando a conexão for pessoal. Uma configuração de espaço de trabalho contendo apenas o endpoint pode ser compartilhada. O Visual Studio Code armazena as credenciais OAuth em cache de forma segura e pode reutilizá-las ao se reconectar.

Se a autenticação do Microsoft Entra não estiver disponível no ambiente do cliente, configure um cabeçalho x-api-key com uma entrada protegida, conforme descrito em Entradas de configuração do MCP. Nunca coloque o valor do token de acesso ao workspace diretamente em mcp.json.

Para localizações de configuração, entradas secretas, confiança em servidores e diagnósticos, veja Adicionar e gerenciar servidores MCP no Visual Studio Code e na referência de configuração MCP.

Projete um fluxo de automação agential

Use um loop observar-agir-verificar em vez de pedir ao agente para executar uma sequência longa sem verificar o estado da página.

1. Criar: Chame create_browser_session e retenha seu browserSessionId.
2. Navegar: Chame browser_navigate usando uma URL explícita e aprovada.
3. Observação: Use browser_find para uma busca direcionada ou browser_snapshot para uma visão mais ampla sobre acessibilidade.
4. Aja: use uma referência de instantâneo ou um seletor exclusivo com uma ferramenta de interação.
5. Espere: Chame browser_wait_for para texto esperado, texto que desaparece ou um atraso determinado.
6. Verificar: Capturar outro snapshot ou inspecionar a atividade do console e da rede.
7. Gerencie ramos: Gerencie um diálogo, troque de aba ou envie arquivos apenas quando o estado da página exigir.
8. Capture evidências: chame browser_take_screenshot se um resultado visual for útil. Não use capturas de tela para selecionar alvos de ação.
9. Limpeza: Chame close_browser_session em um caminho de limpeza no estilo `finally`.

Escolha alvos de ação estável

Prefera referências retornadas por browser_snapshot ou browser_find. Eles descrevem elementos de página acessíveis e reduzem a dependência da marcação específica da implementação. Use um seletor único quando uma referência estável de snapshot não estiver disponível.

Atualize o snapshot após a navegação ou após uma ação de mudança de página. Um elemento de destino retornado anteriormente pode ficar obsoleto quando a página é renderizada novamente.

Gerencie diálogos com segurança

Uma ação pode devolver um dialog-opened resultado após já ter mudado o estado da página. Esse resultado não é uma falha normal de ação.

1. Não repita a ação original.
2. Chame browser_handle_dialog com accept definido como true ou false.
3. Para uma caixa de diálogo de prompt, inclua promptText apenas ao aceitá-lo.
4. Observe a página novamente antes de continuar.

Lidar com falhas ambíguas

Um tempo esgotado ou um chamador desconectado não prova que uma ação não teve efeito. Antes de tentar novamente uma operação não idempotente, como clique, envio de formulário, upload ou execução de código:

1. Chame browser_snapshot, browser_find, ou outra ferramenta de observação se a sessão ainda estiver disponível.
2. Determine se a mudança de estado esperada ocorreu.
3. Retente somente se repetir a ação for seguro.
4. Se a sessão expirar, crie uma nova sessão e reinicie a partir de um estado de aplicação conhecido.

Referência da ferramenta

Todas as ferramentas com escopo de navegador exigem browserSessionId. Os limites de string e de coleção mostrados aqui são os limites atuais de pré-visualização.

Ferramentas de sessão

Ferramentas de navegação e observação

Ferramentas de interação

Abas, arquivos e ferramentas de código

Após cada fluxo de trabalho de automação, chame o close_browser_session com o browserSessionId ativo.

Formato do campo de formulário

Cada browser_fill_form campo tem esta forma:

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

O valor da string para um campo pode conter no máximo 100 KiB de caracteres. name pode conter no máximo 1.024 caracteres, e type pode conter no máximo 128 caracteres.

Forma de upload do arquivo

Cada browser_file_upload arquivo usa esta forma:

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

mimeType é opcional e usa application/octet-stream como padrão.

Limites de upload de arquivos

• De 1 a 20 arquivos por chamada de ferramenta.
• Tamanho máximo decodificado de 10 MiB para cada arquivo.
• Tamanho máximo combinado decodificado de 50 MiB.
• Nome máximo de arquivo de 4.096 caracteres.
• Tipo MIME com 1.024 caracteres no máximo.
• Dados válidos do base64 são necessários.

Formas de ferramentas JavaScript

Para browser_evaluate, passe uma expressão de função:

() => document.title

Quando você fornece target, a função recebe o elemento correspondente:

element => element.textContent

Para browser_run_code, passe instruções que formem o corpo de uma função assíncrona cujo parâmetro page seja uma página do Playwright. Retorne apenas dados serializáveis em JSON e mantenha-os dentro do limite de resposta inline.

Limites e comportamento atual

As respostas são retornadas em linha. Esta versão de prévia não disponibiliza recursos do MCP nem armazenamento persistente de artefatos para instantâneos, capturas de tela ou downloads grandes. As sobrescrições de navegador, sistema operacional, viewport, local e user-agent não são expostas como parâmetros de criação de sessão.

Tratamento de erros

Um erro da ferramenta inclui um código de erro estável, uma mensagem segura para o cliente, um valor retryable e informações de correlação. Use o valor retornado retryable como sinal principal, junto com os efeitos colaterais da operação.

Solucionar problemas comuns

O cliente MCP retorna "Unauthorized"

• Confirme que a autenticação por token de acesso está habilitada para o workspace.
• Confirme que o token não está expirado ou revogado.
• Use o valor bruto do token como o valor x-api-key. Não adicione um Bearer prefixo.
• Confirme que o token e o endpoint pertencem ao mesmo workspace.
• Se você copiou um segredo incorretamente, crie um novo token porque não consegue recuperar valores existentes do portal.

O cliente do MCP relata Forbidden

• Confirme que o usuário associado ao token ainda tem permissão para criar sessões do navegador.
• Use a mesma conexão de projeto ou token para todas as chamadas em uma única sessão do navegador.
• Não compartilhe um browserSessionId entre usuários, agentes que usam credenciais diferentes ou espaços de trabalho.

Ferramentas não são encontradas

• Verifique o endpoint completo, incluindo /playwrightworkspaces/<workspace-id>/mcp.
• Verifique se a região do endpoint corresponde à região do workspace.
• Confirme que o cliente usa um transporte HTTP MCP e envia x-api-key durante a descoberta e chamadas de ferramenta.
• No Visual Studio Code, execute o MCP: List Servers, selecione o servidor e depois selecione Mostrar Saída.
• Reinicie a conexão MCP ou reinicie as ferramentas em cache após mudar o endpoint.

O agente não chama uma ferramenta de navegador

• Diga explicitamente ao agente para usar o servidor MCP configurado do Playwright.
• Verifique se a ferramenta necessária aparece na lista de ferramentas habilitadas ou permitidas do cliente.
• Inclua o ciclo de criar, usar e fechar nas instruções do agente.
• Use uma primeira tarefa focada com um único alvo de navegação e um resultado esperado.

Um destino não funciona mais

A página pode ter navegado ou sido renderizada novamente. Ligue para browser_snapshot ou browser_find novamente e use uma referência atual. Evite seletores vinculados a classes geradas ou mudanças na estrutura do documento.

Uma ferramenta com tempo de vencimento

Não suponha que a ação falhou sem que o estado tenha sido alterado. Se a sessão estiver ativa, inspecione a página atual antes de tentar novamente. Se a sessão expirar, crie uma nova sessão e retorne a aplicação a um estado conhecido.

A captura de tela é grande demais

Use type: "jpeg", capture apenas a área de visualização ou especifique um alvo para uma captura de tela no nível do elemento. Use browser_snapshot quando o objetivo é identificar um elemento em vez de preservar evidências visuais.

A sessão expirou durante um fluxo

Crie uma nova sessão do navegador. As sessões não se reconectam após perda de conexão do navegador, indisponibilidade do proprietário do serviço, fechamento explícito ou limpeza por inatividade. Projete o fluxo para que ele possa reiniciar a partir de uma URL e estado da aplicação conhecidos.

Recomendações de segurança

• Permita apenas as ferramentas exigidas pela tarefa do agente.
• Exigir aprovação humana para ferramentas de mudança de estado, arquivos e código.
• Trate o conteúdo da página, capturas de acessibilidade, saída do console e saída da rede como não confiáveis. Uma página pode conter instruções de injeção rápida.
• Mantenha as instruções do sistema separadas do texto derivado da página. Não deixe o conteúdo da página alterar políticas de segurança ou regras de aprovação.
• Valide os URLs de destino com base em uma lista de permissões ao automatizar aplicações sensíveis.
• Revise texto, seletores, conteúdo do arquivo e código antes de aprovar uma chamada de ferramenta.
• Não use tokens de acesso em prompts, arquivos fonte, capturas de tela, arquivos enviados ou trechos em JavaScript.
• Use tokens de curta duração, rotative-os regularmente e revogue conexões não utilizadas.
• Use um espaço de trabalho dedicado e uma identidade de privilégio mínimo para cada limite de confiança.
• Registre aprovações e nomes de ferramentas para auditoria, mas não registre credenciais, conteúdos enviados ou dados sensíveis de páginas.

Disponibilidade regional

Workspaces do dramaturgo está disponível nas seguintes regiões do Azure:

Conteúdo relacionado

• Gerencie tokens de acesso ao workspace
• Gerencie o acesso a um espaço de trabalho de Dramaturgo
• Conecte agentes do Microsoft Foundry aos endpoints dos servidores MCP
• Adicionar e gerenciar servidores MCP no Visual Studio Code
• Documentação do Protocolo de Contexto do Modelo