Automatizza i browser con il server remoto MCP di Spazi di lavoro Playwright

Il server remoto MCP di Spazi di lavoro Playwright offre agli agenti IA un browser remoto gestito e una serie di strumenti di automazione dei browser. Un agente può aprire una sessione del browser, navigare tra le pagine, trovare e interagire con gli elementi, ispezionare l'attività del browser, fare screenshot e chiudere la sessione. Non è necessario installare Playwright o un browser nell'ambiente agente.

Il server utilizza Model Context Protocol su HTTP in streaming. Supporta l'autenticazione Microsoft Entra ID e i token di accesso allo spazio di lavoro. Funziona con client MCP remoti, inclusi Microsoft Foundry Agent Service e Visual Studio Code.

In questo articolo vengono illustrate le operazioni seguenti:

• Costruisci l'endpoint MCP per uno spazio di lavoro Playwright.
• Autentica usando Microsoft Entra ID o un token di accesso allo spazio di lavoro.
• Collega il server a Microsoft Foundry Agent Service o Visual Studio Code.
• Esegui flussi completi di automazione del browser basata su agenti.
• Seleziona e usa in sicurezza gli strumenti di navigazione disponibili.
• Gestisci la scadenza della sessione, i timeout e altri errori comuni.

Prerequisiti

Prima di iniziare, assicurarsi di avere:

• Un account Azure con una sottoscrizione attiva.
• Uno spazio di lavoro per drammaturghi che ha accesso all'anteprima remota MCP.
• L'ID dello spazio di lavoro e la regione Azure dello spazio di lavoro.
• Un'identità con permesso di creare e utilizzare sessioni browser nello spazio di lavoro.
• Per Microsoft Foundry, un progetto Foundry e l'autorizzazione per creare connessioni di progetto e configurare gli agenti.
• Per Visual Studio Code, una versione attuale di Visual Studio Code con accesso a GitHub Copilot e supporto MCP abilitato.

Scegliere un metodo di autenticazione

Usa Microsoft Entra ID quando il tuo client MCP supporta OAuth o identità gestita. Il server MCP remoto utilizza questo identificatore di risorsa e l'ambito delegato:

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

Il server pubblica metadati OAuth con risorse protette. I client che supportano la scoperta OAuth, tra cui Visual Studio Code, possono individuare il server di autorizzazione e lo scope richiesto dall'endpoint MCP con ambito workspace. L'identità con cui è stato effettuato l'accesso deve disporre dell'accesso allo spazio di lavoro Playwright tramite il controllo degli accessi in base al ruolo (RBAC) di Azure.

Crea un token di accesso allo spazio di lavoro per la compatibilità

Salta questa sezione quando usi Microsoft Entra ID. Se l'autenticazione tramite access-token non è già abilitata per lo spazio di lavoro:

1. Accedi al portale di Azure.
2. Apri il tuo spazio di lavoro da Drammaturghino.
3. Sotto Impostazioni, seleziona Gestione Accessi.
4. Abilita il token di accesso al servizio Playwright.
5. Selezionare Genera token.
6. Inserisci un nome e una data di scadenza, poi genera il token.
7. Copiare immediatamente il token. Non puoi recuperarne il valore in seguito.

Memorizza il token in un archivio segreto gestito o nella funzione di credenziali sicura fornita dal tuo client MCP. Revocalo e sostituiscilo se potrebbe essere stato esposto. Per creare un token di accesso allo spazio di lavoro, vedi Gestisci i token di accesso allo spazio di lavoro.

Costruisci l'endpoint MCP remoto

L'endpoint è limitato a un'area di lavoro e a un'area geografica specifiche:

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

Sostituire:

• <region> con l'area di Azure dello spazio di lavoro.
• <workspace-id> con l'ID dello spazio di lavoro mostrato nel portale Azure.

Per esempio:

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

Il valore nell'intestazione x-api-key della richiesta deve essere un token di accesso creato per lo stesso workspace di <workspace-id>. Usa l'endpoint per la regione dello spazio di lavoro, non per quella più vicina al client MCP.

Comprendere il ciclo di vita della sessione del browser

Un flusso di automazione del browser ha tre fasi:

1. Chiamare create_browser_session. Il risultato contiene un URL opaco browserSessionId e potrebbe contenere un URL in visualizzazione in tempo reale.
2. Trasmetti questo browserSessionId a ogni strumento del browser utilizzato nel flusso.
3. Chiama close_browser_session un passaggio di pulizia, anche quando il flusso fallisce.

Il trasporto HTTP MCP non preserva lo stato del browser. Il browserSessionId identifica il browser remoto tra chiamate separate dello strumento. Tienilo privato e usalo solo con lo spazio di lavoro e l'identità che l'ha creato.

Il comportamento attuale di anteprima include questi vincoli:

• Una sessione appartiene al suo creatore e non può essere condivisa con un'altra entità.
• Le chiamate per una sessione vengono elaborate in ordine. Non emettere azioni concorrenti contro la stessa sessione.
• Una sessione inattiva viene ripulita dopo 15 minuti. È richiesta una pulizia esplicita.
• Una sessione chiusa o scaduta non può essere riaperta.
• La perdita di connessione è terminale per la sessione. Crea una nuova sessione per continuare.
• Un risultato potrebbe contenere un liveViewUrl. La disponibilità della visualizzazione live dipende dalla sessione.

Connettiti dal servizio Microsoft Foundry Agent Service

Usa Microsoft Entra Agent Identity per autenticare l'agente con l'identità gestita del progetto Foundry. Concede a quell'identità l'accesso allo spazio di lavoro Playwright prima di collegare lo strumento MCP.

Creare la connessione al progetto

1. Apri il tuo progetto nel portale Microsoft Foundry.
2. Apri l'esperienza di gestione del progetto, poi seleziona Risorse connesse.
3. Crea una connessione per un server MCP remoto.
4. Inserisci un nome di connessione descrittiva, come playwright-mcp-connection.
5. Seleziona Microsoft Entra Agent Identity come metodo di autenticazione.
6. Inserisci https://mcp.playwright.microsoft.com come destinatario.
7. Salva la connessione.

L'identità gestita del progetto deve avere un ruolo che consenta operazioni di sessione browser sullo spazio di lavoro target di Playwright. Non usare un token di identità di un progetto come un segreto condiviso in un altro progetto.

Se Microsoft Entra Agent Identity non è disponibile per il client o l'ambiente, crea una connessione di chiavi personalizzate con una chiave nominata x-api-key e un token di accesso allo spazio di lavoro come valore.

Aggiungi lo strumento MCP remoto.

1. Crea o apri un agente nel portale Foundry.

2. Aggiungi un server MCP remoto o uno strumento MCP.

3. Utilizzare le seguenti impostazioni:

   Setting	Value
   Etichetta del server	Un'etichetta unica, come playwrightWorkspace
   URL del server	L'endpoint MCP remoto con ambito dello spazio di lavoro
   Connessione al progetto	La connessione Microsoft Entra Agent Identity creata in precedenza
   Approval	Richiedere l'approvazione per ogni chiamata mentre valuti l'integrazione
   Strumenti consentiti	Inizia solo con gli strumenti necessari per il flusso

4. Salvare la configurazione dell'agente.

5. Nelle istruzioni dell'agente, richiedi all'agente di creare una sessione, riutilizzare il suo browserSessionId, e chiudere la sessione quando il compito termina.

Un elenco minimo di strumenti per un flusso di navigazione orientato alla lettura è:

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

Aggiungi strumenti di interazione come browser_click o browser_type solo quando lo scenario lo richiede. Non abilitare browser_evaluate o browser_run_code per impostazione predefinita.

Testare il flusso della fonderia

Usa un prompt che indichi l'obiettivo e la necessità di pulizia. Per esempio:

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 l'agente richiede l'approvazione:

1. Verifica che l'etichetta del server corrisponda al server Playwright configurato.
2. Rivedi il nome dello strumento e tutti gli argomenti, in particolare URL, selettori, testo, dati caricati e codice.
3. Approva solo l'operazione prevista.
4. Verifica che la risposta finale si basi sul risultato della pagina.
5. Conferma che il flusso si chiama close_browser_session.

Per i campi di connessione attuali di Foundry, la gestione delle approvazioni, esempi di SDK e i limiti dei client, vedi Collega agenti agli endpoint server MCP.

Connettersi da Visual Studio Code

Visual Studio Code può scoprire la configurazione OAuth del server remoto e accedere con Microsoft Entra ID. La configurazione necessita solo dell'endpoint con ambito dell'area di lavoro.

1. In Visual Studio Code, esegui MCP: Open User Configuration dalla Palette dei comandi.
2. Aggiungi la seguente configurazione e sostituisci i segnaposto degli endpoint.

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

3. Avvia il server dall'editor di configurazione o esegui MCP: List Servers.
4. Quando richiesto, accedi con l'account Microsoft Entra che ha accesso allo spazio di lavoro Playwright.
5. Approva il permesso richiesto Playwright.Mcp.Tools se è richiesto il consenso per il tuo inquilino.
6. Controlla l'URL e la configurazione del server, poi conferma di fidarti del server.
7. Apri la chat e seleziona Configura strumenti. Abilita solo gli strumenti per il drammaturgo necessari per il compito.
8. Esegui il prompt di esempio dalla sezione Foundry precedente.
9. Esamina i messaggi di conferma degli strumenti e verifica che la sessione sia chiusa al termine.

Usa una configurazione utente quando la connessione è personale. Una configurazione di workspace che contiene solo l'endpoint può essere condivisa. Visual Studio Code memorizza in cache le credenziali OAuth in modo sicuro e può riutilizzarle durante la riconnessione.

Se l'autenticazione di Microsoft Entra non è disponibile nell'ambiente del client, configura un'x-api-keyintestazione con un input protetto, come descritto in Input di configurazione MCP. Non inserire mai direttamente il valore del workspace access-token in mcp.json.

Per posizioni di configurazione, input segreti, server trust e diagnostica, vedi Aggiungi e gestisci server MCP in Visual Studio Code e il riferimento di configurazione MCP.

Progettare un flusso di automazione agentica

Usa un ciclo osserva-agi-verifica invece di chiedere all'agente di eseguire una lunga sequenza senza controllare lo stato della pagina.

1. Crea: Chiama create_browser_session e mantieni il relativo browserSessionId.
2. Naviga: Chiama browser_navigate con un URL esplicito e approvato.
3. Nota: Richiama browser_find per una ricerca mirata o browser_snapshot per una panoramica più ampia dell'accessibilità.
4. Agire: Usa un riferimento snapshot o un selettore unico con uno strumento di interazione.
5. Aspetta: Chiamabrowser_wait_for per messaggi attesi, messaggi che spariscono o un ritardo limitato.
6. Verifica: Acquisisci un altro snapshot o ispeziona l'attività di console e rete.
7. Gestire i rami: Gestire una finestra di dialogo, cambiare scheda o caricare file solo quando lo stato della pagina lo richiede.
8. Cattura le prove: Chiama browser_take_screenshot se un risultato visivo è utile. Non usare screenshot per selezionare i target delle azioni.
9. Pulizia: Chiama close_browser_session in un percorso di pulizia di tipo finally.

Scegli obiettivi di azione stabile

Preferisci i riferimenti restituiti da browser_snapshot o browser_find. Descrivono elementi di pagina accessibili e riducono la dipendenza dal markup specifico dell'implementazione. Usa un selettore unico quando non è disponibile un riferimento di snapshot stabile.

Aggiorna lo snapshot dopo la navigazione o dopo un'azione di cambio pagina. Un target restituito in precedenza può non essere più valido quando la pagina viene nuovamente renderizzata.

Gestire i dialoghi in modo sicuro

Un'azione può restituire un dialog-opened risultato dopo aver già cambiato lo stato della pagina. Questo risultato non è un fallimento normale di un'azione.

1. Non ripetere l'azione originale.
2. Chiama browser_handle_dialog con accept impostato su true o false.
3. Per una finestra di dialogo di richiesta, includere promptText solo quando la si accetta.
4. Osserva di nuovo la pagina prima di continuare.

Gestire errori ambigui

Un timeout o una chiamata disconnessa non dimostrano che un'azione non abbia avuto effetto. Prima di riprovare un'operazione non idempotente come un clic, l'invio di un modulo, il caricamento o l'esecuzione del codice:

1. Chiama browser_snapshot, browser_find, o un altro strumento di osservazione se la sessione è ancora disponibile.
2. Determinare se il cambiamento di stato previsto sia avvenuto.
3. Riprova solo se ripetere l'azione è sicuro.
4. Se la sessione è scaduta, crea una nuova sessione e riavvia da uno stato dell'applicazione noto.

Informazioni di riferimento per gli strumenti

Tutti gli strumenti a livello di browser richiedono browserSessionId. I limiti di stringa e di raccolta mostrati qui sono i limiti attuali di anteprima.

Strumenti di sessione

Strumenti di navigazione e osservazione

Strumenti di interazione

Schede, file e strumenti di codice

Dopo ogni flusso di automazione, invoca close_browser_session con browserSessionId attivo.

Forma del campo del modulo

Ogni browser_fill_form campo ha questa forma:

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

Il valore della stringa per un campo può contenere al massimo 100 KiB di caratteri. name può contenere al massimo 1.024 caratteri e type al massimo 128 caratteri.

Forma del caricamento di file

Ogni browser_file_upload file usa questa forma:

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

mimeType è facoltativo e il valore predefinito è application/octet-stream.

Limiti di caricamento file

• Da 1 a 20 file per chiamata di strumento.
• Dimensione massima decodificata di 10 MiB per ogni file.
• Dimensione massima combinata decodificata di 50 MiB.
• Nome file massimo di 4.096 caratteri.
• Tipo MIME massimo di 1.024 caratteri.
• Sono necessari dati validi base64.

Forme degli strumenti JavaScript

Per browser_evaluate, passa un'espressione di funzione:

() => document.title

Quando si fornisce target, la funzione riceve l'elemento corrispondente:

element => element.textContent

Per browser_run_code, passare le istruzioni che costituiscono il corpo di una funzione asincrona il cui parametro page è una pagina di Playwright. Restituisci solo dati serializzabili in JSON e mantienili entro il limite di risposta inline.

Limiti e comportamento attuale

Le risposte vengono restituite in linea. Questa anteprima non rende disponibili le risorse MCP né uno spazio di archiviazione persistente per gli artefatti relativi a snapshot di grandi dimensioni, screenshot o download. Browser, sistema operativo, viewport, impostazioni locali e override dello user-agent non sono disponibili come parametri di creazione della sessione.

Gestione degli errori

Un errore dello strumento include un codice di errore stabile, un messaggio adatto al cliente, un valore retryable e informazioni di correlazione. Usa il valore restituito retryable come segnale primario, insieme agli effetti collaterali dell'operazione.

Risolvere i problemi comuni

Il client MCP segnala "Non autorizzato"

• Conferma che l'autenticazione tramite token di accesso sia abilitata per lo spazio di lavoro.
• Conferma che il token non sia scaduto o revocato.
• Usa il valore grezzo del token come valore di x-api-key. Non aggiungere un Bearer prefisso.
• Conferma che il token e l'endpoint appartengano allo stesso spazio di lavoro.
• Se hai copiato un segreto in modo errato, crea un nuovo token perché non puoi recuperare i valori esistenti dal portale.

Il cliente MCP riferisce Forbidden

• Conferma che l'utente associato al token abbia ancora il permesso di creare sessioni del browser.
• Usa la stessa connessione o token di progetto per tutte le chiamate in una sessione browser.
• Non trasferire browserSessionId tra utenti, agenti che utilizzano credenziali diverse o aree di lavoro.

Gli strumenti non vengono scoperti

• Verifica l'endpoint completo, compreso /playwrightworkspaces/<workspace-id>/mcp.
• Verifica che la regione endpoint corrisponda alla regione dello spazio di lavoro.
• Conferma che il client utilizza un trasporto MCP su HTTP e invia x-api-key durante il rilevamento e le chiamate di strumenti.
• In Visual Studio Code, esegui MCP: List Servers, seleziona il server e poi seleziona Mostra Output.
• Riavvia la connessione MCP o resetti gli strumenti nella cache dopo aver cambiato endpoint.

L'agente non chiama uno strumento browser

• Dì esplicitamente all'agente di usare il server MCP configurato di Playwright.
• Verifica che lo strumento richiesto compaia nella lista degli strumenti abilitati o consentiti del cliente.
• Includere il ciclo di vita creazione-utilizzo-chiusura nelle istruzioni dell'agente.
• Usa un primo compito focalizzato con un solo obiettivo di navigazione e un risultato atteso.

Un bersaglio non funziona più

La pagina potrebbe essere stata navigata o renderizzata di nuovo. Richiama browser_snapshot o browser_find e usa un riferimento corrente. Evita selettori legati alle classi generate o che cambino la struttura dei documenti.

Uno strumento con tempi esauriti

Non dare per scontato che l'azione sia fallita senza cambiare stato. Se la sessione è attiva, ispeziona la pagina corrente prima di riprovare. Se la sessione è scaduta, crea una nuova sessione e riporta l'applicazione a uno stato noto.

Uno screenshot è troppo grande

Usa type: "jpeg", cattura solo la viewport, oppure fornisci un bersaglio per uno screenshot a livello elementale. Da usare browser_snapshot quando l'obiettivo è identificare un elemento piuttosto che preservare le prove visive.

La sessione è terminata durante un flusso

Crea una nuova sessione del browser. Le sessioni non si riconnettono in seguito alla perdita di connessione del browser, alla perdita del proprietario del servizio, alla chiusura esplicita o alla pulizia per inattività. Progetta il flusso in modo che possa riavviarsi da un URL e uno stato dell'applicazione noti.

Raccomandazioni sulla sicurezza

• Consentire solo gli strumenti richiesti dal compito dell'agente.
• Richiedi l'approvazione umana per gli strumenti di modifica dello stato, dei file e del codice.
• Considera il contenuto della pagina, gli snapshot di accessibilità, l'output della console e l'output di rete come non affidabili. Una pagina può contenere istruzioni per l'iniezione di prompt.
• Tieni separate le istruzioni di sistema dal testo derivato dalla pagina. Non lasciare che il contenuto delle pagine cambi le politiche di sicurezza o le regole di approvazione.
• Validare gli URL di destinazione rispetto a una lista di permessi quando si automatizzano applicazioni sensibili.
• Rivedi testo, selettori, contenuti del file e codice prima di approvare una chiamata a uno strumento.
• Non usare token di accesso in prompt, file sorgente, screenshot, file caricati o frammenti JavaScript.
• Usa token di breve durata, ruotali regolarmente e revoca le connessioni inutilizzate.
• Usa uno spazio di lavoro dedicato e un'identità con privilegi minimi per ogni confine di attendibilità.
• Registra le approvazioni e i nomi degli strumenti per l'audit, ma non registrare credenziali, contenuti caricati o dati sensibili delle pagine.

Disponibilità a livello regionale

Spazi di lavoro Playwright è disponibile nelle seguenti regioni Azure:

Contenuti correlati

• Gestisci i token di accesso allo spazio di lavoro
• Gestire l'accesso a uno spazio di lavoro per drammaturghi
• Connetti gli agenti Microsoft Foundry agli endpoint server MCP
• Aggiungi e gestisci server MCP in Visual Studio Code
• Documentazione del protocollo di contesto del modello