Automatisez les navigateurs avec le serveur MCP distant Espaces de travail pour les dramaturges

Le serveur MCP distant Espaces de travail pour les dramaturges offre aux agents IA un navigateur distant géré et un ensemble d’outils d’automatisation des navigateurs. Un agent peut ouvrir une session de navigateur, naviguer dans les pages, trouver et interagir avec des éléments, inspecter l’activité du navigateur, prendre des captures d’écran et fermer la session. Vous n’avez pas besoin d’installer Playwright ou un navigateur dans l’environnement de l’agent.

Le serveur utilise le protocole de contexte modèle sur HTTP streamable. Il prend en charge l’authentification Microsoft Entra ID et les jetons d’accès à l’espace de travail. Il fonctionne avec des clients MCP distants, y compris Microsoft Foundry Agent Service et Visual Studio Code.

Dans cet article, vous allez apprendre à :

• Construis le point de terminaison MCP pour un espace de travail Playwright.
• Authentifiez en utilisant Microsoft Entra ID ou un jeton d’accès à l’espace de travail.
• Connectez le serveur à Microsoft Foundry Agent Service ou à Visual Studio Code.
• Exécutez des flux complets d’automatisation de navigateur agentique.
• Sélectionnez et utilisez en toute sécurité les outils de navigateur disponibles.
• Gérez l’expiration des sessions, les délais d’attente et d’autres erreurs courantes.

Conditions préalables

Avant de commencer, assurez-vous d’avoir :

• Un compte Azure avec un abonnement actif.
• Un espace de travail pour dramaturges qui a accès à l’aperçu distant du MCP.
• L’ID de l’espace de travail et la région Azure de l’espace de travail.
• Une identité avec la permission de créer et d’utiliser des sessions de navigateur dans l’espace de travail.
• Pour Microsoft Foundry, un projet Foundry et les autorisations nécessaires pour créer des connexions de projet et configurer des agents.
• Pour Visual Studio Code, une version actuelle de Visual Studio Code avec accès à GitHub Copilot et support MCP activé.

Choisir une méthode d’authentification

Utilisez Microsoft Entra ID lorsque votre client MCP prend en charge OAuth ou identité managée. Le serveur MCP distant utilise cet identifiant de ressource et cette portée déléguée :

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

Le serveur publie les métadonnées OAuth à ressource protégée. Les clients qui prennent en charge la découverte OAuth, y compris Visual Studio Code, peuvent découvrir le serveur d’autorisation et la portée requise depuis le point de terminaison MCP à portée de l’espace de travail. L’identité connectée doit avoir accès à l’espace de travail Playwright via le contrôle d’accès basé sur les rôles (RBAC) Azure.

Créer un jeton d’accès à l’espace de travail pour la compatibilité

Passez cette section lorsque vous utilisez Microsoft Entra ID. Si l’authentification par jeton d’accès n’est pas déjà activée pour l’espace de travail :

1. Connectez-vous au portail Azure.
2. Ouvrez votre espace de travail pour dramaturge.
3. Dans Paramètres, sélectionnez Gestion d’accès.
4. Activez le jeton d’accès au service Playwright.
5. Sélectionnez Générer un jeton.
6. Saisissez un nom et une date d’expiration, puis générez le jeton.
7. Copiez immédiatement le jeton. Vous ne pourrez pas en récupérer la valeur plus tard.

Stockez le jeton dans un magasin secret géré ou dans la fonction de crédibilité sécurisée fournie par votre client MCP. Révoquez-le et remplacez-le s’il a peut-être été exposé. Pour créer un jeton d’accès à l’espace de travail, voir Gérer les jetons d’accès à l’espace de travail.

Construisez le point de terminaison MCP distant

Le point de terminaison est limité à un seul espace de travail et région :

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

Remplacez :

• <region> avec la région Azure de l’espace de travail.
• <workspace-id> avec l’identifiant de l’espace de travail affiché dans le portail Azure.

Par exemple:

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

La valeur dans l’en-tête x-api-key de requête doit être un jeton d’accès créé pour le même espace de travail que <workspace-id>. Utilisez le point de terminaison pour la région de l’espace de travail, pas la région la plus proche du client MCP.

Comprendre le cycle de vie des sessions de navigateur

Un flux d’automatisation d’un navigateur comporte trois étapes :

1. Appelez create_browser_session. Le résultat contient une URL opaque browserSessionId et pourrait contenir une URL en vue réelle.
2. Transmettez ce paramètre browserSessionId à chaque outil du navigateur utilisé dans le flux.
3. Appelez close_browser_session lors d’une étape de nettoyage, même si le flux échoue.

Le transport HTTP MCP ne préserve pas l’état du navigateur. Il browserSessionId identifie le navigateur distant via des appels d’outils distincts. Gardez-le privé et utilisez-le uniquement avec l’espace de travail et l’identité qui l’ont créé.

Le comportement actuel de l’aperçu comporte les contraintes suivantes :

• Une session appartient à son créateur et ne peut pas être partagée avec un autre principal.
• Les appels pour une session sont traités dans l’ordre. Ne prenez pas d’actions concurrentes contre la même session.
• Une séance inactive est terminée après 15 minutes. Un nettoyage explicite est nécessaire.
• Une session fermée ou expirée ne peut pas être rouverte.
• La perte de connexion met fin à la session. Créez une nouvelle session pour continuer.
• Un résultat peut contenir un liveViewUrl. La disponibilité de la vue en direct dépend de la session.

Connectez-vous depuis le service Microsoft Foundry Agent Service

Utilisez Microsoft Entra Agent Identity pour authentifier l'agent avec l'identité gérée du projet Foundry. Accordez à cette identité l’accès à l’espace de travail Playwright avant de connecter l’outil MCP.

Créer la connexion au projet

1. Ouvrez votre projet dans le portail Microsoft Foundry.
2. Ouvre l’expérience de gestion du projet, puis sélectionne Ressources connectées.
3. Créez une connexion pour un serveur MCP distant.
4. Entrez un nom de connexion descriptive, tel que playwright-mcp-connection.
5. Sélectionnez l’identité de l’agent Microsoft Entra comme méthode d’authentification.
6. Saisissez https://mcp.playwright.microsoft.com comme audience.
7. Enregistrez la connexion.

L’identité gérée du projet doit disposer d’un rôle qui autorise les opérations de session de navigateur sur l’espace de travail Playwright cible. N’utilisez pas un token d’identité d’un projet comme secret partagé dans un autre projet.

Si Microsoft Entra Agent Identity n'est pas disponible pour le client ou l'environnement, créez une connexion de clés personnalisées avec une clé nommée x-api-key et un jeton d'accès à l'espace de travail comme valeur.

Ajouter l’outil MCP à distance

1. Créez ou ouvrez un agent dans le portail Foundry.

2. Ajoutez un serveur MCP distant ou un outil MCP.

3. Utilisez les paramètres suivants :

   Setting	Value
   Étiquette serveur	Une étiquette unique, telle que playwrightWorkspace
   URL du serveur	Le point de terminaison MCP distant associé à l’espace de travail
   Connexion de projet	La connexion Microsoft Entra Agent Identity créée précédemment
   Approbation	Exigez l’approbation de chaque appel lors de l’évaluation de l’intégration
   Outils autorisés	Commencez avec uniquement les outils nécessaires au flux

4. Enregistrez la configuration de l’agent.

5. Dans les instructions de l’agent, demandez à l’agent de créer une session, de réutiliser son browserSessionId, et de fermer la session à la fin de la tâche.

Une liste minimale d’outils permettant un flux de navigation orienté lecture est :

create_browser_session
browser_navigate
browser_snapshot
browser_find
browser_take_screenshot
close_browser_session

Ajoutez des outils d’interaction, comme browser_click ou browser_type seulement lorsque le scénario les exige. N’activez pas browser_evaluate ou browser_run_code par défaut.

Tester l’écoulement de la fonderie

Utilisez un prompt indiquant l’objectif et les exigences de nettoyage. Par exemple:

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.

Lorsque l’agent demande l’approbation :

1. Vérifiez que l’étiquette serveur est celle configurée de Playwright.
2. Examinez le nom de l’outil et tous les arguments, en particulier les URL, les sélecteurs, le texte, les données téléchargées et le code.
3. Approuvez uniquement l’opération attendue.
4. Vérifiez que la réponse finale est basée sur le résultat de la page.
5. Confirmez que le flux s'appelle close_browser_session.

Pour les champs de connexion Foundry actuels, la gestion des approbations, les exemples de SDK et les limites du client, consultez Connecter des agents à des points de terminaison de serveur MCP.

Se connecter à partir de Visual Studio Code

Visual Studio Code peut découvrir la configuration OAuth du serveur distant et vous connecter avec Microsoft Entra ID. La configuration nécessite uniquement le point de terminaison limité à l’espace de travail.

1. Dans Visual Studio Code, exécutez MCP : Open User Configuration depuis la palette de commandes.
2. Ajoutez la configuration suivante et remplacez les placeholders du point de terminaison.

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

3. Lance le serveur depuis l’éditeur de configuration ou exécute MCP : List Servers.
4. Lorsque vous y êtes invité, connectez-vous avec le compte Microsoft Entra ayant accès à l’espace de travail Playwright.
5. Approuvez l’autorisation demandée Playwright.Mcp.Tools si votre locataire demande un consentement.
6. Examinez l’URL et la configuration du serveur, puis confirmez que vous faites confiance au serveur.
7. Ouvre le chat et sélectionne Configurer les outils. Activez uniquement les outils de dramaturge nécessaires à la tâche.
8. Exécutez le prompt d’exemple de la section Foundry précédente.
9. Vérifiez les confirmations des outils et vérifiez que la session est close à la fin.

Utilisez une configuration utilisateur lorsque la connexion est personnelle. Une configuration d’espace de travail ne contenant que le point de terminaison peut être partagée. Visual Studio Code met en cache les identifiants OAuth de manière sécurisée et peut les réutiliser lors de la reconnexion.

Si l'authentification Microsoft Entra n'est pas disponible dans l'environnement client, configurez un x-api-key en-tête avec une entrée protégée comme décrit dans les entrées de configuration MCP. Ne mettez jamais directement la valeur du token d’accès à l’espace de travail dans mcp.json.

Pour les emplacements de configuration, les entrées secrètes, la confiance des serveurs et les diagnostics, voir Ajouter et gérer les serveurs MCP dans Visual Studio Code et la référence de configuration MCP.

Concevoir un flux d’automatisation agentique

Utilisez une boucle observer-agir-vérifier au lieu de demander à l’agent d’effectuer une longue séquence sans vérifier l’état de la page.

1. Créer : Appeler create_browser_session et conserver son browserSessionId.
2. Naviguer : Appelez browser_navigate avec une URL explicite et approuvée.
3. Observez : Demandez browser_find une recherche ciblée ou browser_snapshot une vision plus large de l’accessibilité.
4. Acte : Utilisez une référence instantanée ou un sélecteur unique avec un outil d’interaction.
5. Attendez : Appelezbrowser_wait_for pour un message attendu, un texte disparu ou un délai limité.
6. Vérifier : Capturez un autre instantané ou inspectez l’activité de la console et du réseau.
7. Gérer les branches : Gérer une boîte de dialogue, changer d’onglet ou télécharger des fichiers uniquement lorsque l’état de la page l’exige.
8. Capturez les preuves : Appelez browser_take_screenshot si un résultat visuel vous est utile. N’utilisez pas de captures d’écran pour sélectionner des cibles d’action.
9. Nettoyage : Appelez close_browser_session dans un chemin de nettoyage de type final.

Choisissez des cibles d’action stable

Préfère références retournées par browser_snapshot ou browser_find. Ils décrivent des éléments de page accessibles et réduisent la dépendance au balisage spécifique à l’implémentation. Utilisez un sélecteur unique lorsqu’une référence d’instantané stable n’est pas disponible.

Rafraîchissez l’instantané après la navigation ou après une action de changement de page. Une cible retournée précédemment peut devenir obsolète lorsque la page se réaffiche.

Gérer les dialogues en toute sécurité

Une action peut renvoyer un dialog-opened résultat après avoir déjà changé l’état de la page. Ce résultat n’est pas un échec d’action normal.

1. Ne répétez pas l’action initiale.
2. Appelez browser_handle_dialog avec accept défini sur true ou false.
3. Dans une boîte de dialogue d’invite, incluez promptText uniquement lorsque vous l’acceptez.
4. Regardez la page à nouveau avant de continuer.

Gérer les défaillances ambiguës

Un dépassement de délai ou un appelant déconnecté ne signifie pas qu’une action est restée sans effet. Avant de recommencer une opération non idempotente telle qu’un clic, une soumission de formulaire, un téléchargement ou une exécution de code :

1. Appelez browser_snapshot, browser_find, ou un autre outil d’observation si la session est toujours disponible.
2. Déterminez si le changement d’état attendu s’est produit.
3. Réessayez seulement si répéter l’action est sûr.
4. Si la session a expiré, créer une nouvelle session et redémarrer depuis un état d’application connu.

Informations de référence sur l’outil

Tous les outils à portée de navigateur nécessitent browserSessionId. Les limites de chaînes et de collections présentées ici sont les limites actuelles de prévisualisation.

Outils de session

Outils de navigation et d’observation

Outils d’interaction

Onglets, fichiers et outils de code

Après chaque workflow d’automatisation, appelez le close_browser_session avec le browserSessionId actif.

Forme du champ de formulaire

Chaque browser_fill_form champ a cette forme :

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

La valeur de la chaîne d’un champ peut contenir au maximum 100 KiB de caractères. name peut contenir au maximum 1 024 caractères, et type peut contenir au maximum 128 caractères.

Forme d’envoi du fichier

Chaque browser_file_upload fichier utilise cette forme :

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

mimeType est facultatif et est défini par défaut sur application/octet-stream.

Limites de téléchargement de fichiers

• 1 à 20 fichiers par appel d’outil.
• Taille maximale décodée de 10 MiB pour chaque fichier.
• Taille combinée maximale une fois décodée : 50 MiB.
• Nom de fichier maximum de 4 096 caractères.
• Type MIME maximum de 1 024 caractères.
• Des données valides base64 sont requises.

Formes d’outils JavaScript

Pour browser_evaluate, passe une expression de fonction :

() => document.title

Lorsque vous fournissez target, la fonction reçoit l’élément correspondant :

element => element.textContent

Pour browser_run_code, transmettez les instructions qui constituent le corps d’une fonction asynchrone dont le paramètre page est une page Playwright. Retournez uniquement les données sérialisables en JSON et gardez-les dans la limite de réponse en ligne.

Limites et comportement actuel

Les réponses sont renvoyées en ligne. Cette prévisualisation n’expose pas les ressources MCP ni le stockage d’artefacts persistants pour de gros instantanés, captures d’écran ou téléchargements. Les substitutions du navigateur, du système d’exploitation, de la fenêtre d’affichage, des paramètres régionaux et des agents utilisateurs ne sont pas exposées en tant que paramètres de création de session.

Gestion des erreurs

Une erreur d’outil inclut un code d’erreur stable, un message client sûr, une retryable valeur et des informations de corrélation. Utilisez la valeur retournée retryable comme signal principal, ainsi que les effets secondaires de l’opération.

Résoudre les problèmes courants

Le client MCP signale une erreur « Non autorisé »

• Confirmez que l’authentification par jeton d’accès est activée pour l’espace de travail.
• Confirmez que le jeton n’est pas expiré ou révoqué.
• Utilisez la valeur brute du jeton comme valeur x-api-key. N’ajoutez pas de Bearer préfixe.
• Confirmez que le jeton et le point de terminaison appartiennent au même espace de travail.
• Si vous avez mal copié un secret, créez un nouveau jeton car vous ne pouvez pas récupérer les valeurs existantes depuis le portail.

Le client MCP rapporte Forbidden

• Confirmez que l’utilisateur associé au jeton a toujours la permission de créer des sessions de navigateur.
• Utilisez la même connexion de projet ou jeton pour tous les appels dans une session de navigateur.
• Ne transmettez pas browserSessionId entre des utilisateurs, des agents utilisant des identifiants différents ou des espaces de travail.

Les outils ne sont pas découverts

• Vérifiez le point de terminaison complet, y compris /playwrightworkspaces/<workspace-id>/mcp.
• Vérifiez que la région de terminaison correspond à la région de l’espace de travail.
• Confirmez que le client utilise un transport HTTP MCP et envoie x-api-key lors des appels de découverte et d’outils.
• Dans Visual Studio Code, exécutez MCP : List Servers, sélectionnez le serveur, puis sélectionnez Afficher la sortie.
• Redémarrez la connexion MCP ou réinitialisez les outils mis en cache après avoir changé le point de terminaison.

L’agent n’appelle pas un outil de navigation

• Dites explicitement à l’agent d’utiliser le serveur MCP configuré de Playwright.
• Vérifiez que l’outil requis figure dans la liste d’outils activés ou autorisés du client.
• Incluez le cycle de vie création-utilisation-fermeture dans les instructions de l’agent.
• Utilisez une première tâche ciblée avec une seule cible de navigation et un résultat attendu.

Une cible ne fonctionne plus

La page a peut-être été parcourue ou réaffichée. Rappelez browser_snapshot ou browser_find de nouveau et utilisez une référence à jour. Évitez les sélecteurs liés aux classes générées ou de modifier la structure des documents.

Un outil a expiré

Ne supposez pas que l’action a échoué sans changer d’état. Si la session est active, inspectez la page actuelle avant de réessayer. Si la session a expiré, créez une nouvelle session et renvoyez l’application dans un état connu.

Une capture d’écran est trop grande

Utilisez type: "jpeg", capturez uniquement la fenêtre de vue, ou fournissez une cible pour une capture d’écran au niveau des éléments. À utiliser browser_snapshot lorsque l’objectif est d’identifier un élément plutôt que de préserver des preuves visuelles.

La session a expiré pendant un flux

Créez une nouvelle session de navigateur. Les sessions ne se reconnectent pas après une perte de connexion du navigateur, une déconnexion du propriétaire du service, une fermeture explicite ou un nettoyage pour cause d’inactivité. Concevez le flux pour qu’il puisse redémarrer à partir d’une URL et de l’état de l’application connus.

Recommandations de sécurité

• N’autoriser que les outils requis par la tâche de l’agent.
• Exiger l’approbation humaine pour les outils modifiant l’état, les fichiers et le code.
• Considérez le contenu des pages, les instantanés d’accessibilité, la sortie console et la sortie réseau comme non fiables. Une page peut contenir des instructions d’injection rapide.
• Gardez les instructions système séparées du texte dérivé de la page. Ne laissez pas le contenu des pages modifier la politique de sécurité ou les règles d’approbation.
• Validez les URL de destination par rapport à une liste de permis lors de l’automatisation des applications sensibles.
• Examinez le texte, les sélecteurs, le contenu des fichiers et le code avant d’approuver un appel d’outil.
• N’utilisez pas de jetons d’accès dans les invites, fichiers sources, captures d’écran, fichiers téléchargés ou extraits JavaScript.
• Utilisez des jetons de courte durée, faites-les pivoter régulièrement et révoquez les connexions inutilisées.
• Utilisez un espace de travail dédié et une identité de privilège minimum pour chaque frontière de confiance.
• Enregistrez les approbations et les noms d’outils pour auditer, mais ne consignez pas les identifiants, le contenu téléchargé ou les données sensibles des pages.

Disponibilité régionale

Espaces de travail pour les dramaturges est disponible dans les régions Azure suivantes :

Contenu connexe

• Gérer les jetons d’accès à l’espace de travail
• Gérer l’accès à un espace de travail pour dramaturges
• Connecter les agents Microsoft Foundry aux points de terminaison serveur MCP
• Ajouter et gérer les serveurs MCP dans Visual Studio Code
• Documentation du Model Context Protocol