WebMCP for Browser-Based AI Agents

WebMCP is a proposed browser API that lets a website expose selected functions as named, structured tools to an AI agent running in the browser. Instead of making an agent infer buttons, fields, and click sequences from page layout, the site can describe an operation, validate its inputs, execute it in the current page session, and return a bounded result.

WebMCP is still experimental. Chrome describes it as a proposed web standard, points developers to an origin trial and Chrome Status, and says the work is under active discussion. Check the current browser documentation before promising support or shipping a production dependency.

What WebMCP does

WebMCP places a structured tool interface beside a site’s normal user interface. A browser agent can discover tools while visiting the page and invoke them with typed arguments. The implementation can use the page’s current session, DOM state, client-side application state, and authenticated context.

Typical examples include:

Preparing a customer-support ticket from a form.
Selecting ecommerce options and adding an item to a cart.
Searching, filtering, or booking travel.

These are examples from Chrome’s preview material; they are not capabilities automatically available on every website or browser.

WebMCP versus MCP

Axis	WebMCP	MCP
Where functionality lives	Frontend functionality in a live website	External or backend systems and workflows
Availability	Discovered during a visit and bound to the open tab	A persistent server or daemon can run independently of a page
Context	Browser-integrated and aware of the current page and session	Platform-independent and potentially headless
Best fit	Actions on the site the user is currently viewing	Durable services, background work, and multi-client access

WebMCP does not replace MCP. A service can use backend MCP for durable business logic and data access, then use WebMCP for contextual interaction with the live website. Chrome calls WebMCP MCP-inspired rather than a direct JavaScript implementation of MCP. See Chrome’s comparison guidance.

How WebMCP works

The browser loads a page.
The page exposes tools using declarative HTML annotations or the imperative JavaScript API.
A compatible browser agent discovers those tools during the visit.
The agent chooses a tool and supplies structured arguments.
The page validates the request, performs the operation, and returns a concise result.

Tools are ephemeral: they exist while the page is open and disappear when the user leaves or closes the tab. A browser or client must visit the origin to discover them.

Declarative WebMCP with an HTML form

The declarative API targets ordinary form actions. Add toolname and tooldescription attributes to a form. The browser can expose the form as a structured tool while preserving normal form behavior for human users.

<form method="post"
      action="/support/tickets"
      toolname="create_support_ticket"
      tooldescription="Create a support ticket for the signed-in customer. Use for product problems that need human follow-up.">
  <label>
    Subject
    <input name="subject" required maxlength="120">
  </label>
  <label>
    Details
    <textarea name="details" required maxlength="4000"></textarea>
  </label>
  <label>
    Priority
    <select name="priority">
      <option value="normal">Normal</option>
      <option value="urgent">Urgent</option>
    </select>
  </label>
  <button type="submit">Submit ticket</button>
</form>

<script>
  if ('modelContext' in document) {
    document.modelContext.addEventListener('toolactivated', ({toolName}) => {
      console.info('WebMCP tool activated:', toolName);
    });
  }
</script>

Keep the form usable without an agent. Server-side validation, authentication, authorization, CSRF protection, and rate limits still apply.

Imperative WebMCP with JavaScript

Use the imperative API for dynamic workflows that need application state or custom JavaScript. The following example registers a read-only order lookup and handles cancellation.

async function registerOrderTool() {
  if (!('modelContext' in document)) {
    console.info('WebMCP is unavailable in this browser.');
    return;
  }

  await document.modelContext.registerTool({
    name: 'get_order_status',
    description: 'Find the signed-in customer\'s order status by order number.',
    inputSchema: {
      type: 'object',
      properties: {
        orderNumber: {
          type: 'string',
          description: 'Order number shown in the customer receipt.'
        }
      },
      required: ['orderNumber']
    },
    annotations: {
      readOnlyHint: true,
      untrustedContentHint: true
    },
    execute: async ({orderNumber}, {signal}) => {
      const response = await fetch(
        `/api/orders/${encodeURIComponent(orderNumber)}`,
        {signal, credentials: 'include', headers: {'Accept': 'application/json'}}
      );
      if (!response.ok) throw new Error(`Order lookup failed: ${response.status}`);
      const data = await response.json();
      return JSON.stringify({
        orderNumber: data.orderNumber,
        status: data.status,
        location: data.location
      });
    }
  });
}

registerOrderTool().catch(console.error);

The current Chrome API uses document.modelContext.registerTool(). The execute function receives an abort signal as its second argument, so pass it to long-running requests. You can unregister a tool with an AbortController when the page state changes.

Designing useful tools

One purpose per tool: use action-oriented names such as search_flights or create_support_ticket.
Describe when to use it: explain the result and prerequisites in plain language.
Use a precise schema: constrain strings, enums, ranges, and required fields.
Return a small result: include only fields the agent needs for the next decision.
Register by page state: expose a checkout tool only when checkout is actually available.
Avoid overlap: multiple tools that perform the same task make selection less reliable.

Chrome’s best-practice guidance recommends descriptions of about 500 characters or less, parameter descriptions around 150 characters or less, names of 30 characters or less, and individual tool output around 1.5K characters. These are recommendations for better model behavior, not universal protocol limits.

Origin isolation and Permissions Policy

WebMCP is limited to origin-isolated documents. Enabling document.domain, such as through Origin-Agent-Cluster: ?0, disables the APIs.

The tools Permissions Policy defaults to self. Top-level and same-origin contexts can use the API, while cross-origin iframes are disabled unless explicitly allowed:

<iframe src="https://partner.example/checkout" allow="tools"></iframe>

Cross-origin exposure should be deliberate. The imperative API supports an exposedTo option containing specific trusted origins. Review the current Chrome WebMCP documentation before relying on exact policy behavior.

Security and prompt-injection defenses

Tool definitions can contain malicious instructions in names, descriptions, or parameters. Tool output can also contain third-party text, such as comments or imported documents, that attempts to redirect the agent. An authenticated browser session increases the impact of data leakage or unauthorized actions.

Expose tools only to trusted origins.
Mark externally sourced output with untrustedContentHint.
Use readOnlyHint for functions that do not change state.
Set consequentialHint: true for purchases, bookings, transfers, deletion, and other significant actions.
Require human confirmation before irreversible operations.
Validate authorization on the server; a tool annotation is not an access-control boundary.
Limit input length, output size, token budgets, and cross-origin interaction.
Delimit untrusted text in the agent’s context and treat it as data, not instructions.

Chrome’s tool security guidance and agent security guidance both recommend defense in depth. Model safeguards alone cannot guarantee safe execution.

Testing a WebMCP integration

Test the normal human form or UI first.
Test feature detection in browsers where document.modelContext is absent.
Inspect tool names, schemas, descriptions, and output sizes with the available Chrome preview or inspector tooling.
Test authenticated and logged-out sessions separately.
Simulate malformed arguments, expired sessions, server errors, cancellation, and duplicate execution.
Verify that consequential actions pause for confirmation.
Test iframe behavior with and without allow="tools".

Performance, reliability, and cost

WebMCP adds no universal network cost by itself, but every tool consumes agent context and may add a page request. Register only tools relevant to the current state. Keep schemas and results small, use indexed backend queries, and return stable identifiers instead of large records.

Reliability depends on the page, browser, agent, session, and backend. Design idempotent operations where possible, use request identifiers for writes, handle abort signals, and make retries safe. A tab-bound tool is unavailable after navigation or closure, so durable workflows still belong behind a backend service.

There is no verified adoption rate, latency benchmark, uptime figure, or universal browser-support guarantee in the cited material. Treat availability as provisional and check Chrome’s preview announcement, Chrome Status, and the current origin-trial instructions before publishing compatibility claims. The W3C AI Knowledge Representation Community Group describes WebMCP as a Draft Community Group Report and explicitly says it is not a W3C Standard or on the W3C Standards Track: technical notes.

Common errors and fixes

Symptom	Likely cause	Fix
`document.modelContext` is undefined	Unsupported browser, disabled preview, or non-isolated document	Feature-detect, check the origin trial and Chrome Status, and keep the normal UI path.
Tool is not discovered	Tool registered in the wrong page state or blocked by policy	Register after the relevant state exists; inspect `tools` Permissions Policy and iframe `allow`.
Cross-origin iframe cannot use tools	Cross-origin access is disabled by default	Allow the feature explicitly and restrict exposure to trusted origins.
Agent chooses the wrong tool	Overlapping names or vague descriptions	Use one action per tool, specific names, clear prerequisites, and constrained schemas.
Tool returns unsafe instructions	Untrusted third-party content in output	Mark it untrusted, cap output, delimit it, and require confirmation for actions.
Duplicate or partial writes	Retry or cancellation during a non-idempotent operation	Use idempotency keys, transaction checks, and abort-aware server handling.
Tool disappears after navigation	Tools are bound to the live page	Re-register on the new page or use a persistent backend MCP service.

Or skip the browser setup

If your goal is reliable website capture for an agent workflow, ScreenshotNeo provides a single screenshot API and an MCP server. Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status.

See the ScreenshotNeo API documentation for all options. A basic request:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. It supports full-page and element capture, dark mode, device presets, custom CSS and JavaScript, waits, request blocking, headers and cookies, geolocation, caching, signed links, asynchronous jobs, bulk capture, and PDF options. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.

Create your free ScreenshotNeo account and start with 1,000 screenshots a month without a card.

FAQ

Is WebMCP a finished web standard?

No. Chrome describes it as a proposal under active discussion with preview and origin-trial pathways. Browser support and API details may change.

Does WebMCP require an MCP server?

No. WebMCP is a browser-facing API. You can combine it with MCP, but a page can expose WebMCP tools without running a conventional backend MCP server.

Can WebMCP run headlessly?

Chrome says headless usage is possible, but the API is primarily designed for local browser workflows with a human in the loop. Verify the current implementation before building a headless dependency.

Can a tool read private account data?

It can operate inside the current session, so read-only tools may still expose sensitive information. Apply authorization, origin restrictions, output limits, and confirmation policies.

How many tools should a page expose?

Expose the smallest useful set for the current page state. Chrome’s guidance warns that excessive tools consume context, add latency, and make selection harder.