Quickstart: Automatizar tarefas do navegador com o servidor remoto MCP do Espaços de trabalho para dramaturgos

Neste quickstart, liga um agente de IA ao servidor remoto MCP do Espaços de trabalho para dramaturgos. O agente utiliza um navegador cloud gerido para abrir uma página web, inspecionar o seu instantâneo de acessibilidade, reportar o conteúdo da página e fechar a sessão do navegador.

O servidor MCP remoto disponibiliza ferramentas de automatização do navegador através de HTTP com transmissão em fluxo. Não precisas de instalar o Playwright, binários do navegador ou um servidor MCP local no ambiente do agente.

Depois de concluir este guia de início rápido, passa a ter um cliente MCP ligado a uma área de trabalho do Playwright e pode executar uma tarefa no navegador controlada por agente no GitHub Copilot CLI ou no Microsoft Foundry.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
• Um espaço de trabalho do Playwright com a pré-visualização remota do MCP ativada.
• O papel Contribuidor ou Proprietário Azure no âmbito do espaço de trabalho. Este papel é necessário para criar um token de acesso ao espaço de trabalho. Para mais informações, consulte Gerir acesso a um espaço de trabalho de Playwright.
• Um dos seguintes clientes MCP:
  • CLI do GitHub Copilot com suporte para MCP.
  • Um projeto Microsoft Foundry com permissão para criar ligações de projeto e configurar agentes.

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.

Use um token de acesso ao espaço de trabalho apenas quando o cliente MCP não conseguir autenticar-se com o Microsoft Entra ID. Os tokens de acesso são menos seguros e estão desativados por defeito.

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:

Criar um token de acesso ao espaço de trabalho

Este quickstart utiliza autenticação baseada em chaves. O cliente MCP envia um token de acesso ao espaço de trabalho no cabeçalho do x-api-key pedido.

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. Selecione a caixa de verificação Playwright Service Access Token se ainda não estiver selecionada.
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.

O token está associado ao utilizador que o cria. O serviço avalia as permissões atuais de controlo de acesso baseado em funções (RBAC) do Azure desse utilizador quando o token é utilizado. Use um período de expiração curto para este quickstart.

Para mais informações, consulte Gerir tokens de acesso ao espaço de trabalho.

Criar o endpoint remoto do MCP

No portal Azure, abra a página de Visão Geral do seu espaço de trabalho de Playwright. Use a região do espaço de trabalho e o ID do espaço de trabalho para construir o endpoint MCP remoto.

O endpoint utiliza o seguinte formato:

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

Por exemplo:

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

Use o endpoint da região onde o espaço de trabalho está implantado.

Ligue um cliente MCP

Escolhe o cliente MCP que queres usar.

GitHub Copilot CLI

Para adicionar o servidor remoto MCP do Espaços de trabalho para dramaturgos ao GitHub Copilot CLI:

1. Abre a CLI do GitHub Copilot.
2. Introduza /mcp add.
3. Insira um nome de servidor único, como playwrightWorkspace.
4. Selecione HTTP como tipo de servidor.
5. Introduza o endpoint remoto do MCP.
6. Adicione um cabeçalho HTTP nomeado x-api-key e use o token de acesso ao espaço de trabalho como seu valor.
7. Selecione Auto para ferramentas diferidas.
8. Prima Esc para concluir a adição do servidor.

Microsoft Foundry

Liga o servidor remoto como uma ferramenta MCP personalizada. O Foundry armazena o token de acesso ao espaço de trabalho numa ligação de projeto.

Para ligar o servidor MCP remoto:

1. Abra o seu projeto no portal Microsoft Foundry.
2. Selecione Ferramentas de Compilação> e depois selecione Adicionar ferramenta>Protocolo de Contexto de Modelo Personalizado>.
3. Inscreva playwrightWorkspace como o nome único.
4. Introduza o endpoint do servidor MCP remoto.
5. Selecione autenticação baseada em chaves.
6. Introduza x-api-key como nome da credencial e o token de acesso ao espaço de trabalho como valor da credencial.
7. Selecione Conectar. A Foundry cria a ligação ao projeto.

Crie ou abra um agente, adicione a ferramenta MCP remota e selecione a ligação ao projeto. Exija aprovação para cada chamada de ferramenta enquanto avalias a integração. Exigir aprovação permite-lhe inspecionar o nome da ferramenta e os argumentos antes de cada operação do navegador.

Para campos de ligação atuais e comportamento de aprovação, consulte Ligar agentes Microsoft Foundry aos endpoints dos servidores MCP.

Execute a sua primeira tarefa de navegador

Envie o seguinte prompt ao agente:

Use the Playwright workspace tools to create a browser session, open
https://example.com, inspect the page snapshot, and report the main heading
and page URL. Close the browser session when the task finishes. Always close
the session if a browser step fails.

Verifique se o agente segue esta sequência:

1. Chama create_browser_session e retém o valor devolvido browserSessionId.
2. Chama browser_navigate com o ID da sessão e https://example.com.
3. Efetua chamadas para browser_snapshot ou browser_find com o mesmo ID de sessão.
4. Reporta o título do Domínio de Exemplo e o URL da página.
5. Chama close_browser_session com o ID da sessão.

Um resultado bem-sucedido assemelha-se ao seguinte resultado:

Heading: Example Domain
URL: https://example.com/
Browser session closed.

A resposta exata varia consoante o agente e o modelo. O resultado da criação da sessão pode também conter uma URL de visualização em direto. A resposta final, por si só, não confirma a limpeza. Inspecione o histórico de chamadas da ferramenta e verifique se close_browser_session foi bem-sucedida.

Limpeza de recursos

Quando terminares o guia de iniciação rápida:

1. Confirme que o agente ligou close_browser_session.
2. Se criaste um espaço de trabalho do Playwright apenas para este início rápido, elimina o respetivo grupo de recursos. Não apagues um grupo de recursos que contenha recursos que queres manter.

Passo seguinte