How to Set Up WebMCP ?

Published on mcpfy.ai · Category: AI Agents & Web Standards · Reading time: ~8 minutes

---

WebMCP is one of the most exciting new tools available to web developers building for the age of AI agents — and setting it up is simpler than you might expect. If you have not yet read our introduction to WebMCP, start there first. This guide picks up where that one leaves off: we will walk through enabling WebMCP in Chrome, inspecting your registered tools, and implementing both the declarative HTML approach and the imperative JavaScript approach in a real React or Next.js app.

By the end, your product will be capable of exposing structured, schema-validated tools that AI agents can call directly — without scraping your DOM or guessing at your UI. Furthermore, you will have a rollout plan that takes you from zero to production-ready in three clear phases.

What you need: A Chrome Canary or Chrome Beta install, five minutes to flip some flags, and a web project you want to make agent-ready. No backend changes required to get started.

---

Table of Contents

1. Step 0 — Enable WebMCP in Chrome
2. Approach A — Declarative WebMCP with HTML Forms
3. Approach B — Imperative WebMCP in React and Next.js
4. Returning Clean Results to the Agent
5. A Practical WebMCP Rollout Plan
6. Where MCPfy Fits In
7. Frequently Asked Questions

---

Step 0 — Enable WebMCP in Chrome

Before you can register or test any WebMCP tools, you need a Chrome build that supports the early preview and the right flags turned on. This is a one-time setup that takes under five minutes.

Show Image

1 — Install a supported Chrome build

WebMCP is currently available as an early preview program through Chrome for Developers. Most experimentation happens in Chrome Canary or Chrome Beta. If you do not already have one of these installed, download them from Google’s official Chrome downloads page.

Canary gets the very latest flags first, though it is less stable. Beta, by contrast, is more reliable and still ships experimental features quickly. For most developers, therefore, Chrome Beta is the safer choice for WebMCP experimentation.

2 — Enable the WebMCP flag

Once you have the right Chrome build installed, open it and navigate to:

chrome://flags

Search for “WebMCP” or “model-context” — the exact wording varies slightly between Chrome builds. When you find it, set it to Enabled. Some builds additionally require you to enable “Experimental Web Platform Features”, so check for that too while you are in the flags panel.

After enabling the flags, restart Chrome when prompted. The flags will not take effect until you do.

3 — Install the Model Context Tool Inspector

The Model Context Tool Inspector Chrome extension is an essential companion during WebMCP development. Once installed, it adds a dedicated panel to Chrome DevTools that shows you every tool currently registered on the page — including the name, description, input schema, and a way to fire test calls manually.

Without this extension, you are developing blind. With it, however, you can immediately see whether your declarative HTML attributes or imperative registerTool() calls are working as expected. Install it before writing a single line of WebMCP code.

---

Approach A — Declarative WebMCP with HTML Forms

Declarative WebMCP is the fastest route to making any page agent-ready. You add a small set of custom attributes to your existing HTML forms — no JavaScript, no libraries, no build step required. As a result, Chrome’s WebMCP layer automatically picks up those attributes and exposes them as callable, schema-validated tools.

This approach is ideal for static pages, marketing sites, contact forms, booking enquiries, and any scenario where your primary user action is a straightforward form submission.

How it works

Add toolname and tooldescription to a <form> element. Then add toolparamdescription to each <input> or <textarea> field. That is the entire API surface. The browser does the rest.

Example — a customer support contact form

html

<form
  toolname="contact_support"
  tooldescription="Send a support request to the team"
  action="/api/contact"
  method="POST"
>
  <input
    name="name"
    type="text"
    required
    toolparamdescription="Full name of the user"
  />

  <input
    name="email"
    type="email"
    required
    toolparamdescription="Email address to respond to"
  />

  <input
    name="subject"
    type="text"
    required
    toolparamdescription="Short summary of the issue"
  />

  <textarea
    name="message"
    required
    toolparamdescription="Detailed description of the issue"
  ></textarea>

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

Once Chrome picks this up, an AI agent sees a contact_support tool with a fully typed input schema — name, email, subject, and message — all documented and ready to call. The agent does not need to find the form on the page, read the labels, or guess what each field means. Consequently, the interaction is deterministic every time.

Important: Write your tooldescription and toolparamdescription values the way you would write API documentation — specific, action-oriented, and unambiguous. “Full name of the user” is better than “name”. “Email address to respond to” is better than “email”. The more precise your descriptions, therefore, the more reliably agents will call your tool correctly.

---

Approach B — Imperative WebMCP in React and Next.js

For dynamic single-page applications, declarative HTML is not enough. Routes change, components mount and unmount, and the available tools need to update accordingly. Imperative WebMCP registration, however, handles all of this cleanly through JavaScript — making it the right choice for any component-based app.

Imperative WebMCP uses navigator.modelContext to register and manage tools programmatically. The key methods are registerTool(), unregisterTool(), provideContext(), and clearContext(). Furthermore, because these are tied to component lifecycle hooks, tools appear and disappear exactly when the relevant UI does — giving agents precisely the right context at every point in the user’s journey.

1 — Create a reusable WebMCP helper

Rather than calling navigator.modelContext directly throughout your codebase, start by wrapping it in a small utility file. This approach keeps your components clean and, moreover, provides a safe browser guard for environments where WebMCP is not available.

typescript

// webmcp.ts
type JSONSchema = Record<string, any>;

type Tool = {
  name: string;
  description: string;
  inputSchema: JSONSchema;
  execute: (args: any) => Promise<any> | any;
};

function getModelContext(): any | null {
  // @ts-ignore
  return typeof navigator !== "undefined" ? (navigator as any).modelContext : null;
}

export function registerTool(tool: Tool) {
  const mc = getModelContext();
  if (!mc) return;
  mc.registerTool({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.inputSchema,
    execute: tool.execute,
  });
}

export function unregisterTool(name: string) {
  const mc = getModelContext();
  if (!mc) return;
  mc.unregisterTool(name);
}

export function replaceToolContext(tools: Tool[]) {
  const mc = getModelContext();
  if (!mc) return;
  mc.provideContext({
    tools: tools.map((t) => ({
      name: t.name,
      description: t.description,
      inputSchema: t.inputSchema,
      execute: t.execute,
    })),
  });
}

export function clearToolContext() {
  const mc = getModelContext();
  if (!mc) return;
  mc.clearContext();
}

The getModelContext() guard is important. It ensures your code does not throw errors in browsers that do not yet support WebMCP — which, in 2025, is still most of them outside Chrome Canary and Beta. In other words, this helper makes your WebMCP implementation fully progressive-enhancement-safe.

2 — Register tools per page or route

With your helper in place, the pattern is simple: call replaceToolContext() when a component mounts, and clearToolContext() when it unmounts. Consequently, the agent always sees only the tools relevant to the current page.

Here is a complete example for a flight search page:

typescript

// SearchFlightsPage.tsx
import { useEffect } from "react";
import { replaceToolContext, clearToolContext } from "./webmcp";

export default function SearchFlightsPage() {
  useEffect(() => {
    replaceToolContext([
      {
        name: "search_flights",
        description: "Search available flights by origin, destination, and travel date",
        inputSchema: {
          type: "object",
          properties: {
            from: { type: "string", description: "Origin airport or city" },
            to:   { type: "string", description: "Destination airport or city" },
            date: { type: "string", description: "Travel date in YYYY-MM-DD format" },
          },
          required: ["from", "to", "date"],
        },
        execute: async ({ from, to, date }) => {
          const res = await fetch(`/api/flights?from=${from}&to=${to}&date=${date}`);
          const data = await res.json();
          return { flights: data };
        },
      },
    ]);

    return () => clearToolContext();
  }, []);

  return (
    <div>
      <h1>Search Flights</h1>
      {/* normal UI */}
    </div>
  );
}

When the user navigates away from this page, clearToolContext() fires and the search_flights tool disappears from the agent’s view. When the results page mounts, meanwhile, you call replaceToolContext() again with a different set of tools — for example, filter_results, sort_by_price, and select_flight. The agent therefore always has precisely the right capabilities for wherever it is in the application.

This “tools change as the page changes” pattern is one of WebMCP’s biggest wins over traditional MCP servers, where all tools are always loaded regardless of context.

---

Returning Clean Results to the Agent

Whether you use declarative or imperative WebMCP, your tool’s execute function should always return structured, deterministic output. Treat every tool call like a real API call — not a UI side effect.

This means your responses should clearly signal success or failure:

typescript

// ✅ Success
return { status: "success", message: "Support ticket submitted successfully." };

// ❌ Validation failure
return { status: "error", reason: "validation_error", field: "email", message: "Email address is required." };

// ❌ Rate limited
return { status: "error", reason: "rate_limited", message: "Too many requests. Please try again in 60 seconds." };

Agents that call your WebMCP tools need predictable outputs to make decisions. If your execute function throws unhandled errors or returns inconsistent shapes, the agent cannot reliably determine what happened or what to do next. Consequently, structured error responses are not optional — they are a core part of making your tools genuinely useful.

Pro Tip: Use a consistent response envelope across all your tools — always { status, message, ...data } or similar. This makes it far easier for agents to handle your tools generically, without needing to learn the specific shape of each one.

---

A Practical WebMCP Rollout Plan

Show Image

Trying to make your entire app WebMCP-ready at once is a mistake. Instead, roll out in three phases — starting with low-risk tools and expanding as you build confidence and observability.

Phase 1 — Start with read-only tools

Begin with tools that only read or search data. These are low-risk because they cannot cause irreversible state changes. Good candidates for Phase 1 include:

• search_* — product search, flight search, location search
• list_* — list categories, list available slots, list items in cart
• get_* — get product details, get order status, get pricing
• apply_filters — filter search results by criteria

These tools immediately reduce the need for agents to parse your DOM. Furthermore, they are safe to ship quickly because a failed call simply returns an empty result, not a corrupted transaction.

Phase 2 — Add transactional tools with guardrails

Once Phase 1 is stable and you have baseline data on tool call patterns, introduce actions that modify state. These require more care, however, because they have real consequences:

• add_to_cart
• submit_form
• checkout
• issue_refund

For each transactional tool, add explicit guardrails: confirmation steps before irreversible actions, rate limits on sensitive endpoints, permission scopes so agents cannot call admin tools on user sessions, and audit logs so you can trace every agent-initiated action.

Phase 3 — Add observability

Do not ship Phase 1 or Phase 2 blind. From the start, instrument your tools to track:

• Tool call frequency — which tools are agents using most?
• Failure reasons — are calls failing on schema validation, auth, or business logic?
• Time-to-complete — how long does each tool flow take from first call to task completion?
• Drop-off points — where do agent sessions abandon after a “confirmation required” step?

This data is invaluable for iterating on tool descriptions, fixing schema issues, and prioritizing which tools to build next. In other words, observability turns WebMCP from an experiment into a production feature you can actually improve over time.

---

Where MCPfy Fits In

WebMCP makes your web surface agent-ready. That is a significant step — but it is only one layer of what a real production agent stack needs.

In practice, most products also need:

• Backend MCP servers for deeper, authenticated data access beyond what WebMCP can safely expose
• Policies and scopes to control which agents can call which tools under which conditions
• Cross-tool observability to understand how agents move across your tool ecosystem
• Reliability analytics to surface which tools fail, where they fail, and why

That is precisely the layer MCPfy is building: hosting, observability, and governance for agent tool ecosystems — including WebMCP-powered experiences. Whether you are just starting with declarative HTML forms or running a full imperative tool suite across a complex React app, MCPfy is designed to give you the visibility and control that WebMCP alone does not provide.

---

Frequently Asked Questions About WebMCP Setup

Do I need Chrome Canary specifically, or will Chrome Beta work?

Both work for WebMCP experimentation. Chrome Canary gets new flags first, however, it is less stable. Chrome Beta is therefore the recommended choice for most developers — it ships WebMCP features quickly and is reliable enough for sustained development work.

Can I use WebMCP without React or Next.js?

Yes. The declarative HTML approach requires no JavaScript framework at all. The imperative approach uses navigator.modelContext directly, which is a browser API — so it works with any framework or plain JavaScript. The webmcp.ts helper shown above is a React-friendly wrapper, but adapting it to Vue, Svelte, or vanilla JS is straightforward.

What happens in browsers that do not support WebMCP?

Nothing breaks. The getModelContext() guard in the helper returns null in unsupported browsers, and all the exported functions return early without throwing. WebMCP is consequently a pure progressive enhancement — invisible to users on unsupported browsers, powerful for agents on supported ones.

Should I use declarative or imperative WebMCP?

Use declarative mode for static pages and simple form-based interactions. Use imperative mode for any page with routes, state, or dynamic UI. Many production apps will use both — declarative for marketing pages and contact forms, imperative for the core product experience.

How do I know my tools are registering correctly?

Open Chrome DevTools and look for the Model Context Tool Inspector panel. It shows every tool currently registered on the page, its full input schema, and lets you fire test calls manually. If a tool is not showing up there, check that your Chrome flag is enabled and that you are running on a supported Chrome build.

Can agents call WebMCP tools without user permission?

WebMCP operates within the browser’s existing security model. Tools run in the page’s origin context, subject to the same CORS, auth, and permission rules as any other request from that page. However, as you move into Phase 2 with transactional tools, adding explicit confirmation steps and rate limits is strongly recommended regardless.

---

Next Steps

You now have everything you need to go from zero to a working WebMCP implementation:

1. Install Chrome Canary or Beta and enable the WebMCP flag at chrome://flags.
2. Add the Model Context Tool Inspector extension to Chrome DevTools.
3. Start with Approach A on your highest-value form — your contact page, your primary search, your booking flow.
4. When you are ready for dynamic routes, scaffold the webmcp.ts helper and wire it into your React components with replaceToolContext and clearToolContext.
5. Follow the three-phase rollout plan — read-only first, then transactional, then observability.

Coming up in Part 3: Advanced WebMCP patterns — authenticated tool calls, multi-step agent flows, error handling strategies, and how to connect your WebMCP tools to a backend MCP server for deep data access.

---

Related topics: WebMCP setup, Chrome Canary WebMCP, navigator.modelContext, registerTool JavaScript, WebMCP React, WebMCP Next.js, AI agent tool registration, browser-native MCP, declarative WebMCP HTML, imperative WebMCP, model context protocol browser, agent-ready web app.

Published by MCPfy.ai — The resource for building agent-ready web products.