W4DEV

Use a browser agent through WebMCP

By the end of this page an agent that runs inside your browser tab can see and call the site’s tools, and you have run a tool yourself to confirm they are there.

WebMCP is a draft browser API. A page registers tools on document.modelContext, and an agent in the browser calls them. Block Theme MCP registers its tools there for a signed-in user who holds the capability the tools require. Nothing has to be connected: the agent uses the session of the tab it runs in.

The switches

All of them are on the Settings tab, under Ways to connect, in the Browser agents (WebMCP) group.

  • Admin screens starts on. It registers the tools on wp-admin screens, including the Customizer.
  • Front end starts off. It registers the tools on public pages, for logged-in users who hold the capability tools require.
  • Polyfill document.modelContext starts on. When the browser has no WebMCP, the plugin provides one, so browser extensions and page scripts can still reach the tools.

Visitors who are not signed in never get any tool, on any page.

Check what your browser offers

The Status card at the top of the settings screen has a Browser agents (WebMCP) row. Under it, one line describes the browser you are using right now:

  • “Chrome WebMCP detected”: the browser has WebMCP built in.
  • “Polyfill active: tools are visible to this page and browser extensions that read it, not to Chrome’s built-in agent”: the plugin’s own document.modelContext is in use.
  • “Not available”: the browser has no WebMCP and the polyfill is switched off.

Run a tool without an agent

  1. Open the Tools tab and scroll to Tool inspector.
  2. Choose btm.site-info in Tool.
  3. Leave Input (JSON) as {} and click Run.

The result shows your site address, the WordPress and PHP versions and the tool groups that are on. If the inspector says “Tools are not active on this screen for your account.”, the Browser agents (WebMCP) row of the Status card names the reason: the main switch is off, your account lacks the capability, or Admin screens is off.

Chrome’s built-in agent and origin-trial tokens

Chrome’s built-in agent only sees the tools on a site that has a WebMCP origin-trial token. Without a token, the polyfill still serves browser extensions and page scripts.

  1. Register your site’s origin, for example https://example.com, at https://developer.chrome.com/origintrials/.
  2. On the Settings tab, open Origin trial tokens in the Browser agents (WebMCP) group.
  3. Paste the token into WebMCP origin-trial tokens, one per line and click Save Changes.

The plugin prints each token as an origin-trial meta tag on every page where tools are active. Tokens are issued per origin, so a token for one address does not work on another.

Confirmations

With Confirm destructive tools on (the default), a tool marked destructive asks first. The prompt names the tool and shows the arguments it is about to run with:

Allow the AI agent to run "btm.theme-update-file"? This action may change or delete data.

The prompt comes from the agent’s own confirmation UI when it has one, and from a browser dialog otherwise. An answer that arrives in under 300 milliseconds is not counted as a person’s answer, and the tool does not run. Keep the tab in front when you expect a prompt.

Tools that only exist in the browser

Four tools need a tab, so only a browser agent gets them: btm.browse-navigate, btm.browse-current-url, btm.browse-open-tab and btm.request. The first three are in the Browse group. btm.request is in the HTTP requests group, which is off by default. Read Tool groups and what each one allows before you switch it on.

If something goes wrong

  • The agent sees no tools on a public page. Front end is off, or you are not signed in.
  • A destructive tool fails at once with “closed before a person could answer it”. The dialog was dismissed automatically, often because the tab was in the background. Bring the tab to the front and try again.
  • Tools vanish after a page script runs. A script that calls provideContext() or clearContext() on document.modelContext clears every registered tool until the next page load.