WebMCP Tutorial: Building Agent-Ready Websites With Chrome New Standard
WebMCP (Web Model Context Protocol) is a new browser standard that lets websites declare their capabilities as structured tools that AI agents can call directly. Instead of forcing an AI to "read" and click through a visual interface, WebMCP turns the webpage itself into a clean, client-side API. This complete tutorial walks you through what WebMCP actually is, how to set up your environment, and build working integrations using both HTML-based and JavaScript-based approaches.
What You'll Learn:
- What WebMCP is and how it differs from standard MCP
- How to set up Chrome Canary and enable WebMCP flags
- Build declarative WebMCP tools with HTML form annotations
- Build imperative WebMCP tools with JavaScript API
- Handle agent invocation detection and safety patterns
- Test WebMCP implementations with Chrome DevTools and Model Context Tool Inspector
What Is WebMCP?
WebMCP (Web Model Context Protocol) is a new browser standard that lets websites declare their capabilities as structured tools that AI agents can call directly. Instead of forcing an AI to "read" and click through a visual interface, WebMCP turns the webpage itself into a clean, client-side API.
Let us think about what happens when an agent tries to book a flight on a travel site today. It has to figure out which field expects the departure city, guess whether the date format is MM/DD or YYYY-MM-DD, locate the search button, and hope the page does not reload into a layout it has never seen before. If the site could instead publish a tool called searchFlights with typed parameters, all of that guessing disappears.
WebMCP makes that possible. A site registers tools through a browser API called navigator.modelContext, where each tool comes with a name, a natural language description, and a JSON schema for its inputs and outputs. The agent discovers those tools, sends parameters that match the schema, and receives structured data in return.
WebMCP vs Standard MCP
| Feature | Standard MCP | WebMCP |
|---|---|---|
| Architecture | Backend server handles tool execution over JSON-RPC | Purely client-side, runs in browser tab |
| Tool Execution | Separate server process | In page JavaScript, shares user session |
| Discovery | MCP server connection | Agent visits page to discover tools |
| Infrastructure | Requires separate backend server | No backend needed, uses existing frontend JS |
WebMCP Key Features and Capabilities
Declarative API (HTML)
Add toolname and tooldescription attributes to form elements. Browser generates JSON schema from existing form structure automatically.
Imperative API (JavaScript)
Full programmatic control with navigator.modelContext.registerTool() for dynamic workflows and custom validation logic.
Dynamic Registration
Tools can appear and disappear as page state changes. Register login tool before auth, account tools after authentication.
CSS Pseudo-Classes
Visual feedback during agent interactions. :tool-form-active and :tool-submit-active show which form the agent is working on.
JSON Schemas
Every tool specifies types, enums, required fields, and parameter descriptions to prevent agents from inventing values.
No Backend Required
Tools run in page context, use same session as human user, need no additional infrastructure behind them.
Early Preview Note
WebMCP is still in early preview, available only in Chrome Canary behind a flag. The spec has already evolved, including removal of provideContext and clearContext methods in March 2026. Tool discoverability is limited to pages already visited. Check the Chrome documentation changelog before starting.
WebMCP Prerequisites and Environment Setup
Getting the environment right takes a few minutes, though the wrong Chrome version will waste considerably more time than that. Chrome Canary version 146.0.7672.0 or higher is required. The stable release, Beta, and Dev channels of Chrome do not ship with the WebMCP flag.
Download Chrome Canary
Download specifically from the Chrome Canary page. Several developers have reported installing the wrong version and wondering why the flag was missing.
Enable WebMCP Flag
Navigate to chrome://flags/#enable-webmcp-testing, set "WebMCP for testing" to Enabled, and click Relaunch at the bottom of the page.
Verify API Availability
Open DevTools (F12), go to Console tab, and run console.log(navigator.modelContext). An object (not undefined) confirms the API is available.
Install Model Context Tool Inspector
Install the Model Context Tool Inspector Extension from Chrome Web Store. It lists registered tools, lets you execute them manually, and has built-in Gemini API support for testing.
Enable File URL Access (for local testing)
Open the extension settings, go to Details, and enable access to file URLs so the extension can interact with your local HTML files during development.
Building Your First WebMCP Integration
There are two ways you can build your first WebMCP integration: the declarative approach using HTML annotations, and the imperative approach using JavaScript API.
The Declarative Approach (HTML)
The simplest way to register a WebMCP tool is to annotate a form that already exists on your page. Four attributes turn a standard form into an agent-callable tool: toolname, tooldescription on the form, and toolparamtitle and toolparamdescription on individual fields.
What the browser does with those attributes is generate a JSON schema internally. The tool name, parameter types, enum values from select options, and required markers from HTML all carry over without additional configuration.
Agent Fills Form
Chrome focuses the form, populates fields with values the agent supplied, and stops there. The user still has to click Submit by default.
Auto-Submit (Optional)
Add toolautosubmit attribute to remove confirmation step. Use for read-only operations like search queries, not for data-modifying actions.
Intercept and Respond
Use respondWith() method on submit event to send structured results back to the agent instead of normal form submission.
Detect Agent vs Human
Use the agentInvoked boolean on submit event. True when agent triggered submission, false for human click. Branch your response formatting accordingly.
The Imperative Approach (JavaScript)
Forms cover a lot of ground, but some tools need to work with application state, make API calls, or return computed results that do not map to a traditional form submission. The imperative API gives you full programmatic control.
navigator.modelContext.registerTool({
name: "addTodo",
description: "Add a new item to the user's to-do list.",
inputSchema: {
type: "object",
properties: {
text: { type: "string", description: "The task description" },
priority: { type: "string", enum: ["low", "medium", "high"] }
},
required: ["text"]
},
execute: (params) => {
const { text, priority = "medium" } = params;
const newItem = { id: Date.now(), text, priority, done: false };
todoApp.addItem(newItem);
todoApp.renderList();
return {
content: [{ type: "text", text: "Added task: " + text }]
};
}
});
navigator.modelContext.registerTool({
name: "addTodo",
description: "Add a new item to the user's to-do list.",
inputSchema: {
type: "object",
properties: {
text: { type: "string", description: "The task description" },
priority: { type: "string", enum: ["low", "medium", "high"] }
},
required: ["text"]
},
execute: (params) => {
const { text, priority = "medium" } = params;
const newItem = { id: Date.now(), text, priority, done: false };
todoApp.addItem(newItem);
todoApp.renderList();
return {
content: [{ type: "text", text: "Added task: " + text }]
};
}
});
