Automatize os navegadores com o servidor MCP remoto do Espaços de trabalho para dramaturgos

O servidor remoto MCP da Espaços de trabalho para dramaturgos oferece aos agentes de IA um navegador remoto gerido e um conjunto de ferramentas de automação de browsers. 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 ecrã e fechar a sessão. Não precisas de instalar o Playwright ou um navegador no ambiente do agente.

O servidor utiliza o Model Context Protocol sobre HTTP Streamable. Suporta a autenticação do Microsoft Entra ID e os tokens de acesso ao espaço de trabalho. Funciona com clientes MCP remotos, incluindo o Microsoft Foundry Agent Service e o Visual Studio Code.

Neste artigo, você aprenderá a:

• Crie o endpoint 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.
• Ligue o servidor ao Microsoft Foundry Agent Service ou ao Visual Studio Code.
• Execute fluxos completos de automação autónoma do navegador.
• Selecione e utilize com segurança as ferramentas de navegador disponíveis.
• Trate da expiração da sessão, tempos de espera e outros erros comuns.

Pré-requisitos

Antes de começar, certifique-se de que tem:

• Uma conta do Azure com uma assinatura ativa.
• Um espaço de trabalho Playwright com acesso à versão preliminar remota do MCP.
• O ID do espaço de trabalho e a região Azure do espaço de trabalho.
• Uma identidade com permissão para criar e usar sessões de navegador no espaço de trabalho.
• No Microsoft Foundry, um projeto do Foundry e permissão para criar ligações de projeto e configurar agentes.
• Para o Visual Studio Code, uma versão recente do Visual Studio Code com acesso ao GitHub Copilot e suporte para MCP ativado.

Escolha um método de autenticação

Use o Microsoft Entra ID quando o seu cliente MCP suporta OAuth ou identidade gerida. O servidor MCP remoto utiliza este identificador de recurso e o âmbito delegado:

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

O servidor publica metadados de recursos protegidos OAuth. Os clientes que suportam a deteção de OAuth, incluindo o Visual Studio Code, podem detetar o servidor de autorização e o âmbito necessário a partir do endpoint MCP associado ao espaço de trabalho. A identidade com sessão iniciada tem de ter acesso ao espaço de trabalho do Playwright através do controlo de acesso baseado em funções (RBAC) do Azure.

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

Evite esta secção quando usar o Microsoft Entra ID. Se a autenticação por token de acesso ainda não estiver ativada para o espaço de trabalho:

1. Inicie sessão no portal Azure.
2. Abra o seu espaço de trabalho de Dramaturgo.
3. Em Definições, selecione Gestão de Acessos.
4. Ativar o Token de Acesso ao Serviço Playwright.
5. Selecione Gerar token.
6. Insira um nome e uma data de validade, e depois gera o token.
7. Copie o token imediatamente. Não podes recuperar o seu valor mais tarde.

Armazene o token numa loja secreta gerida ou na facilidade de credencial segura fornecida pelo seu cliente MCP. Revoque-o e substitua-o se este puder ter sido exposto. Para criar um token de acesso ao espaço de trabalho, veja Gerir tokens de acesso ao espaço de trabalho.

Criar o endpoint remoto do MCP

O endpoint está limitado a uma área de trabalho e a uma 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 apresentado no portal do Azure.

Por exemplo:

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

O valor no cabeçalho do pedido x-api-key deve ser um token de acesso criado para o mesmo espaço de trabalho que <workspace-id>. Utilize o endpoint da região da área de trabalho, e não o da região mais próxima do cliente MCP.

Compreenda o ciclo de vida das sessões do navegador

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

1. Ligue para o create_browser_session. O resultado contém um opaco browserSessionId e pode conter um URL de visualização em direto.
2. Passe isso browserSessionId para cada ferramenta do navegador utilizada no fluxo.
3. Chame close_browser_session numa 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. Mantém-na privada e usa-a apenas com o espaço de trabalho e a identidade que a criaram.

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

• Uma sessão pertence ao seu criador e não pode ser partilhada com outro principal.
• As chamadas para uma sessão são processadas por ordem. Não emita ações simultâneas contra a mesma sessão.
• Uma sessão inativa é limpa após 15 minutos. É necessária uma limpeza explícita.
• Uma sessão encerrada ou expirada não pode ser reaberta.
• A perda de ligação termina a sessão. Cria uma nova sessão para continuar.
• Um resultado pode conter um liveViewUrl. A disponibilidade da visualização ao vivo depende da sessão.

Conectar-se através do Serviço de Agentes Microsoft Foundry

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

Criar a ligação ao projeto

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

A identidade gerida do projeto tem de ter uma função que permita operações de sessão do navegador no espaço de trabalho Playwright de destino. Não uses um token de identidade de um projeto como segredo partilhado noutro projeto.

Se o Microsoft Entra Agent Identity não estiver disponível para o cliente ou ambiente, crie uma ligação de chaves personalizadas com uma chave nomeada x-api-key e um token de acesso ao espaço de trabalho como 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. Utilize as seguintes definições:

   Setting	Value
   Etiqueta do servidor	Um rótulo único, como playwrightWorkspace
   URL do servidor	O endpoint remoto MCP ao nível do espaço de trabalho
   Ligação ao projeto	A ligação Microsoft Entra Agent Identity criada anteriormente
   Approval	Exija aprovação para cada chamada ao avaliar a integração
   Ferramentas permitidas	Comece apenas com as ferramentas necessárias para o fluxo de trabalho

4. Guarda a configuração do agente.

5. Nas instruções do agente, indique que o agente deve criar uma única sessão, reutilizar o seu browserSessionId e fechar 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 apenas quando o cenário o exigir. Não ative browser_evaluate nem browser_run_code por defeito.

Testar 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 identificador do servidor corresponde ao servidor Playwright configurado.
2. Revê o nome da ferramenta e todos os argumentos, especialmente URLs, seletores, texto, dados carregados e código.
3. Aprove apenas a operação prevista.
4. Verifica se a resposta final se baseia no resultado da página.
5. Confirme que o fluxo denominado close_browser_session.

Para campos de ligação atuais do Foundry, gestão de aprovações, exemplos de SDK e limites de clientes, consulte Conectar agentes aos endpoints do servidor MCP.

Liga-te a partir do Visual Studio Code

O Visual Studio Code pode descobrir a configuração OAuth do servidor remoto e iniciar sessão com o Microsoft Entra ID. A configuração necessita apenas do endpoint ao nível da área de trabalho.

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. Inicia o servidor a partir do editor de configuração ou executa o MCP: List Servers.
4. Quando solicitado, inicie sessão com a conta Microsoft Entra que tem acesso ao espaço de trabalho Playwright.
5. Aprove a autorização solicitada Playwright.Mcp.Tools se for necessário consentimento para o seu inquilino.
6. Revê a URL e a configuração do servidor, e depois confirma que confias no servidor.
7. Abre o Chat e seleciona Configurar Ferramentas. Ative apenas as ferramentas de dramaturgo necessárias para a tarefa.
8. Execute o prompt de exemplo da secção anterior do Foundry.
9. Revise as confirmações da ferramenta e verifique se a sessão está encerrada no final.

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

Se a autenticação Microsoft Entra não estiver disponível no ambiente do cliente, configure um cabeçalho x-api-key com um input protegido, 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, consulte Adicionar e gerir servidores MCP no Visual Studio Code e a referência de configuração MCP.

Projetar um fluxo de automação agential

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

1. Criar: Invocar create_browser_session e reter o respetivo browserSessionId.
2. Navegar: Chame browser_navigate com um URL explícito e autorizado.
3. Nota: Utilize browser_find para uma pesquisa direcionada ou browser_snapshot para uma perspetiva mais abrangente da acessibilidade.
4. Agir: Use uma referência de snapshot ou seletor único com uma ferramenta de interação.
5. Aguarde: Chame browser_wait_for para texto esperado, texto que desaparece ou um atraso delimitado.
6. Verifique: Tire outra captura de ecrã ou inspecione a atividade da consola e da rede.
7. Lidar com ramos: Gerir um diálogo, mudar de separador ou carregar ficheiros apenas quando o estado da página o exigir.
8. Recolha provas: Chame browser_take_screenshot se um resultado visual for útil. Não uses capturas de ecrã para selecionar alvos de ação.
9. Limpar: Chame close_browser_session num caminho de limpeza do tipo finally.

Escolha alvos de ação estável

Prefira referências devolvidas por browser_snapshot ou browser_find. 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 não houver uma referência estável de snapshot.

Atualize a captura após navegar ou depois de uma ação que altere a página. Um alvo devolvido anteriormente pode tornar-se obsoleto quando a página é rerenderizada.

Lidar com diálogos com segurança

Uma ação pode devolver um dialog-opened resultado depois de já ter alterado o estado da página. Este resultado não é uma falha normal de ação.

1. Não repitas a ação original.
2. Invoque browser_handle_dialog com accept definido como true ou false.
3. Para um diálogo de prompt, inclua promptText apenas quando o aceitar.
4. Observe a página novamente antes de continuar.

Tratar falhas ambíguas

Um tempo limite excedido 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 um clique, submissão 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. Determinar se a mudança de estado esperada ocorreu.
3. Tente novamente apenas 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 associadas ao navegador requerem browserSessionId. Os limites da cadeia e da coleção aqui mostrados 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, ficheiros e ferramentas de código

Após cada fluxo de automação, chama 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 cadeia de caracteres 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 ficheiro

Cada browser_file_upload ficheiro utiliza esta forma:

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

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

Limites de upload de ficheiros

• Entre 1 a 20 ficheiros por chamada de ferramenta.
• Tamanho máximo decodificado de 10 MiB para cada ficheiro.
• Tamanho máximo combinado decodificado de 50 MiB.
• Nome máximo de ficheiro de 4.096 caracteres.
• Tipo MIME com um máximo de 1.024 caracteres.
• São necessários dados base64 válidos.

Formas de ferramentas JavaScript

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

() => document.title

Quando 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 é uma página do Playwright. Devolva apenas dados serializáveis em JSON e mantenha-os dentro do limite de resposta em linha.

Limites e comportamento atual

As respostas são devolvidas em linha. Esta pré-visualização não expõe recursos MCP nem armazenamento persistente de artefactos para grandes instantâneos, capturas de ecrã ou downloads. Os overrides do navegador, sistema operativo, viewport, localização e user-agent não são expostos como parâmetros de criação de sessões.

Tratamento de erros

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

Solucionar problemas comuns

O cliente MCP indica “Não autorizado”

• Confirme que a autenticação por token de acesso está ativada para o espaço de trabalho.
• Confirma que o token não está expirado nem revogado.
• Utilize o valor bruto do token como valor de x-api-key. Não adiciones um Bearer prefixo.
• Confirme que o token e o endpoint pertencem ao mesmo espaço de trabalho.
• Se copiaste um segredo incorretamente, cria um novo token porque não consegues recuperar valores existentes do portal.

O cliente do MCP relata Forbidden

• Confirme que o utilizador associado ao token ainda tem permissão para criar sessões do navegador.
• Use a mesma ligação ao projeto ou token para todas as chamadas numa sessão de navegador.
• Não passe um browserSessionId entre utilizadores, agentes que utilizam credenciais diferentes ou espaços de trabalho.

As ferramentas não são detetadas

• Verifique o endpoint completo, incluindo /playwrightworkspaces/<workspace-id>/mcp.
• Verifique se a região do ponto de extremidade corresponde à da área de trabalho.
• Confirme que o cliente utiliza um transporte HTTP MCP e envia x-api-key durante a descoberta e chamadas à ferramenta.
• No Visual Studio Code, executa MCP: List Servers, seleciona o servidor e depois seleciona Mostrar Saída.
• Reinicia a conexão MCP ou repõe as ferramentas em cache depois de alterar o endpoint.

O agente não chama uma ferramenta de navegador

• Diz 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.
• Inclui o ciclo de vida 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 alvo já não funciona

A página pode ter mudado ou sido renderizada novamente. Volte a ligar para browser_snapshot ou browser_find e use uma referência atual. Evite seletores ligados a classes geradas ou que alterem a estrutura do documento.

Uma ferramenta com tempo esgotado

Não assuma que a ação falhou sem que tenha havido alteração de estado. 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 devolva a aplicação a um estado conhecido.

Uma captura de ecrã é demasiado grande

Use type: "jpeg", capture apenas a área visível, ou indique um destino para uma captura de ecrã ao nível do elemento. Use browser_snapshot quando o objetivo é identificar um elemento em vez de preservar evidências visuais.

A sessão terminou durante um fluxo

Crie uma nova sessão no navegador. As sessões não se restabelecem após perda de ligação do navegador, indisponibilidade do proprietário do serviço, encerramento explícito ou limpeza por inatividade. Projete o fluxo para que possa reiniciar a partir de um 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 alteração de estado, ficheiros e código.
• Considere o conteúdo da página, as capturas de acessibilidade, a saída da consola e a saída da rede como não fidedignos. 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 que o conteúdo da página altere a política de segurança ou as regras de aprovação.
• Valide os URLs de destino com base numa lista de permissões ao automatizar aplicações sensíveis.
• Revise texto, seletores, conteúdos de ficheiros e código antes de aprovar uma chamada de ferramenta.
• Não uses tokens de acesso em prompts, ficheiros fonte, capturas de ecrã, ficheiros carregados ou excertos JavaScript.
• Usa tokens de curta duração, roda-os regularmente e revoga ligações não utilizadas.
• Use um espaço de trabalho dedicado e uma identidade de menor privilégio para cada limite de confiança.
• Regista aprovações e nomes de ferramentas para auditoria, mas não registas credenciais, conteúdos carregados ou dados sensíveis das páginas.

Disponibilidade regional

O Espaços de trabalho para dramaturgos está disponível nas seguintes regiões do Azure:

Conteúdo relacionado

• Gerir tokens de acesso ao espaço de trabalho
• Gerir o acesso a um espaço de trabalho para dramaturgos
• Ligue agentes Microsoft Foundry aos endpoints dos servidores MCP
• Adicionar e gerir servidores MCP no Visual Studio Code
• Documentação do Model Context Protocol