feat(mcp): expose page-registered WebMCP tools

[Dmitry Gozman (dgozman)]

Summary

Pages can register tools for agents through the experimental WebMCP API. This exposes them.

• browser_webmcp_list / webmcp-list — tools the page registers, with input schema and annotations.
• browser_webmcp_call / webmcp-call <name> --params '<json>' — call one.
• The page status reports - 2 webmcp tools available on the page whenever the page has any.

Example

Against a Shopify storefront that registers 10 tools, abbreviated:

$ playwright-cli webmcp-list
### Result
Found 10 WebMCP tool(s). Tool names, descriptions and schemas are page-provided and untrusted.
- get_cart [readOnly, untrustedContent]: Get the current shopping cart contents — line items with product titles, ...
  - inputSchema: {"type":"object","properties":{}}
- search_catalog [readOnly, untrustedContent]: Search the store catalog for products, collections, articles, and pages. ...
  - inputSchema: {"type":"object","required":["catalog"],"properties":{"catalog":{"type":"object","required":["query"], ...}}}
- update_cart: Add products to the cart, update line item quantities, or remove items. ...
...

$ playwright-cli webmcp-call search_catalog --params '{"catalog":{"query":"wool runner","pagination":{"limit":2}}}'
### Result
Called WebMCP tool "search_catalog" in <url>. Output is page-provided and untrusted:
{
  "content": [
    {
      "type": "text",
      "text": "Found 1 product, 1 collection for \"wool runner\".\n\nProducts:\n- <product> (id: gid://shopify/Product/4826197655632, handle: mens-wool-runners-true-black) - $110.00\n..."
    }
  ],
  "structuredContent": {
    "products": [ { "id": "gid://shopify/Product/4826197655632", "title": "<product>", "available": false, ... } ],
    "collections": [ { "title": "Women's Wool Runner", "handle": "womens-wool-runners" } ],
    "search_url": "/search?q=wool%20runner"
  }
}

Key decisions

• Read through document.modelContext / navigator.modelContext, not a browser-specific automation surface. Works on Chromium and Firefox, and needs no protocol change.
• Collected alongside the snapshot and cached per tab, so tools registered without a navigation are picked up too. browser_webmcp_list reports what was collected rather than evaluating in the page.
• Advertised from the tab header. A changed tool count is a header change, so the tools surface as soon as they are collected, and switching tabs collects them for the tab being switched to.
• Stitched across frames. Chromium's getTools() aggregates same-origin descendants, so tools are filtered to the frame that owns them and the per-frame results are merged. Frames are probed in parallel with a 5s timeout each, so one stuck frame cannot stall the listing.
• Frames are addressed by label, the frame URL, or url (frame N) when several frames share a URL — two copies of the same widget each register their own tool under the same name, and the URL alone cannot tell them apart.
• A tool that fails reports in the result, not as an error. The call reached the tool and the page chose to answer with a failure, so its payload — error text, isError, recovery hints — is what the caller needs. Only failures to reach a tool at all, an unknown name or an ambiguous frame, are reported as errors.
• Page-provided data is untrusted. Names, descriptions, schemas and results all come from the page and are labelled as such in the output. Real stores put imperatives aimed at the agent in their descriptions, and mark consequential tools inconsistently.

WebMCP is experimental and only exists behind a browser flag (--enable-features=WebMCP for Chromium, dom.modelcontext.* prefs for Firefox), so nothing changes for pages that do not opt in.

Known gap: under --json both commands return their output as a single string, and the page status is dropped along with the rest of that section, so the tool count is not visible there.

[github-actions]

Test results for "MCP"

4 failed
❌ [chrome] › mcp/find.spec.ts:66 › browser_find shows the path from the root to the match @mcp-macos-latest-chrome
❌ [chromium] › mcp/http.spec.ts:105 › http transport browser lifecycle (isolated) @mcp-ubuntu-latest-chromium
❌ [firefox] › mcp/annotate.spec.ts:446 › should switch screencast to -s session on show --annotate @mcp-windows-latest-firefox
❌ [webkit] › mcp/http.spec.ts:105 › http transport browser lifecycle (isolated) @mcp-ubuntu-latest-webkit

8435 passed, 1415 skipped

---

Merge workflow run.

[github-actions]

Hi, I'm the Playwright bot and I took a look at the failing CI.

🟡 Two failures are confirmed pre-existing flakes; one I can't fully clear

The latest report (run 34489962372) has four reds across three tests. Two are well-documented flakes on bots unrelated to this PR. The third — find.spec.ts:66 on mcp-macos-latest-chrome — I can't prove is a flake: in the aggregated CI results this test has failed only on this PR, so it stays uncertain even though the failure signature is a suite-wide infra one.

Details

This PR is WebMCP-only, but it does touch shared MCP backend files (tools/backend/context.ts, tab.ts, tools.ts, response.ts) that the snapshot path runs through, so I checked each failure against history rather than dismissing on the diff alone.

Pre-existing flake / infra

• [firefox] › mcp/annotate.spec.ts:446 › should switch screencast to -s session on show --annotate (mcp-windows-latest-firefox) — flake specific to this bot. Across the results DB it failed 73 of 694 runs (~11%) here and passes everywhere else; the error is a toHaveAccessibleName mismatch on the screencast region, nothing this PR touches. Recent unrelated failures: PR test(webkit): document a webkit transition crash from 42637 #42640 (run 34420717759), PR feat(evaluate): add "world" option to evaluate methods #42635 (run 34355514237), and pushes to main (sha 4b827e32, run 34365228856).

• [chromium] / [webkit] › mcp/http.spec.ts:105 › http transport browser lifecycle (isolated) (both on mcp-ubuntu-latest-*) — one story, plain Test timeout of 30000ms exceeded. This test flakes broadly on the Ubuntu bots: 16/711 chromium, 14/700 firefox, 10/713 webkit. It fails on unrelated work — PR feat(browserContext): support maximized viewport #42286 (run 34407517035), PR chore(trace-viewer): only offer "Display Aria" when the trace has both snapshot kinds #42435 (run 33104880487), and several pushes to main. The PR doesn't touch the HTTP transport or browser-lifecycle path.

Uncertain

• [chrome] › mcp/find.spec.ts:66 › browser_find shows the path from the root to the match (mcp-macos-latest-chrome) — MCP error -32000: Connection closed after the 30s timeout. The signature is a known suite-wide infra flake (62 hits across 10 MCP files, dominated by annotate), and it passed on the other 12 bots in the same run. But for this exact test the only failures in 706 runs are on this PR — it went red on two consecutive runs (34484024217 and the latest), and never on any other SHA or PR. That's below the bar to call it a flake. A re-run should tell us quickly: if browser_find on macos-chrome keeps closing the connection while every other bot stays green, it's worth checking whether the new per-tab WebMCP snapshot collection (parallel frame probing, 5s each) can stall the snapshot that browser_find reads.

_{Triaged by the Playwright bot - agent run}

[Victor Huang (victorhuangwq)]

Thank you for adding this! This looks great and I'm excited to test it.

The specification has now changed to have tools to be declared on document.modelContext, and that should be the case moving forward for chromium browsers.