DEV Community: Prasanna Vaidya

auto-webmcp v0.3.0: React support, richer schemas, and WebMCP spec compliance

Prasanna Vaidya — Wed, 25 Mar 2026 07:11:52 +0000

When we shipped the first version of auto-webmcp, the pitch was simple: drop one script tag and every form on your page becomes a callable tool for AI agents, no manual JSON Schema writing required.

That core idea has not changed. But the past two days have been a sprint through every edge case the real web throws at you: React forms that fight you, inputs that live outside <form> tags, select menus that lie about their options, and a new set of WebMCP spec fields that make your tools dramatically more useful to agents.

Here is what shipped.

React and framework-managed forms

Vanilla forms are easy. React forms are a different story.

React intercepts input events using its own synthetic event system. Setting input.value = 'foo' directly does nothing because React's state never updates. The DOM value changes, but React still thinks the field is empty. When the form submits, it sends blank data.

auto-webmcp now fills React inputs by dispatching a native input event through HTMLInputElement.prototype — bypassing the React wrapper and triggering onChange as if the user typed the value themselves:

// What we do internally for React-controlled inputs
const nativeSetter = Object.getOwnPropertyDescriptor(
  HTMLInputElement.prototype, 'value'
).set;
nativeSetter.call(input, value);
input.dispatchEvent(new Event('input', { bubbles: true }));

For frameworks that use execCommand (older content-editable patterns), we fall back to document.execCommand('insertText', false, value).

There is also a subtler React problem: when an agent fills a form and triggers a re-render, React can reset the field values before the submit fires. We now capture a post-fill snapshot immediately after filling, and use that snapshot when constructing the response instead of re-querying the live DOM.

MutationObserver re-analysis is debounced for forms that add inputs lazily (common in multi-step React flows). If a new field appears inside an already-registered form, auto-webmcp re-analyzes the schema without re-registering a duplicate tool.

ARIA inputs and unnamed fields

The web is full of inputs that are not <input> elements. Rich text editors, custom dropdowns, date pickers — most of them use role="textbox", role="combobox", or role="spinbutton" to communicate their semantics to screen readers. auto-webmcp now reads the same signals.

Any element with a recognized ARIA input role is included in the schema alongside native inputs. The field key is inferred from aria-label or the associated <label> element.

For inputs without a name attribute (common in React where form state lives in JS, not the DOM), we now key the schema field by id or aria-label so agents can still reference and fill them by name.

One specific fix: Ghost's newsletter signup forms use an <input type="email"> with no name or id — only a placeholder. Previously, these were silently excluded. Now placeholder is used as the field key and title, making these forms fully callable.

Schema improvements for selects and checkboxes

Optgroup labels are now surfaced in the schema. If a select menu groups options under <optgroup label="North America">, the label appears as metadata on the option, giving agents clearer context for picking values.

Datalist suggestions from <input list="..."> are collected and included in the schema as suggestions, not hard constraints — agents can still provide values outside the list.

Disabled options are excluded. If an option is disabled, agents should not try to select it.

Meaningful empty options are now handled correctly. The old behavior was simple: skip any <option value="">. But that excluded legitimate choices like "No preference" or "All Categories". Now we only skip placeholder text that follows the pattern "Select...", "Choose...", "Pick...", or "---". Empty-value options with real labels are included in the schema with const: "" so agents can express those choices.

Multi-select fields produce type: array with items.enum instead of a single-value string. The fill handler accepts an array of values or a single string (treated as a one-element array), deselects all options first, then selects matching values.

Checkbox groups produce type: array with items.enum listing the values of each checkbox in the group. Filling accepts an array of values to check.

Orphan inputs (forms without `<form>` tags)

A surprising number of real-world "forms" are not <form> elements. They are collections of inputs inside a <div>, with a submit button and some JavaScript. Single-page apps love this pattern.

auto-webmcp now scans for inputs outside <form> elements, groups them by their nearest ancestor that contains a visible submit button, and registers each group as a tool. The same schema inference rules apply: field types, labels, enums, and descriptions are all collected.

This means subscribe boxes, search widgets, and wizard steps that skip the <form> tag are now automatically callable.

WebMCP spec compliance: annotations, field titles, defaults

Version 0.3.0 adds three features that align auto-webmcp with the latest WebMCP spec.

Tool annotations

ToolAnnotations is a set of hints that tell agents about the behavior of a tool before they call it:

Annotation	Meaning
`readOnlyHint`	Tool only reads data, does not modify anything
`destructiveHint`	Tool deletes or irreversibly modifies data
`idempotentHint`	Calling the tool multiple times has the same effect as calling it once
`openWorldHint`	Tool talks to external systems (email, payment, etc.)

auto-webmcp infers these automatically:

GET forms get readOnlyHint: true
Forms with delete/remove/cancel button text get destructiveHint: true
Forms posting to URLs with /search or /filter patterns get idempotentHint: true
Forms posting to external domains get openWorldHint: true

You can override any inference with data attributes:

<form data-webmcp-destructive="true" data-webmcp-openworld="true">
  <!-- delete account form -->
</form>

Field titles via `toolparamtitle`

The WebMCP spec added toolparamtitle as a native attribute for setting the display title of a schema field. auto-webmcp now reads this attribute first, before falling back to data-webmcp-title and label text.

<input
  type="text"
  name="q"
  toolparamtitle="Search query"
  toolparamdescription="What you want to search for"
>

Schema defaults from pre-filled values

If a field has a value already set when the page loads — a text input with a default value, a select with a pre-selected option, a checked checkbox — that value is now exposed as default in the JSON Schema.

This gives agents a concrete starting point. Instead of guessing that "economy" is probably the default cabin class, the schema tells them directly.

{
  "cabin_class": {
    "type": "string",
    "enum": ["economy", "business", "first"],
    "default": "economy"
  }
}

By the numbers

v0.2.1 shipped with 32 tests
v0.3.0 ships with 82 tests
50 new integration tests covering React remounts, multi-select fill, orphan inputs, annotations, and defaults
All tests run against real Chromium via Playwright

Try it

<script
  src="https://cdn.jsdelivr.net/npm/auto-webmcp@0.3.0/dist/auto-webmcp.iife.js"
  async>
</script>

That is the entire integration. Every form on your page becomes a callable WebMCP tool. React forms, orphan inputs, multi-selects, checkbox groups — all handled.

To test: Chrome 146+, enable chrome://flags/#enable-webmcp-testing, install the Model Context Tool Inspector extension, and open any page with the script tag.

autowebmcp.dev · GitHub · npm: auto-webmcp · MIT

What is WebMCP? Chrome's browser-native API for AI agents

Prasanna Vaidya — Sun, 22 Mar 2026 12:38:31 +0000

AI agents are getting good at using the web. But the way they interact with it today is fragile: CSS selectors, XPath queries, visual parsing, and DOM scraping that breaks every time a designer renames a class.

Chrome 146 ships an early preview of something that changes this: WebMCP.

The problem with how agents use the web today

When an AI agent needs to fill out a flight search form, it typically does something like this:

Take a screenshot or parse the DOM
Guess which input is "origin" vs "destination"
Figure out the date picker format
Click submit and hope the page structure hasn't changed

This works poorly. It's slow, brittle, and requires constant maintenance as sites update their UI. The agent is essentially learning to use a UI designed for humans, not machines.

WebMCP flips this model.

What is WebMCP?

WebMCP is a proposed web standard that lets websites publish structured tools directly to in-browser AI agents. Instead of the agent scraping the DOM to guess how a form works, the page explicitly tells the agent: here is what I can do, here are the inputs I expect, here is what I'll return.

Think of it as MCP (Model Context Protocol) built into the browser itself.

The key difference from server-side MCP: WebMCP tools are defined in the client, inside a web page, and are available only while that page is open in a browser tab. No server to deploy, no infrastructure to maintain.

How WebMCP works

Chrome exposes a new JavaScript API: navigator.modelContext. This object is the bridge between your web page and any AI agent running in the browser.

WebMCP offers two ways to define tools: the Imperative API (JavaScript) and the Declarative API (HTML annotations).

The Imperative API

Use registerTool() to define a tool in JavaScript:

navigator.modelContext.registerTool({
  name: "addTodo",
  description: "Add a new item to the todo list",
  inputSchema: {
    type: "object",
    properties: {
      text: { type: "string" }
    }
  },
  execute: ({ text }) => {
    addItemToList(text);
    return { content: [{ type: "text", text: `Added todo: ${text}` }] };
  }
});

The execute function is called by the agent with structured parameters matching your schema. You fill the UI, run the action, and return a result the agent can read.

To remove a tool (for example, when the user navigates away from a state where it makes sense):

navigator.modelContext.unregisterTool("addTodo");

This dynamic registration is useful for single-page apps where available actions change based on UI state.

The Declarative API

For forms, you don't need JavaScript at all. Add a few HTML attributes and the browser generates the tool definition automatically:

<form
  toolname="search_flights"
  tooldescription="Search for available flights between two airports"
  action="/search"
>
  <label for="origin">Departure airport</label>
  <input type="text" name="origin" id="origin">

  <label for="destination">Arrival airport</label>
  <input type="text" name="destination" id="destination">

  <select name="cabin_class" toolparamdescription="Cabin class preference">
    <option value="economy">Economy</option>
    <option value="business">Business</option>
    <option value="first">First</option>
  </select>

  <button type="submit">Search</button>
</form>

The browser reads the form structure and generates a full JSON Schema automatically, including field types, required fields, and enum options from <select> and <input type="radio"> elements.

The three key attributes:

Attribute	Where	Purpose
`toolname`	`<form>`	Tool identifier (snake_case, no spaces)
`tooldescription`	`<form>`	Plain-language description for the agent
`toolautosubmit`	`<form>`	If present, form submits automatically when agent invokes it
`toolparamdescription`	any field	Overrides the label text for the JSON Schema description

By default, when an agent invokes a declarative tool, Chrome fills in the form fields and waits for the user to click submit. Add toolautosubmit to the form if you want the agent to submit without user confirmation.

Responding to tool invocations

The Declarative API integrates with the standard submit event, extended with two new properties:

document.querySelector("form").addEventListener("submit", (e) => {
  e.preventDefault();

  if (e.agentInvoked) {
    // Agent called this tool, return structured result
    e.respondWith(Promise.resolve("Search complete. 3 flights found."));
  } else {
    // Regular human submission, handle normally
    doRegularSubmit();
  }
});

e.agentInvoked is true when the submission came from an agent. e.respondWith() lets you pass a promise that resolves to the result the agent receives.

Events and CSS pseudo-classes

WebMCP fires two events on window:

window.addEventListener('toolactivated', ({ toolName }) => {
  // Agent has filled the form, waiting for submit
  console.log(`${toolName} was activated by an agent`);
});

window.addEventListener('toolcancel', ({ toolName }) => {
  // Agent cancelled or user reset the form
  console.log(`${toolName} was cancelled`);
});

Chrome also applies CSS pseudo-classes when a tool is active:

form:tool-form-active {
  outline: blue dashed 1px; /* default Chrome style */
}

input:tool-submit-active {
  outline: red dashed 1px;
}

You can override these to match your design system and give users a clear visual indicator that an agent is operating.

What the agent sees

For a form with a <select>, Chrome generates a schema like this:

{
  "name": "search_flights",
  "description": "Search for available flights between two airports",
  "inputSchema": {
    "type": "object",
    "properties": {
      "origin": {
        "type": "string",
        "description": "Departure airport"
      },
      "cabin_class": {
        "type": "string",
        "enum": ["economy", "business", "first"],
        "oneOf": [
          { "const": "economy", "title": "Economy" },
          { "const": "business", "title": "Business" },
          { "const": "first", "title": "First" }
        ],
        "description": "Cabin class preference"
      }
    }
  }
}

Note the oneOf alongside enum: this gives the agent both the raw values it needs to submit and the human-readable labels for each option, reducing the chance of the agent picking the wrong value.

Best practices for tool design

A few things the Chrome team recommends:

Name tools with verbs that describe what happens. Use create_event for immediate creation, but start_event_creation if the tool just opens a form. The name is the agent's primary signal for when to use a tool.

Describe what the tool does, not what it doesn't do. Avoid descriptions like "Do not use for weather queries." Instead, describe exactly what the tool is for. Limitations should be implicit in a clear, specific description.

Accept raw user input in your schema. If a user says "11am to 3pm", your tool should accept strings like "11:00" and "15:00", not ask the model to convert to minutes since midnight. The model is not a calculator.

Return results after the UI updates. Agents may use UI state to verify an action succeeded before planning next steps. Make sure your execute or respondWith call happens after the UI reflects the new state.

Register tools dynamically as UI state changes. For single-page apps, register tools when they are available and unregister when they are not. An agent should never be offered a tool that does nothing or is currently disabled.

How to try it today

Install Chrome 146 or later
Navigate to chrome://flags/#enable-webmcp-testing and enable the flag, then relaunch
Install the Model Context Tool Inspector extension from the Chrome Web Store
Visit any WebMCP-enabled page, open the extension, and you will see all registered tools with their names, descriptions, and schemas

The extension also lets you manually call tools with custom parameters and test them with natural language via the Gemini API, without needing a full AI agent setup.

Google's official demo: https://googlechromelabs.github.io/webmcp-tools/demos/react-flightsearch/

Progressive enhancement by default

A critical design choice: navigator.modelContext simply does not exist in browsers that don't support WebMCP. Your code should check for it or use a library that handles this gracefully:

if (navigator.modelContext) {
  navigator.modelContext.registerTool({ ... });
}

Sites that adopt WebMCP are not broken for regular users. The tools are only visible to agents in WebMCP-capable browsers.

WebMCP vs MCP

A common question: how does this differ from the Model Context Protocol (MCP) already used by tools like Claude Desktop?

	MCP	WebMCP
Where tools run	Server-side	Client-side, in the browser
Who deploys them	Developer runs a server	Any web page can define tools
Requires a server	Yes	No
Works with	Desktop AI apps	In-browser AI agents
Spec status	Established (Anthropic)	Proposed (Google, early preview)

They are complementary. MCP gives desktop agents access to tools and data. WebMCP gives browser agents a structured interface to web pages. A future agent might use both: MCP to access your calendar, WebMCP to book a flight on an airline's website.

The bigger picture

WebMCP is in early preview, which means the API will change and the Chrome team is actively seeking feedback. But the direction is clear: the web is gaining a first-class interface for AI agents.

Forms are the most natural starting point. They already represent the actions a site wants users to take: search, submit, book, register. WebMCP makes that intent machine-readable.

If you want to make your existing forms WebMCP-ready without manually adding attributes to every one, auto-webmcp is an open-source library that does this automatically with one script tag. But even without a library, you can start today: add toolname and tooldescription to your most important forms and see them appear in the inspector.

The agentic web is not a distant future. It is in Chrome 146, behind a flag, right now.

Follow along with the WebMCP spec on GitHub and join the early preview at developer.chrome.com/blog/webmcp-epp.

Every web form should be callable by AI agents (and yours can be today)

Prasanna Vaidya — Sun, 22 Mar 2026 10:04:05 +0000

AI agents are getting good at using computers. They can browse the web, click buttons, read emails, write code. But when it comes to filling out web forms, they still do it the hard way: CSS selectors, fragile XPath queries, DOM scraping that breaks every time a designer tweaks a class name.

Chrome is about to change that.

WebMCP: structured tool registration, built into the browser

Chrome 146 shipped an Early Preview of WebMCP, a browser-native API that lets websites register their interactive elements as structured tools. Think of it as MCP (Model Context Protocol) for desktop AI, but built directly into the browser itself.

When a page registers a tool via WebMCP, an AI agent can see:

What the tool is called (e.g. submit_flight_search)
What it does (e.g. "Search for available flights between two cities")
What inputs it expects: a full JSON Schema with field types, constraints, and descriptions

No more guessing from HTML. No more brittle selectors. The agent just calls the tool.

The problem: adopting WebMCP manually is tedious

Here is what it takes to register a single form manually:

navigator.modelContext.registerTool({
  name: 'search_flights',
  description: 'Search for available flights between two airports on a given date.',
  inputSchema: {
    type: 'object',
    properties: {
      origin: { type: 'string', description: 'IATA code of departure airport' },
      destination: { type: 'string', description: 'IATA code of arrival airport' },
      departure_date: { type: 'string', format: 'date', description: 'Departure date (YYYY-MM-DD)' },
      passengers: { type: 'integer', minimum: 1, maximum: 9 },
      cabin_class: { type: 'string', enum: ['economy', 'business', 'first'] }
    },
    required: ['origin', 'destination', 'departure_date']
  },
  execute: async (params) => {
    // fill the form, submit, return result
  }
});

That's for one form. A typical site has dozens.

Then you have to maintain it every time a field changes. And write it for every platform your users are on: WordPress, Shopify, HubSpot, Zendesk, ServiceNow...

The solution: one script tag

auto-webmcp is an open-source library that does all of this automatically.

Drop one script tag into your page:

<script
  src="https://cdn.jsdelivr.net/npm/auto-webmcp@0.2.1/dist/auto-webmcp.iife.js"
  async>
</script>

That's it. Every <form> on the page is automatically:

Scanned — MutationObserver catches forms added by JavaScript too
Analyzed — name inferred from submit button, heading, or form ID; description from legend or aria-label
Schema-generated — HTML input types mapped to JSON Schema with constraints, enums, and field titles
Registered — via navigator.modelContext.registerTool() with full spec compliance

No manual JSON schema writing. No annotations required. No backend changes.

It reads your existing HTML intelligently

auto-webmcp infers everything it needs from your existing markup:

What it needs	Where it looks
Tool name	`toolname` attr, then submit button text, then nearest heading, then form `id`
Description	`tooldescription` attr, then `<legend>` text, then `aria-label`
Field type	`<input type>`, `<select>`, `<textarea>` mapped to JSON Schema
Field title	`<label>` text, then humanized field name
Options	`<option>` elements collected as `enum` + `oneOf` with display labels

If you want to override anything, you can add native spec attributes directly to the form:

<form
  toolname="submit_flight_search"
  tooldescription="Search for available flights. Requires origin, destination, and date."
  toolautosubmit="true"
>
  ...
</form>

Or use data-webmcp-* attributes, which are useful for platforms where you cannot touch the form element directly.

Safe to ship on any site today

auto-webmcp is built around progressive enhancement:

No navigator.modelContext? The script loads and does nothing, silently
Password, hidden, and file inputs are never exposed to agents
No data leaves the browser: completely client-side, MIT licensed, no API key required
Works with React, Vue, Angular, and any framework (MutationObserver handles dynamic forms)

You can drop it into production today and regular users will not notice anything. Only WebMCP-capable agents will see the registered tools.

Works on every platform

Because it is just a script tag, it works anywhere custom JavaScript is allowed:

WordPress: install the auto-webmcp plugin (currently in wp.org review) or add one line to functions.php
Shopify: paste into theme.liquid before </body>
Wix: Settings, Custom Code, Body end
HubSpot: Footer HTML tracking code
Zendesk: Zendesk Apps Framework
ServiceNow: UI Scripts

Full platform guides

Try it now

Open Chrome 146+ and enable chrome://flags/#enable-webmcp-testing
Install the Model Context Tool Inspector extension from the Chrome Web Store
Visit autowebmcp.dev/demo and watch the registered tools appear in the inspector panel in real time

The agentic web is arriving. WebMCP is the infrastructure layer. auto-webmcp is the one-line on-ramp.

autowebmcp.dev · GitHub · MIT · open source