How WebMCP Works: A Complete Guide

Chrome's experimental WebMCP standard, documented as of September 16, 2026, lets web pages expose structured tools to browser agents through the imperative `document.modelContext.registerTool()` API or HTML form annotations, with each tool defining its inputs via JSON Schema. WebMCP is available to deployed sites through the Chrome WebMCP origin trial starting in Chrome 149, or locally via the `chrome://flags/#enable-webmcp-testing` flag, and requires an origin-isolated document, excluding pages that use legacy `document.domain` relaxation or are served with `Origin-Agent-Cluster: ?0`. The standard differs from MCP in that MCP connects AI applications to backend services while WebMCP connects agents to the live website in the current tab.

How WebMCP Works: A Complete Guide Learn how WebMCP works end to end, from exposing tools with JavaScript or HTML to discovery, execution, state, and security with working examples. Authored by Nart Madi https://nartmadi.com Published on September 16, 2026 What WebMCP does WebMCP is a proposed web standard that lets a page expose structured tools to browser agents. A tool describes a specific action the site can perform and defines its inputs with a JSON Schema. The browser makes those tools discoverable to WebMCP-aware agents that can act on the page, so an agent can inspect what the site offers and call the right tool with structured arguments instead of guessing how to click through the interface. If you want the architectural distinction first, see WebMCP vs. MCP https://senro.ai/blog/webmcp-vs-mcp . MCP connects AI applications to backend services. WebMCP connects agents to the live website in the current tab. If your task depends on the open page and its state, WebMCP gives the agent a direct way to act on that page. Before you start WebMCP is currently experimental. To make WebMCP available on a deployed website without requiring visitors to enable a Chrome flag, join the Chrome WebMCP origin trial https://developer.chrome.com/origintrials/ /register trial/4163014905550602241 , available from Chrome 149. For local development, enable chrome://flags/ enable-webmcp-testing and relaunch Chrome. WebMCP also requires an origin-isolated document, meaning the page’s origin must remain fixed while its tools are available. Sites that use legacy document.domain origin relaxation, including pages served with Origin-Agent-Cluster: ?0 , cannot use the WebMCP APIs. This guide reflects Chrome's experimental WebMCP implementation as of September 16, 2026. The API is still evolving. How the WebMCP flow works At a high level, WebMCP interactions follow this sequence. 1. The page registers or exposes tools with JavaScript or with HTML annotations 2. The browser makes those tools discoverable to WebMCP-aware agents that can act on the page 3. The agent inspects the available tools and their descriptions and schemas 4. The agent chooses the tool that matches the user intent 5. The agent supplies arguments that satisfy the tool schema 6. The browser invokes the tool, which may execute JavaScript, populate a form, or update page state 7. The tool returns a result to the agent or causes a browser action such as navigation The page controls what is available. The browser controls visibility and origin rules. The agent decides what to call and when. The imperative API Chrome's current imperative API documentation https://developer.chrome.com/docs/ai/webmcp/imperative-api uses document.modelContext . You register imperative tools with JavaScript and can create a wide range of tool logic for your site. The core method is document.modelContext.registerTool . It takes the following fields: - name identifies the tool. Keep it short and descriptive so the model can distinguish it from nearby tools - description explains what the tool does and when to use it. The model relies on this text to choose correctly - inputSchema defines the tool inputs with JSON Schema - execute runs when the agent calls the tool and receives the parsed arguments - annotations is optional and provides hints about safety and side effects The following example registers a tool that searches a product catalog. It includes structured inputs, an enum, and a concise description that helps the model choose it. Install webmcp-types https://www.npmjs.com/package/webmcp-types if you want TypeScript typings for document.modelContext . The declarative API The declarative API https://developer.chrome.com/docs/ai/webmcp/declarative-api turns an existing HTML form into a tool without writing an execute function. You annotate the form and its fields and the browser translates the form into a tool definition for the agent. Add the following attributes to the form element: - toolname defines the tool name - tooldescription defines what the tool does Add the following attributes to individual fields when you need more precise parameter descriptions: - toolparamdescription adds a description for a single field in the generated schema If you remove toolname or tooldescription , the tool is unregistered. Use toolautosubmit when you want the browser to submit and navigate automatically when the agent calls the tool. Without it, the agent populates the fields and the user submits manually. The browser exposes this form as if you had registered an imperative tool with the same name, description, and derived inputSchema . The agent sees the same kind of structured metadata. Use the declarative API when your action already maps to a form submission and you want the least code. Use the imperative API when you need custom logic, when you read or mutate application state, when you call an internal API, or when the action does not map to a single form. Many sites use both. Declarative tools also support agent-aware events and styling. The browser fires toolactivated when the agent focuses and populates the form and toolcancel when the agent cancels or the form resets. You can style the active states with :tool-form-active and :tool-submit-active . The SubmitEvent adds agentInvoked and respondWith Promise so you can return a result to the model after calling preventDefault . Tool schemas A well-designed schema is essential for reliable tool calls. The schema tells the model what arguments exist, what types they use, and what values are valid. WebMCP uses JSON Schema for inputSchema , so the same modeling concepts apply. Use the following building blocks for tool inputs: - type defines the basic type for a property such as string , number , boolean , or object . Use specific types so the model does not send freeform text where you expect a number - required lists the properties the agent must supply - enum limits a string to a small set of valid values. Use it for categories, statuses, and other closed sets - description explains what a parameter means and how to choose it. This text directly affects whether the model sends the right value - oneOf and const can express richer constraints when you need labeled constants, as shown in the imperative docs for time ranges The example below shows a more complete schema for inspecting a product. It uses a required string, an enum, and concise descriptions for each parameter. Parameter descriptions give the model the semantic context it needs to choose the right value consistently. A description that says what the field expects and when to use it reduces wrong arguments and follow-up calls. Chrome's WebMCP best-practices guide https://developer.chrome.com/docs/ai/webmcp/best-practices makes the same point and recommends positive language that describes what the tool does rather than what it should not do. Tool annotations Annotations are optional hints that describe how a tool behaves. Chrome currently recommends them as safety and behavior hints for agents and browsers. They do not change what the tool does, but they help the surrounding system decide when to ask for confirmation and how to treat the output. Chrome documents the following hints: - readOnlyHint indicates that the tool only reads information and does not change application or system state. Set it to true for search, lookup, and retrieval tools - consequentialHint indicates that the tool causes a significant or non-reversible action such as booking, purchasing, transferring money, or deleting data. Set it to true when the agent or browser should confirm with the user before execution - untrustedContentHint indicates that the tool output may contain user-generated content or external data that the tool author does not control. Set it to true for reviews, comments, or other untrusted sources so agents and clients can apply heightened security handling Set readOnlyHint: true for tools that only retrieve data. Use consequentialHint sparingly and only for actions where a mistake has real cost. Set untrustedContentHint: true when the tool returns untrusted or externally controlled content. Tool lifecycle WebMCP tools are tied to the page lifecycle. They exist only while the page remains open and they should reflect what the user can actually do right now. You register a tool when it becomes useful and you unregister it when it no longer applies. Chrome supports AbortSignal for this. Pass a signal when you register and call abort to remove the tool. As of Chrome 153, unregistering does not cancel an execution that is already in flight, which makes lifecycle handling safer in component frameworks. Use the signal that execute receives as its second argument to handle cancellation gracefully. Pass it to fetch or other long-running work so the tool can stop when the user or agent cancels. This avoids wasted work and resource leaks. Frames can listen for the toolchange event on document.modelContext to know when the set of available tools has changed. This is useful when tools appear or disappear as page state changes, such as when a user logs in, navigates, or empties a cart. Treat tools as dynamic, not static. Register what is valid for the current state and remove what is not. Discovering tools Use document.modelContext.getTools to retrieve the tools the calling document can access. The method is async and returns tools in alphabetical order. By default it returns only same-origin tools from the calling document and other same-origin documents in the frame tree. The returned metadata includes the following fields: - name and description - inputSchema - annotations when present - origin , title , and the owner window To retrieve tools from a cross-origin iframe, pass the hosting origins explicitly with fromOrigins . Only secure origins are supported, and the tool must have been exposed to your origin. The next section explains that opt-in. Discovering tools is useful for debugging, for page agents that list available actions, and for tests that verify what the page actually exposes in a given state. Executing tools Use document.modelContext.executeTool to run a tool you discovered with getTools . Pass the tool object and a JavaScript object for arguments that can be serialized to JSON. The method returns the tool result or null when the tool triggers a navigation. You can cancel a pending execution with AbortSignal as well. Stringified JSON arguments are deprecated from Chrome 155 onward. Pass a plain object instead of a string. If you still have stringified calls, update them to objects so they keep working. Cross-origin tools and iframes WebMCP is gated by permissions policy and by explicit origin controls. The tools permissions policy defaults to self , so cross-origin iframes cannot register tools until the parent delegates access. Add allow="tools" to the iframe element to grant that permission. Even with the permission granted, a tool is not visible to a cross-origin document unless the tool author exposes it. Set exposedTo when you register to list the secure origins that may view and execute the tool. The caller must also request the origin explicitly with fromOrigins in getTools . Both sides must agree. This opt-in on both ends prevents a site from leaking sensitive capabilities to a page that embeds it and prevents a parent page from seeing tools it did not ask for. Only expose tools to origins you trust, especially when those tools read user data or perform writes on behalf of the user. Framework support React applications can use the experimental usewebmcp https://www.npmjs.com/package/usewebmcp package to register tools with hooks tied to a component's lifecycle. It also provides schema-driven type inference and local execution state. Angular also offers experimental WebMCP support https://angular.dev/ai/webmcp . Angular applications can connect tools to dependency injection and expose Signal Forms as WebMCP tools. These integrations can reduce lifecycle boilerplate, but they use the same underlying concepts. The page still exposes named tools with descriptions, schemas, execution logic, and state-dependent availability. State and context WebMCP is useful because it runs inside the live page. Unlike a backend service that does not inherently share the current page context, a WebMCP tool can directly use the current route, authenticated session, and application state. This changes what you can build. You can expose tools that operate on what is actually present, such as: - the current route and query parameters that define what the user is viewing - the authenticated session that determines what data and actions are allowed - the cart or application state that reflects selections the user already made - the dynamic availability of tools that depends on that state For example, a checkout tool should only be registered when the cart contains items. A filter tool should reflect the filters that are valid for the current catalog view. A lookup tool should return data for the entity the user is actually looking at. By keeping registration tied to live state, you keep the agent from calling tools that make no sense in context and you make the remaining tools easier to choose correctly. Security WebMCP tools run in the page with the same access the page has. That makes security part of the tool design, not an afterthought. Plan for the following risks from the start. Prompt injection is the first concern. LLMs process instructions, user content, and tool output within the same context, which makes them vulnerable to indirect prompt injection. Validate and constrain external data, preserve it as data rather than instructions, and mark untrusted outputs with untrustedContentHint . Do not treat sanitization alone as sufficient protection against prompt injection. Review Chrome's WebMCP tool security guidance https://developer.chrome.com/docs/ai/webmcp/secure-tools when tools process external or user-generated content. Consequential actions need a clear boundary. Any tool that books, purchases, deletes, or otherwise creates a real-world effect should set consequentialHint so the browser or agent can require user confirmation. Do not rely on the model to infer risk from the description alone. Untrusted content needs explicit handling. Reviews, comments, marketplace listings, and other external sources can contain instructions or misleading claims. Treat those outputs as data, not directives, and keep the formatting simple so the agent can use the result without reinterpreting it. Origin exposure needs a deliberate choice. Only set exposedTo for secure origins you trust with the data or action. A read-only tool such as getFavoriteProducts can leak personal information. A write tool such as postComment can act on behalf of the user. Both need the same care as any cross-origin permission. Separately, concise descriptions and outputs reduce context pressure and improve reliability. Chrome recommends the following budgets as guidance and notes that they may evolve to enforced limits: - 500 characters per tool description - 150 characters per parameter description - 30 characters per tool name and parameter name - 1500 characters per individual tool output Staying inside these budgets keeps tools inside the context window and reduces the chance that the agent misses a key instruction. End-to-end example The following example carries one scenario through the full flow. A user wants to search for products, inspect a product, and add it to the cart. The page exposes three tools that cover the task and that reflect live state. The agent uses the tools in sequence and the page updates its state after each call. 1. The user asks to find running shoes under a budget. The agent calls search products with a query, category, and maximum price and the page returns a short list 2. The user asks for details on one result. The agent calls get product with the identifier from the previous output and the page returns the product record 3. The user asks to add it to the cart. The agent calls add to cart with the product identifier and quantity and the page updates the cart and returns a confirmation that reflects the new item count Each tool is small, named clearly, and depends on live state. search products reads the catalog. get product reads a single record. add to cart mutates the session, while an eventual purchase tool would be consequential because it creates a real-world transaction. The page can keep a checkout tool unregistered while the cart is empty, then register it after add to cart succeeds. What happens after implementation A valid tool does not guarantee reliable agent behavior. The schema can be correct and the function can work, yet the agent can still choose the wrong tool, send the wrong arguments, or behave differently across models, languages, and page states. Implementation is the first step, not the final check. The next step is to verify that agents actually use these tools the way you expect. That means testing tool selection, parameter accuracy, and task completion across a large set of cases and conditions before you rely on the tools in production. Senro https://senro.ai/ evaluates WebMCP tool selection, parameter accuracy, and task completion across models, languages, and test cases, then monitors tool behavior in production. Learn more about Senro https://senro.ai/about . Frequently asked questions What is WebMCP? WebMCP is a proposed web standard that lets a page expose structured tools to browser agents. The page defines tools with JavaScript or HTML annotations and the browser makes them discoverable in the current tab. How do I expose a WebMCP tool? Use the imperative API with document.modelContext.registerTool for custom logic, or add toolname and tooldescription to an HTML form for the declarative API. Both expose tools the browser can share with agents. Do WebMCP tools work across origins? By default tools are same-origin. For cross-origin iframes, the parent must allow tools and the tool must list the target origin in exposedTo . The caller must also request that origin with fromOrigins in getTools .