webmcp

WebMCP

The API Surface

WebMCP exposes a page's capabilities to an in-browser agent through document.modelContext. A tool is registered with a name, a description, an input schema, and a handler:

const controller = new AbortController();

document.modelContext.registerTool(
  {
    name: "add_to_cart",
    description: "Adds a product to the shopping cart by SKU.",
    inputSchema: { type: "object", properties: { sku: { type: "string" } }, required: ["sku"] },
    async execute({ sku }) {
      await cart.add(sku);
      return { content: [{ type: "text", text: `Added ${sku} to cart.` }] };
    },
  },
  { signal: controller.signal },
);

// later, to unregister:
controller.abort();

The handler's result must be JSON-serializable. The current draft defines ToolExecuteCallback as Promise<any>; an MCP content envelope is an application convention, not the required browser return type. executeTool() resolves to the serialized result. Rejections and serialization failures can reject execution; expected domain errors can use a documented JSON object with a recovery message. An agent discovers tools with getTools() and tracks toolchange events. Registration should last only as long as the view state that makes the tool usable.

Verified against the WebMCP draft dated 4 September 2026. This is an evolving community draft, not a W3C standard. Feature-detect the actual browser API and keep it behind an adapter; do not infer availability from a version number alone. The global examples here belong in that adapter.

One Tool, One Function

Wrong -- a single tool with a mode switch covering unrelated operations:

document.modelContext.registerTool({
  name: "manage_booking",
  description: "Search, filter, or book reservations depending on mode.",
  inputSchema: {
    type: "object",
    properties: { mode: { enum: ["search", "filter", "book"] }, params: { type: "object" } },
  },
  async execute({ mode, params }) {
    // agent picks the wrong mode -> silently runs the wrong branch, no error surfaces
  },
});