Quickstart: Automate browser tasks with the Playwright Workspaces remote MCP server

In this quickstart, you connect an AI agent to the Playwright Workspaces remote MCP server. The agent uses a managed cloud browser to open a webpage, inspect its accessibility snapshot, report page content, and close the browser session.

The remote MCP server provides browser automation tools over streamable HTTP. You don't need to install Playwright, browser binaries, or a local MCP server in the agent environment.

After you complete this quickstart, you have an MCP client connected to a Playwright workspace and can run an agent-driven browser task from GitHub Copilot CLI or Microsoft Foundry.

Prerequisites

• An Azure account with an active subscription. If you don't have an Azure subscription, create a free account before you begin.
• A Playwright workspace that is enabled for the remote MCP preview.
• The Contributor or Owner Azure role at the workspace scope. This role is required to create a workspace access token. For more information, see Manage access to a Playwright workspace.
• One of the following MCP clients:
  • GitHub Copilot CLI with MCP support.
  • A Microsoft Foundry project with permission to create project connections and configure agents.

Build the remote MCP endpoint

In the Azure portal, open the Overview page of your Playwright workspace. Use the workspace region and workspace ID to build the remote MCP endpoint.

The endpoint uses the following format:

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

For example:

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

Use the endpoint for the region where the workspace is deployed.

Create a workspace access token

This quickstart uses key-based authentication. The MCP client sends a workspace access token in the x-api-key request header.

1. Sign in to the Azure portal.
2. Open your Playwright workspace.
3. Under Settings, select Access Management.
4. Select the Playwright Service Access Token checkbox if it isn't already selected.
5. Select Generate token.
6. Enter a name and expiration date, and then generate the token.
7. Copy the token immediately. You can't retrieve its value later.

The token is associated with the user who creates it. The service evaluates that user's current Azure role-based access control (RBAC) permissions when the token is used. Use a short expiration period for this quickstart.

For more information, see Manage workspace access tokens.

Connect an MCP client

Choose the MCP client that you want to use.

GitHub Copilot CLI

To add the Playwright Workspaces remote MCP server to GitHub Copilot CLI:

1. Open GitHub Copilot CLI.
2. Enter /mcp add.
3. Enter a unique server name, such as playwrightWorkspace.
4. Select HTTP as the server type.
5. Enter the remote MCP endpoint.
6. Add an HTTP header named x-api-key and use the workspace access token as its value.
7. Select Auto for deferred tools.
8. Press Esc to finish adding the server.

Microsoft Foundry

Connect the remote server as a custom MCP tool. Foundry stores the workspace access token in a project connection.

To connect the remote MCP server:

1. Open your project in the Microsoft Foundry portal.
2. Select Build > Tools, and then select Add tool > Custom > Model Context Protocol.
3. Enter playwrightWorkspace as the unique name.
4. Enter the remote MCP server endpoint.
5. Select key-based authentication.
6. Enter x-api-key as the credential name and the workspace access token as the credential value.
7. Select Connect. Foundry creates the project connection.

Create or open an agent, add the remote MCP tool, and select the project connection. Require approval for every tool call while you evaluate the integration. Requiring approval lets you inspect the tool name and arguments before each browser operation.

For current connection fields and approval behavior, see Connect Microsoft Foundry agents to MCP server endpoints.

Run your first browser task

Submit the following prompt to the agent:

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.

Verify that the agent follows this sequence:

1. Calls create_browser_session and retains the returned browserSessionId.
2. Calls browser_navigate with the session ID and https://example.com.
3. Calls browser_snapshot or browser_find with the same session ID.
4. Reports the Example Domain heading and the page URL.
5. Calls close_browser_session with the session ID.

A successful result resembles the following output:

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

The exact response varies by agent and model. The session creation result might also contain a live-view URL. The final response alone doesn't confirm cleanup. Inspect the tool-call history and verify that close_browser_session succeeded.

Clean up resources

When you finish the quickstart:

1. Confirm that the agent called close_browser_session.
2. Remove the test agent or project connection if you no longer need it.
3. Revoke temporary workspace access tokens.
4. In GitHub Copilot CLI, remove the MCP server if you no longer need the connection.
5. If you created a Playwright workspace only for this quickstart, delete its resource group. Don't delete a resource group that contains resources you want to keep.

Next step