Skip to content
Blog
Updated November 2026

WebMCP Toolkit

Make your website agent-ready. Generate a document.modelContext.registerTool() call or an experimental declarative form, then check your code against the current spec draft.

Spec status (Nov 2026)

  • The API lives on document.modelContext. Chrome 150 and 151 still answer on navigator.modelContext with a deprecation warning; Chrome 152 removed it.
  • registerTool(tool, { signal, exposedTo }) returns a Promise. There is no unregisterTool(), provideContext() or clearContext(): abort the signal to unregister.
  • Annotations are readOnlyHint, consequentialHint, untrustedContentHint and debugging. MCP's openWorldHint, destructiveHint and idempotentHint are dropped, and title is a top-level field.
  • Declarative forms were taken out of the spec draft "for now" on October 8, 2026. Chromium still ships them experimentally, behind the same origin trial.
  • HTTPS only, and the tools Permissions Policy defaults to self.

Read: WebMCP, six months laterThe spec on GitHub (opens in a new tab)

Generator

1-128 characters: letters, digits, underscore (_), hyphen (-) or period (.).

Shown to people in browser UI. A top-level title (or tooltitle), never annotations.title.

Annotations (imperative JS; all default to false)

Leave it off for payments, deletions, messages and bookings.

Parameters
// WebMCP imperative API, spec draft webmachinelearning/webmcp@6838130
// (Oct 27, 2026). HTTPS only. Chrome 152+ exposes it on document.modelContext only.
if ("modelContext" in document) {
  const controller = new AbortController();

  const tool = {
    name: "search_products",
    title: "Search products",
    description: "Search the product catalog by keyword, category, or price range",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search keyword"
        },
        category: {
          type: "string",
          description: "Product category filter"
        },
        max_price: {
          type: "number",
          description: "Maximum price in USD"
        }
      },
      required: ["query"]
    },
    // "= {}": Chromium before 153 called execute() with only the input.
    async execute(input, { signal } = {}) {
      // The browser doesn't check input against inputSchema, so validate here.
      if (typeof input.query !== "string" || input.query.trim() === "") {
        return { error: "query is required and must be a non-empty string." };
      }
      if (input.category !== undefined && typeof input.category !== "string") {
        return { error: "category must be a string." };
      }
      if (input.max_price !== undefined && typeof input.max_price !== "number") {
        return { error: "max_price must be a number." };
      }
      try {
        const response = await fetch("/api/search_products", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(input),
          signal
        });
        if (!response.ok) {
          return { error: "Request failed with status " + response.status };
        }
        return await response.json();
      } catch (err) {
        // Cancelled by the agent or the user: let the call end.
        if (signal?.aborted) throw err;
        // A thrown error reaches the agent as an OperationError with no
        // message, so return errors as values the agent can read.
        return { error: err instanceof Error ? err.message : String(err) };
      }
    },
    annotations: {
      readOnlyHint: true
    }
  };

  // await inside try/catch also covers Chromium 149-150, where registerTool()
  // threw synchronously instead of returning a Promise.
  (async () => {
    try {
      await document.modelContext.registerTool(tool, { signal: controller.signal });
    } catch (err) {
      // Rejects on an invalid or duplicate name, or an inputSchema that
      // can't be serialized.
      console.warn("WebMCP: could not register search_products", err);
    }
  })();

  // There is no unregisterTool(). To remove the tool (route change,
  // component unmount), abort the signal it was registered with:
  // controller.abort();
}

Validator

Paste WebMCP code on the left to see validation results.

Quick Reference

Imperative API

document.modelContext.registerTool(tool, options)

nameUnique id: 1-128 of A-Z a-z 0-9 _ - .required
titleHuman-readable label for browser UIoptional
descriptionWhat the tool does and when to use itrequired
inputSchemaJSON Schema for the input (not enforced; validate yourself)optional
execute(input, { signal }) => result; return errors as valuesrequired
annotationsreadOnlyHint, consequentialHint, untrustedContentHint, debuggingoptional
{ signal }Second argument to registerTool(); abort it to unregisteroptional
{ exposedTo }Origins of other frames that may use the tooloptional

Declarative APIExperimental · Chromium only

Removed from the spec draft on October 8, 2026; still in Chromium's origin trial. toolparamtitle is gone.

toolnameTool name: 1-128 of A-Z a-z 0-9 _ - .<form>
tooldescriptionWhat the tool does and when to use it<form>
tooltitleHuman-readable title for browser UI<form>
toolautosubmitAgent may submit without the user (safe forms only)<form>
nameParameter key in the input schema<input>
toolparamdescriptionParameter description (also on <fieldset>); else the <label> text, then aria-description<input>
respondWith()When event.agentInvoked, answer the agent without navigating; call preventDefault() firstSubmitEvent
:tool-form-activeStyle the form (and :tool-submit-active its button) while an agent uses itCSS