WebMCP Guide: Make Your Website Agent-Ready

WebMCP is a proposed browser standard that lets a website expose structured tools to compatible AI agents. Instead of making an agent rediscover a page by reading pixels, locating buttons, and guessing form intent, the site can describe an action, its inputs, and its expected behavior directly.

This guide explains what WebMCP does, how its declarative and imperative APIs differ, how to design a safe first tool, and how to test the application contract before involving a language model. It also separates what is documented by Chrome from what is still an informed implementation recommendation.

What problem does WebMCP solve?

Browser agents can already operate many websites. They inspect the DOM, accessibility tree, screenshots, and visible controls, then simulate mouse and keyboard actions. That approach is useful, but it forces the agent to infer capabilities that the application already knows.

A product search page, for example, knows that a price field accepts a number, that a rating filter has a finite set of values, and that an “Add to cart” action changes state. A structured tool can expose those facts explicitly. The agent receives a narrower contract instead of reconstructing the application from its presentation layer.

Chrome’s documentation describes WebMCP as a proposed web standard that supports tool discovery, JSON Schemas, and shared page state. It is related to MCP, but it runs at the website-and-browser boundary rather than acting as a general-purpose remote server.

WebMCP and MCP are related, not interchangeable

The practical architecture may use both. A commerce site could expose a browser tool for the current cart while also operating an authenticated MCP server for inventory or order support. Choose based on the trust boundary and where the authoritative business logic belongs.

Choose the right WebMCP API

Declarative API: annotate an existing form

The declarative API is the lowest-friction entry point when a task already maps to a semantic HTML form. Add a tool name and description to the form, then improve the generated parameter descriptions with labels and optional annotations.

<form toolname="search_posts"
      tooldescription="Search published articles by topic."
      action="/search">
  <label for="query">Topic or keyword</label>
  <input id="query" name="query" type="search" required
         toolparamdescription="A topic, phrase, or question to search for.">
  <button type="submit">Search</button>
</form>

Chrome’s reference describes toolname and tooldescription as the required registration attributes. Fields become tool parameters, and semantic labels help form the input schema. A site can choose whether the user must still click Submit or whether an agent invocation may submit automatically.

Imperative API: register a dynamic function

Use the imperative API when the action is not naturally represented by a static form, when the tool needs dynamic registration, or when it should reuse an application function that already returns structured data.

if (document.modelContext) {
  await document.modelContext.registerTool({
    name: "get_article_outline",
    description: "Return the outline for a published article by slug.",
    inputSchema: {
      type: "object",
      properties: {
        slug: { type: "string", description: "Published article slug" }
      },
      required: ["slug"]
    },
    execute: async ({ slug }) => {
      const article = await getPublishedArticle(slug);
      if (!article) throw new Error("Published article was not found.");
      return { title: article.title, sections: article.sections };
    }
  });
}

Feature-detect the API. If document.modelContext is unavailable, the human interface should continue to work normally. Do not ship a fake fallback that makes a test pass while hiding the absence of the browser implementation.

A safe first implementation workflow

1. Start with a read-only action. Choose a task such as searching published content, filtering a catalog, or retrieving a public status. Avoid payments, account changes, deletion, and other irreversible mutations for the first experiment.
2. Write the contract before the code. Define one purpose, a precise name, a human-readable description, input types, required fields, and a predictable output. Avoid overlapping tools that leave the agent to choose between near-duplicates.
3. Reuse the application’s trusted function. The tool should call the same validation and business logic used by the visible UI. Do not create a second implementation that can drift from the product.
4. Validate in code. Schemas help an agent understand inputs, but server and application code must still enforce authorization, range checks, ownership, rate limits, and state transitions.
5. Keep the user in control. For sensitive actions, show what will happen, preserve a visible confirmation step, and make cancellation or reset possible. A tool description is not a security boundary.
6. Register only when useful. Expose tools in the page states where they are valid, and remove or disable them when the underlying capability is no longer available.

Tool descriptions are part of the product interface

An agent chooses among tools using the contract it can see. Names and descriptions therefore need the same care as labels, button text, and API documentation.

Use verbs that state the action. Explain when the tool is useful. Accept natural input where possible instead of forcing the model to perform unnecessary transformations. Keep strict validation in code and return errors that explain how a valid retry can be made.

Security: treat tools as privileged capabilities

The MCP specification emphasizes user consent, control over shared data, access controls, and caution around arbitrary tool execution. The same principles apply here. A tool that can change real state should have an explicit trust model and should not rely on an agent’s interpretation of its description.

• Require the user to confirm purchases, deletions, permission changes, and other consequential actions.
• Enforce authorization and ownership checks in application code, not only in the UI.
• Return minimal data. Do not expose secrets, hidden fields, or unrelated account records.
• Protect against prompt injection in page content. Treat product text, comments, and retrieved documents as untrusted data.
• Log tool activation, actor context, validation failures, and resulting state changes where appropriate.
• Rate-limit expensive or repeatable operations and return a useful error when a limit is reached.

Test the application before testing the agent

A reliable evaluation has two layers. First, test the deterministic application contract without a language model. Then test whether agents select and use the tools sensibly. Mixing both layers makes failures difficult to diagnose.

Layer 1: deterministic contract tests

const result = await searchPosts({ query: "MCP security" });
if (!Array.isArray(result.items)) throw new Error("Expected an item list");

await assertRejects(
  () => searchPosts({ query: "" }),
  "A non-empty query is required."
);

Cover valid input, missing fields, malformed values, empty results, repeated calls, rate limits, and failures in downstream services. For mutating tools, test authorization, duplicate requests, cancellation, and invalid state transitions.

Layer 2: agent evaluations

Test paraphrases and boundary cases. One successful prompt is not evidence that a tool is reliable. Measure whether the agent selects the correct tool, supplies valid arguments, respects confirmation requirements, and recovers from clear errors.

What WebMCP does not solve yet

WebMCP does not guarantee that an agent will discover your site, choose your tool, or complete a task correctly. There is no promise of search visibility, traffic, conversion, or compatibility with every browser or model. It also does not replace clean HTML, accessible forms, descriptive page titles, or conventional SEO.

Chrome’s documentation marks the work as experimental and subject to change. Origin trials are deliberately limited in duration and scope, so a production rollout should include feature detection, a rollback plan, and a way to remove or revise registrations without breaking the human experience.

For search, keep the fundamentals intact. Google describes crawling, rendering, and indexing as separate stages and recommends meaningful titles, canonical URLs, crawlable links, compatible code, and useful content. WebMCP is an interaction surface for agents; it is not a substitute for indexable information architecture.

Practical checklist for an agent-ready website

• Choose one low-risk, high-value task for the pilot.
• Use a semantic form or a small imperative tool with one clear purpose.
• Give the tool a specific verb-based name and a complete description.
• Define typed parameters and human-readable field descriptions.
• Feature-detect WebMCP and preserve the normal UI when it is unavailable.
• Reuse trusted validation and business logic.
• Keep sensitive actions behind user confirmation and authorization.
• Write deterministic contract tests before agent evaluations.
• Document the experimental status and plan for API changes.
• Continue investing in crawlable content, accessibility, and conventional SEO.

Conclusion

Sources and further reading

1. Chrome for Developers: WebMCP overview — overview, tool discovery, JSON Schemas, state, limitations, and demos.
2. Chrome for Developers: Declarative API — form annotations, parameters, submission behavior, events, and focus indicators.
3. Chrome for Developers: WebMCP best practices — tool strategy, naming, schemas, reliability, and evaluation guidance.
4. Chrome for Developers: WebMCP is available for early preview — published February 10, 2026; explains the early-preview scope and use cases.
5. Model Context Protocol specification — protocol concepts and security principles concerning consent, privacy, and tool safety.
6. Google Search Central: JavaScript SEO basics — crawling, rendering, indexing, canonical URLs, and crawlable links.
7. Chrome Developers: Origin trials — how experimental web-platform features are tested and the limitations of trial participation.

Related PromptSphere reading: Model Context Protocol: How AI Connects to Approved Tools and Data, AI Agent Evaluation Dataset: Build Before Production, and AI Agent Observability: Production Reliability.