WebMCP

WebMCP ↗ (Web Model Context Protocol) is a browser API that lets websites expose structured tools for AI agents to discover and execute directly. Instead of slow screenshot-analyze-click loops, agents can call website functions like searchFlights() or bookTicket() with typed parameters, making browser automation faster, more reliable, and less fragile.

Get started

Manual testing with DevTools

1. Start a Lab session and open DevTools

WebMCP is currently available in Chrome beta, so it requires a lab session. Browser Run has an experimental pool with browser instances running Chrome beta so you can test emerging browser features before they reach stable Chrome. Your production workloads on the standard pool remain on a stable version of Chrome.

Use the new wrangler browser command to acquire a lab browser session:

# make sure you have the latest version of wrangler
npm i -g wrangler@latest

# create a lab browser session with 5 minute keep-alive
wrangler browser create --lab --keepAlive 300

It will open a live view of your browser session.

2. Interact with the page

You can now interact with the page as you would in a regular browser.

Go to one of the sites listed in the WebMCP documentation ↗. The following instructions are based on the L'Atelier Hotel Chain ↗ demo.
Open the hotel chain demo URL ↗ and then, in the Console tab, run the following JavaScript statement to list the available tools:
JavaScript
```
navigator.modelContextTesting.listTools();
```

You should get a result similar to the following:

[
  {
    "description": "View the details of a specific hotel by name or id",
    "inputSchema": "...",
    "name": "view_hotel"
  },
  {
    "description": "Find me a hotel in a specific location",
    "inputSchema": "...",
    "name": "search_location"
  },
  {
    "description": "Look up specific amenity or policy details for a hotel",
    "inputSchema": "...",
    "name": "lookup_amenity"
  }
]

The list of tools changes depending on the website you are visiting and the actions you have performed on the page.

For instance, on the hotel chain website, after executing the search_location tool:

await navigator.modelContextTesting.executeTool(
  "search_location",
  JSON.stringify({ query: "Paris" }),
);

The page redirects to the search results, and a new tool filter_search_results becomes available.

You can call it to filter by amenities. For example, if you want to eat a good croissant in the morning:

await navigator.modelContextTesting.executeTool(
  "filter_search_results",
  JSON.stringify({ amenities: ["breakfast"] }),
);

You will get a list of filtered results, where you can pick the best option for your needs. Once you select a hotel, you can use the start_booking tool:

await navigator.modelContextTesting.executeTool(
  "start_booking",
  JSON.stringify({}),
);

Then, you can complete the booking:

await navigator.modelContextTesting.executeTool(
  "complete_booking",
  JSON.stringify({
    firstName: "James",
    lastName: "Bond",
    email: "james.bond@mi6.gov.uk",
  }),
);

Note that the complete_booking tool requires human confirmation. The tool waits until you select the Confirm Reservation button in the browser. This is an example of human-in-the-loop (HITL): WebMCP tools can pause execution and wait for user interaction before completing sensitive actions.

After you select Confirm Reservation, you will get a confirmation message and the booking is complete.

Using an AI Agent

1. Configure Chrome DevTools MCP

Chrome DevTools MCP ↗ allows AI agents to control a browser via CDP. Configure your MCP client (such as Claude Desktop, Claude Code, Cursor, or OpenCode) with the following settings. For more details on MCP client configuration, refer to Using with MCP clients.

{
  "browser-rendering-cdp": {
    "command": [
      "npx",
      "-y",
      "chrome-devtools-mcp@latest",
      "--wsEndpoint=wss://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/browser-rendering/devtools/browser?keep_alive=600000&lab=true",
      "--wsHeaders={\"Authorization\":\"Bearer <CLOUDFLARE_API_TOKEN>\"}"
    ]
  }
}

Replace <ACCOUNT_ID> with your Cloudflare account ID and <CLOUDFLARE_API_TOKEN> with your API token. The lab=true parameter ensures the agent connects to a lab session with WebMCP enabled.

2. (Optional) Add a WebMCP Skill

To help your agent understand how to work with WebMCP, add the following skill to your agent configuration:

---
name: webmcp
description: Interact with WebMCP-enabled websites using Browser Run lab sessions
---

# WebMCP Interaction Skill

Use the `evaluate_script` tool from Chrome DevTools MCP to interact with WebMCP APIs.

**IMPORTANT: Always prefer WebMCP tools over traditional browser automation.** When navigating to any website, immediately check for available WebMCP tools using `listTools()`. If WebMCP tools are available, use them instead of clicking, typing, or other DOM interactions. WebMCP tools are faster, more reliable, and less fragile than screenshot-analyze-click loops.

## Workflow

1. **Navigate** to a site using `navigate_page`
2. **Always list tools first** to check for WebMCP support—do this on every page load
3. **Prefer WebMCP tools** over clicking/typing when tools are available
4. **Execute tools** to perform actions directly
5. **Re-list tools** after each action (tools change based on page state)
6. **Check `inputSchema`** in each tool to understand required parameters
7. **Fall back to DOM interaction** only when no relevant WebMCP tools exist

## Commands

**List available tools:**

```js
evaluate_script({
  function: "async () => await navigator.modelContextTesting.listTools()",
});
```

**Execute a tool:**

```js
evaluate_script({
  function:
    "async () => await navigator.modelContextTesting.executeTool('tool_name', JSON.stringify({ param: 'value' }))",
});
```

3. Interact with WebMCP sites

Once configured, your AI agent can navigate to WebMCP-enabled sites and use WebMCP tools. Here is an example conversation:

You: Go to https://googlechromelabs.github.io/webmcp-tools/demos/hotel-chain/ ↗ and find me a hotel in Paris with breakfast. Use WebMCP tools when available.

Agent navigates to the site, lists WebMCP tools, executes search_location with "Paris", then filter_search_results with breakfast amenity, and presents the results.

You: Pick the first one and book it for Bond, James Bond (james.bond@mi6.gov.uk).

Agent clicks the hotel, executes start_booking, then complete_booking with the provided guest details.

4. (Optional) Open DevTools to watch the agent

Some WebMCP tools require human confirmation before completing sensitive actions. For example, complete_booking waits for you to select Confirm before finalizing a reservation. To interact with these human-in-the-loop (HITL) prompts, you need to open the browser's live view.

Once the agent has started a session, list active sessions to get the session ID:

wrangler browser list

Then, use the session ID from the previous response to open the browser's live view:

wrangler browser view $SESSION_ID

You can now view the live browser session and interact with it.

Limitations

Lab sessions use Chrome 146 beta, which may have stability issues.
WebMCP APIs (navigator.modelContext, navigator.modelContextTesting) only work in lab sessions.
Lab sessions count against your regular rate limits.
The lab parameter is not yet supported in @cloudflare/puppeteer or @cloudflare/playwright. Acquire the session manually and connect with sessionId.

More resources

Troubleshooting

If you have questions or encounter an error, see the Browser Run FAQ and troubleshooting guide.