web-mcp

WebMCP Implementation Guide

WebMCP lets web pages expose structured tools to AI agents running in the browser. Instead of building separate backend MCP servers, you reuse existing client-side code — the tools live where your UI lives.

  User + Agent
       |
  [ Browser ]
       |
  document.modelContext.registerTool()
       |
  [ Your Web Page JS ]

Two Approaches

Approach	API	When to Use
Imperative	document.modelContext.registerTool()	Custom logic, navigation, state management, complex tools
Declarative	toolname / tooldescription HTML attributes on <form>	Existing forms you want agents to fill and submit

Both approaches can coexist on the same page.

Quick Start — Imperative Tool

await document.modelContext.registerTool({
  name: "add-todo",
  description: "Add a new item to the user's active todo list",
  inputSchema: {
    type: "object",
    properties: {
      text: { type: "string", description: "The text content of the todo item" }
    },
    required: ["text"]
  },
  async execute({ text }) {
    await addTodoItemToCollection(text);
    return {
      content: [{
        type: "text",
        text: `Added todo item: "${text}" successfully.`
      }]
    };
  }
});

Quick Start — Declarative Form Tool

<form toolname="support_request"
      tooldescription="Submit a request for customer support."
      toolautosubmit>
  <label for="name">Name</label>
  <input type="text" name="name">

  <label for="issue">Issue type</label>
  <select name="issue"
    toolparamdescription="Determines what team handles the request.">
    <option value="returns">Return my purchase</option>
    <option value="shipping">Check package status</option>
    <option value="technical">Get website help</option>
  </select>

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

The browser auto-generates a JSON Schema tool definition from the form structure. The agent can fill and submit it.