Automatiseer browsers met de Playwright-werkruimten externe MCP-server

De Playwright-werkruimten remote MCP-server biedt AI-agenten een beheerde remote browser en een set browserautomatiseringstools. Een agent kan een browsersessie openen, pagina's navigeren, elementen vinden en ermee interacteren, browseractiviteit inspecteren, screenshots maken en de sessie afsluiten. Je hoeft Playwright of een browser niet te installeren in de agent-omgeving.

De server gebruikt Model Context Protocol over Streamable HTTP. Het ondersteunt Microsoft Entra ID-authenticatie en toegangstokens voor werkruimtes. Het werkt met externe MCP-clients, waaronder Microsoft Foundry Agent Service en Visual Studio Code.

In dit artikel leert u het volgende:

• Bouw het MCP-eindpunt voor een Playwright-werkruimte.
• Authenticeer door gebruik te maken van een Microsoft Entra ID of een toegangstoken voor de werkruimte.
• Verbind de server met Microsoft Foundry Agent Service of Visual Studio Code.
• Voer volledige agentische browserautomatiseringsstromen uit.
• Selecteer en gebruik veilig de beschikbare browsertools.
• Behandel sessievervaldatum, time-outs en andere veelvoorkomende fouten.

Prerequisites

Voordat u begint, moet u ervoor zorgen dat u het volgende hebt:

• Een Azure-account met een actief abonnement.
• Een Playwright-werkruimte die toegang heeft tot de remote MCP-preview.
• De werkruimte-ID en Azure-regio van de werkruimte.
• Een identiteit met toestemming om browsersessies in de werkruimte te maken en te gebruiken.
• Voor Microsoft Foundry, een Foundry-project en toestemming om projectverbindingen te maken en agents te configureren.
• Voor Visual Studio Code, een recente versie van Visual Studio Code met toegang tot GitHub Copilot en waarbij MCP-ondersteuning is ingeschakeld.

Een verificatiemethode kiezen

Gebruik Microsoft Entra ID wanneer je MCP-client OAuth of managed identity ondersteunt. De externe MCP-server gebruikt deze resource identifier en gedelegeerde scope:

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

De server publiceert OAuth protected-resource metadata. Clients die OAuth-detectie ondersteunen, waaronder Visual Studio Code, kunnen de autorisatieserver en de vereiste scope afleiden uit het werkruimtespecifieke MCP-eindpunt. De ingelogde identiteit moet toegang hebben tot de Playwright-werkruimte via Azure role-based access control (RBAC).

Maak een workspace-toegangstoken aan voor compatibiliteit

Sla deze sectie over wanneer je Microsoft Entra ID gebruikt. Als toegangstokenauthenticatie nog niet is ingeschakeld voor de werkruimte:

1. Meld u aan bij het Azure-portaal.
2. Open je Playwright-werkruimte.
3. Selecteer onder InstellingenToegangsbeheer.
4. Activeer Playwright Service Access Token.
5. Selecteer Het token genereren.
6. Voer een naam en vervaldatum in en genereer vervolgens de token.
7. Kopieer het token onmiddellijk. Je kunt de waarde later niet meer terughalen.

Sla het token op in een beheerde geheime opslag of in de beveiligde credentialfaciliteit die door je MCP-client wordt aangeboden. Trek het in en vervang het als het mogelijk blootgesteld is. Om een toegangstoken voor de werkruimte aan te maken, zie Beheren werkruimtetoegangstokens.

Bouw het externe MCP-eindpunt

Het eindpunt is beperkt tot één werkruimte en regio:

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

Replace:

• <region> met de Azure-regio van de werkruimte.
• <workspace-id> met de werkruimte-id die wordt weergegeven in de Azure-portal.

Voorbeeld:

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

De waarde in de x-api-key requestheader moet een toegangstoken zijn dat is aangemaakt voor dezelfde werkruimte als <workspace-id>. Gebruik het eindpunt voor de regio van de werkruimte, niet de regio die het dichtst bij de MCP-client ligt.

Begrijp de browsersessiecyclus

Een browserautomatiseringsflow bestaat uit drie fasen:

1. Roep create_browser_session aan. Het resultaat bevat een ondoorzichtige browserSessionId en kan een live-view URL bevatten.
2. Geef dat browserSessionId door aan elke browsertool die in de flow wordt gebruikt.
3. Roep close_browser_session een opruimstap in, zelfs als de stroom faalt.

De MCP HTTP-transport bewaart de browserstatus niet. De browserSessionId identificeert de externe browser bij afzonderlijke toolaanroepen. Houd deze privé en gebruik deze alleen in combinatie met de werkruimte en identiteit waarmee deze is gemaakt.

Het huidige previewgedrag omvat deze beperkingen:

• Een sessie behoort toe aan de maker en kan niet gedeeld worden met een andere directeur.
• Oproepen voor één sessie worden in volgorde verwerkt. Voer geen gelijktijdige acties uit tegen dezelfde sessie.
• Een inactieve sessie wordt na 15 minuten opgeruimd. Expliciete schoonmaak is vereist.
• Een gesloten of verlopen sessie kan niet worden heropend.
• Verbindingsverlies beëindigt de sessie. Maak een nieuwe sessie aan om door te gaan.
• Een resultaat kan een liveViewUrlbevat. De beschikbaarheid van live view hangt af van de sessie.

Verbind via Microsoft Foundry Agent Service

Gebruik Microsoft Entra Agent Identity om de agent te authenticeren met de beheerde identiteit van het Foundry-project. Verleen die identiteit toegang tot de Playwright-werkruimte voordat je de MCP-tool verbindt.

De projectverbinding maken

1. Open je project in het Microsoft Foundry-portaal.
2. Open de managementervaring van het project en selecteer vervolgens Verbonden bronnen.
3. Maak een verbinding aan voor een externe MCP-server.
4. Voer een beschrijvende verbindingsnaam in, zoals playwright-mcp-connection.
5. Selecteer Microsoft Entra Agent Identity als authenticatiemethode.
6. Vul https://mcp.playwright.microsoft.com in als doelgroep.
7. Sla de verbinding op.

De beheerde identiteit van het project moet een rol hebben die browsersessie-operaties op de doel-Playwright-werkruimte toestaat. Gebruik geen identiteitstoken van het ene project als gedeeld geheim in een ander project.

Als de Microsoft Entra Agent Identity niet beschikbaar is voor de client of omgeving, maak dan een Custom Keys-verbinding aan met een sleutel genaamd x-api-key en een workspace access token als waarde.

Voeg de remote MCP-tool toe

1. Maak een agent aan of open er een in het Foundry-portaal.

2. Voeg een remote MCP-server of MCP-tool toe.

3. Gebruik de volgende instellingen:

   Setting	Value
   Serverlabel	Een uniek label, zoals playwrightWorkspace
   Server-URL	Het externe MCP-eindpunt met werkruimtebereik
   Projectverbinding	De eerder aangemaakte Microsoft Entra Agent Identity-verbinding
   Approval	Vraag goedkeuring voor elk gesprek bij het evalueren van de integratie
   Toegestane gereedschappen	Begin alleen met de tools die nodig zijn voor de flow

4. Sla de agentconfiguratie op.

5. In de agentinstructies moet de agent één sessie aanmaken, de , browserSessionIdhergebruiken en de sessie sluiten wanneer de taak is voltooid.

Een minimale lijst met toegestane tools voor een op lezen gerichte navigatieflow is:

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

Voeg interactietools toe, zoals, browser_click of browser_type alleen wanneer het scenario dat vereist. Schakel browser_run_code of browser_evaluate niet standaard in.

Test de gieterijstroom

Gebruik een prompt waarin het doel en de opruimvereiste worden vermeld. Voorbeeld:

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.

Wanneer de makelaar goedkeuring aanvraagt:

1. Controleer of het serverlabel de geconfigureerde Playwright-server is.
2. Bekijk de toolnaam en alle argumenten, vooral URL's, selectoren, tekst, geüploade data en code.
3. Keur alleen de verwachte operatie goed.
4. Controleer of het uiteindelijke antwoord gebaseerd is op het resultaat van de pagina.
5. Bevestig dat de flow close_browser_session heet.

Voor de huidige Foundry-verbindingsvelden, goedkeuringsafhandeling, SDK-voorbeelden en clientlimieten, zie Connect agents to MCP server endpoints.

Verbinding maken vanuit Visual Studio Code

Visual Studio Code kan de OAuth-configuratie van de externe server ontdekken en je inloggen met Microsoft Entra ID. De configuratie heeft alleen het werkruimtegebonden eindpunt nodig.

1. Voer in Visual Studio Code MCP: Open User Configuration uit vanuit het Command Palette.
2. Voeg de volgende configuratie toe en vervang de placeholders voor de eindpunten.

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

3. Start de server vanuit de configuratie-editor of voer MCP: List Servers uit.
4. Wanneer daarom wordt gevraagd, log je in met het Microsoft Entra-account dat toegang heeft tot de Playwright-werkruimte.
5. Keur de gevraagde Playwright.Mcp.Tools toestemming goed als toestemming vereist is voor je huurder.
6. Bekijk de server-URL en configuratie, en bevestig vervolgens dat je de server vertrouwt.
7. Open Chat en selecteer Tools configureren. Schakel alleen de Playwright-tools in die voor de taak nodig zijn.
8. Voer de voorbeeldprompt uit vanuit het voorgaande Foundry-gedeelte.
9. Bekijk de bevestigingen van de tool en controleer dat de sessie aan het einde is gesloten.

Gebruik een gebruikersconfiguratie wanneer de verbinding persoonlijk is. Een werkruimteconfiguratie die alleen het eindpunt bevat, kan worden gedeeld. Visual Studio Code cachet de OAuth-inloggegevens veilig en kan ze hergebruiken bij het opnieuw verbinden.

Als Microsoft Entra-authenticatie niet beschikbaar is in de clientomgeving, configureer dan een x-api-key header met een beschermde invoer zoals beschreven in MCP-configuratie-invoer. Plaats nooit de workspace access-token waarde direct in mcp.json.

Voor configuratielocaties, geheime invoer, serververtrouwen en diagnostiek, zie Add and manage MCP-servers in Visual Studio Code en de MCP-configuratiereferentie.

Ontwerp een agentische automatiseringsstroom

Gebruik een observe-act-verify lus in plaats van de agent te vragen een lange sequentie uit te voeren zonder de paginastatus te controleren.

1. Aanmaken: Roep create_browser_session aan en bewaar de browserSessionId.
2. Navigeren: Bel browser_navigate met een expliciete, goedgekeurde URL.
3. Let op: Roep browser_find op tot een gerichte zoekopdracht of browser_snapshot een bredere toegankelijkheidsweergave.
4. Handelen: Gebruik een snapshotreferentie of unieke selector met een interactietool.
5. Wacht: Belbrowser_wait_for voor verwachte sms, verdwijnende sms of een beperkte vertraging.
6. Verifieer: Maak een andere snapshot of inspecteer console- en netwerkactiviteit.
7. Verwerk vertakkingen: Verwerk een dialoogvenster, wissel tussen tabbladen of upload alleen bestanden wanneer de status van de pagina dat vereist.
8. Bewijs vastleggen: Bel browser_take_screenshot als een visueel resultaat nuttig is. Gebruik geen screenshots om actiedoelen te selecteren.
9. Opruimen: Roep close_browser_session aan in een cleanup-pad in finally-stijl.

Kies stabiele actiedoelen

Geef voorkeur aan referenties die worden teruggegeven door browser_snapshot of browser_find. Ze beschrijven toegankelijke pagina-elementen en verminderen de afhankelijkheid van implementatie-specifieke markup. Gebruik een unieke selector wanneer er geen stabiele snapshotreferentie beschikbaar is.

Ververs de snapshot na navigatie of na een wijziging van de pagina. Een eerder teruggegeven doel kan verouderd raken wanneer de pagina opnieuw wordt weergegeven.

Behandel dialoogvensters veilig

Een actie kan een dialog-opened uitkomst teruggeven nadat de paginastatus al is veranderd. Dit resultaat is geen normale mislukking van een actie.

1. Herhaal de oorspronkelijke handeling niet.
2. Bel browser_handle_dialog met accept ingesteld op true of false.
3. Voor een promptdialoog, promptText vermeld alleen wanneer je het accepteert.
4. Bekijk de pagina opnieuw voordat je verdergaat.

Ambigue fouten afhandelen

Een timeout of een beller van wie de verbinding is verbroken, bewijst niet dat een actie geen effect heeft gehad. Voordat je een niet-idempotente bewerking opnieuw probeert, zoals een klik, formulierindiening, upload of code-uitvoering:

1. Gebruik browser_snapshot, browser_find of een andere observatietool indien de sessie nog steeds beschikbaar is.
2. Bepaal of de verwachte toestandsverandering heeft plaatsgevonden.
3. Probeer het alleen opnieuw als het herhalen van de actie veilig is.
4. Als de sessie is verlopen, maak dan een nieuwe sessie aan en start opnieuw vanaf een bekende applicatiestatus.

Toolreferentie

Alle browsergebonden tools vereisen browserSessionId. De hier getoonde string- en collectiegrenzen zijn de huidige previewlimieten.

Sessiehulpmiddelen

Navigatie- en observatiehulpmiddelen

Hulpprogramma's voor interactie

Tabbladen, bestanden en codehulpmiddelen

Roep na elke automatiseringsworkflow de close_browser_session aan met de actieve browserSessionId.

Formveldvorm

Elk browser_fill_form veld heeft deze vorm:

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

De stringwaarde voor een veld kan maximaal 100 KiB aan tekens bevatten. name kan maximaal 1.024 tekens bevatten, en type maximaal 128 tekens.

Vorm voor bestandsupload

Elke browser_file_upload map gebruikt deze vorm:

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

mimeType is optioneel en wordt standaard ingesteld op application/octet-stream.

Uploadlimieten voor bestanden

• 1 tot 20 bestanden per toolcall.
• 10 MiB maximale gedecodeerde grootte voor elk bestand.
• Maximale gecombineerde gedecodeerde grootte: 50 MiB.
• Maximale bestandsnaam van 4.096 tekens.
• 1.024 tekens maximaal MIME-type.
• Geldige base64-gegevens zijn vereist.

JavaScript-toolvormen

Voor browser_evaluate, geef een functie-expressie door:

() => document.title

Wanneer u geeft target, ontvangt de functie het bijbehorende element:

element => element.textContent

Voor browser_run_code, geef pass-instructies door die de hoofdtekst vormen van een asynchrone functie, waarbij de parameter page een Playwright-pagina is. Geef alleen JSON-serialiseerbare data terug en houd deze binnen de inline responslimiet.

Limieten en huidig gedrag

Reacties worden inline teruggestuurd. Deze preview biedt geen toegang tot MCP-bronnen of persistente opslag van artefacten voor grote snapshots, screenshots of downloads. Browser-, besturingssysteem-, viewport-, landinstellings- en user-agentoverrides zijn niet beschikbaar als parameters voor het maken van een sessie.

Foutafhandeling

Een toolfout omvat een stabiele foutcode, een klantveilig bericht, een retryable waarde en correlatie-informatie. Gebruik de teruggegeven retryable waarde als primair signaal, samen met de neveneffecten van de bewerking.

Veelvoorkomende problemen oplossen

De MCP-client meldt Ongeautoriseerd

• Bevestig dat toegangstokenauthenticatie is ingeschakeld voor de werkruimte.
• Bevestig dat de token niet verlopen of ingetrokken is.
• Gebruik de ruwe tokenwaarde als waarde x-api-key . Voeg geen voorvoegsel toe.Bearer
• Bevestig dat het token en het eindpunt bij dezelfde werkruimte horen.
• Als je een secret verkeerd hebt gekopieerd, maak dan een nieuw token aan omdat je bestaande waarden niet uit het portaal kunt terughalen.

De MCP-client meldt 'Toegang geweigerd'

• Bevestig dat de gebruiker die aan het token is gekoppeld nog steeds toestemming heeft om browsersessies aan te maken.
• Gebruik dezelfde projectverbinding of token voor alle aanroepen in één browsersessie.
• Deel geen browserSessionId tussen gebruikers, agenten die verschillende inloggegevens gebruiken, of werkruimtes.

Hulpmiddelen worden niet gevonden

• Controleer het volledige eindpunt, inclusief /playwrightworkspaces/<workspace-id>/mcp.
• Controleer of de eindpuntregio overeenkomt met de werkruimteregio.
• Bevestig dat de client een HTTP MCP-transport gebruikt en verzendt x-api-key tijdens discovery en toolcalls.
• Voer in Visual Studio Code MCP: List Servers uit, selecteer de server en selecteer vervolgens Show Output.
• Herstart de MCP-verbinding of reset gecachede tools nadat je het eindpunt hebt gewijzigd.

De agent roept geen browsertool aan

• Zeg expliciet tegen de agent dat hij de geconfigureerde Playwright MCP-server moet gebruiken.
• Controleer of de benodigde tool verschijnt in de lijst met ingeschakelde of toegestane tools van de klant.
• Neem de levenscyclus van creëren-gebruiken-sluiten op in de agentinstructies.
• Gebruik een gerichte eerste taak met één navigatiedoel en één verwacht resultaat.

Een doel werkt niet meer

Er kan naar een andere pagina zijn genavigeerd of de pagina is mogelijk opnieuw gerenderd. Bel browser_snapshot of browser_find opnieuw en gebruik een actuele referentie. Vermijd selectors die gekoppeld zijn aan gegenereerde klassen of het veranderen van de documentstructuur.

Een tool die uitliep

Ga er niet van uit dat de actie mislukte zonder van toestand te veranderen. Als de sessie actief is, inspecteer dan de huidige pagina voordat je het opnieuw probeert. Als de sessie is verlopen, maak je een nieuwe sessie aan en stuur je de applicatie terug naar een bekende staat.

Een screenshot is te groot

Gebruik type: "jpeg", leg alleen het viewport vast, of geef een doel voor een screenshot op elementniveau. Gebruik browser_snapshot wanneer het doel is om een element te identificeren in plaats van visueel bewijs te bewaren.

De sessie liep af tijdens een flow

Maak een nieuwe browsersessie aan. Sessies worden niet opnieuw verbonden na verlies van de browserverbinding, verlies van service-eigenaar, expliciete sluiting of inactieve opruiming. Ontwerp de flow zodat hij kan herstarten vanaf een bekende URL en applicatiestatus.

Aanbevelingen voor beveiliging

• Sta alleen de tools toe die door de taak van de agent worden vereist.
• Menselijke goedkeuring vereisen voor statuswijzigende tools, bestandstools en codetools.
• Behandel pagina-inhoud, toegankelijkheidssnapshots, console-output en netwerk-output als onbetrouwbaar. Een pagina kan prompt-injectie-instructies bevatten.
• Houd systeeminstructies gescheiden van pagina-afgeleide tekst. Laat de inhoud van de pagina het beveiligingsbeleid of de goedkeuringsregels niet veranderen.
• Valideer bestemmings-URL's aan de hand van een toestemmingslijst bij het automatiseren van gevoelige applicaties.
• Bekijk tekst, selectors, bestandsinhoud en code voordat je een toolcall goedkeurt.
• Gebruik geen toegangstokens in prompts, bronbestanden, screenshots, geüploade bestanden of JavaScript-fragmenten.
• Gebruik kortstondige tokens, roteer ze regelmatig en trek ongebruikte verbindingen in.
• Gebruik voor elke vertrouwensgrens een afzonderlijke werkruimte en een identiteit met minimale bevoegdheden.
• Log goedkeuringen en toolnamen voor audit, maar log geen inloggegevens, geüploade inhoud of gevoelige paginagegevens.

Regionale beschikbaarheid

Playwright-werkruimten is beschikbaar in de volgende Azure-regio's:

Verwante onderwerpen

• Beheer toegangstokens voor werkruimtes
• Beheer toegang tot een Playwright-werkruimte
• Verbind Microsoft Foundry-agenten met MCP-servereindpunten
• Voeg MCP-servers toe en beheer in Visual Studio Code
• Model Context Protocol Documentatie