WebMCP example: concrete uses that work today

You searched for “webmcp example.” Here are working patterns you can copy: add-to-cart that agents call reliably, guarded checkout that won’t fire without a human confirm, and a SaaS action that runs in the user’s session. You’ll see what works today, what’s still rough, and the code to ship it.

TL;DR

• WebMCP exposes page-level tools (JSON Schema + execute) that agents can call instead of scraping. Use it for actions like add_to_cart, start_checkout, create_report.
• Feature-detect both document.modelContext and navigator.modelContext, then register small, well-described tools with minimal JSON results.
• Sensitive actions need an in-page confirmation UI. Never pass secrets in tool params; run with the user’s session.
• Today’s agent/browser support is mixed. ChatGPT desktop and several frameworks work now; see the live ecosystem support tracker.
• If you want production guardrails, drift checks, analytics, and test scenarios, Agent Layer adds those without changing your code.

WebMCP basics in one minute

WebMCP is an in-page standard for registering “tools” that an AI agent can discover and call. A tool has a name, description, JSON Schema for inputs, and an async execute that runs in the current page and session. There’s no separate backend or API keys for the agent.

• Where it lives: document.modelContext (new) and navigator.modelContext (old). Feature-detect both.
• What returns: a small JSON-serialisable result (e.g., { added: true, sku }). Don’t return megabyte payloads.
• Good descriptions explain when to use it, preconditions, and side effects. Agents pick tools from descriptions.

If you want the full primer, see WebMCP Explained: The Native Standard Turning Websites into AI APIs. If you’re comparing protocols, read What is the Difference Between MCP and WebMCP?.

Reality check: support today

WebMCP is early. It already works in some places, and not at all in others.

• Agents: ChatGPT desktop and ChatGPT Work call page tools today. Brave Leo is behind a flag. Claude for Chrome and Gemini in Chrome don’t use tools yet. Perplexity Comet: no signal.
• Browsers: Chrome and Edge have origin trials, Brave is behind a flag; Safari and Firefox don’t support it.
• Frameworks: Vercel agent-browser, Stagehand, and Browser Use work today. Puppeteer and Chrome DevTools MCP need flags. Playwright declined for now.

For the current, verified list, check the ecosystem tracker. Plan for progressive enhancement: your site should work without WebMCP; tools are a fast path for agents that support it.

A practical WebMCP example set you can ship

Below are three real-world examples you can drop into an e‑commerce site or a SaaS app. They feature-detect both addresses and return small results.

1) E‑commerce: add_to_cart

Registers a precise cart action so agents stop guessing at buttons or CSS selectors.

// webmcp-add-to-cart.ts
// Feature-detect both addresses
const mc = (document as any).modelContext ?? (navigator as any).modelContext;

if (mc) {
  mc.registerTool({
    name: "add_to_cart",
    description:
      "Add a product to the cart by SKU and quantity. Use only on product or cart pages. Preconditions: SKU visible in page state. Side effect: cart count increments.",
    inputSchema: {
      type: "object",
      properties: {
        sku: { type: "string" },
        quantity: { type: "integer", minimum: 1, default: 1 }
      },
      required: ["sku"],
      additionalProperties: false
    },
    execute: async ({ sku, quantity = 1 }: { sku: string; quantity?: number }) => {
      // Example: click your existing UI or call your in-page cart API
      const btn = document.querySelector(`[data-sku="${sku}"][data-action="add"]`) as HTMLButtonElement | null;
      if (!btn) return { added: false, reason: "sku_not_found" };

      // Set quantity if you have an input bound to this SKU
      const qty = document.querySelector(`[data-sku="${sku}"][data-role="qty"]`) as HTMLInputElement | null;
      if (qty) qty.value = String(quantity);

      btn.click();

      // Wait for UI state to reflect (rudimentary, adapt to your app)
      await new Promise((r) => setTimeout(r, 300));

      return { added: true, sku, quantity };
    }
  });
}

Notes

• Return a tiny JSON summary. Agents don’t need your entire cart payload.
• Use stable data attributes (data-sku, data-action) instead of brittle CSS selectors.
• Works with your user’s session; no keys in tool params.

If you’re planning a full checkout flow, pair this with the patterns in Preparing Your E‑Commerce Store for AI‑Driven Checkout.

2) E‑commerce: start_checkout with user confirmation

Starting checkout is sensitive. Require an explicit in-page confirmation so an agent can’t pay without a human signal.

// webmcp-start-checkout.ts
const mc = (document as any).modelContext ?? (navigator as any).modelContext;

function confirmAction(message: string): Promise<boolean> {
  // Minimal, replace with your modal. Must require a real user click.
  return new Promise((resolve) => {
    const ok = window.confirm(message);
    resolve(ok);
  });
}

if (mc) {
  mc.registerTool({
    name: "start_checkout",
    description:
      "Begin checkout for the current cart. Sensitive: requires human confirmation in page. Preconditions: cart not empty. Side effect: navigates to checkout step one.",
    inputSchema: { type: "object", properties: {}, additionalProperties: false },
    execute: async () => {
      // Ask for human confirmation; agents should not bypass this UI
      const ok = await confirmAction("Proceed to checkout?");
      if (!ok) return { started: false, reason: "user_declined" };

      const checkoutBtn = document.querySelector('[data-role="checkout"]') as HTMLButtonElement | null;
      if (!checkoutBtn) return { started: false, reason: "button_not_found" };

      checkoutBtn.click();
      return { started: true };
    }
  });
}

Notes

• The confirmation must run in the page and require a click or tap.
• Never accept payment tokens or card data as tool parameters. Keep them in your secure UI and payment SDK flows.

3) SaaS: create_report for a date range

Let agents orchestrate simple, auditable actions without inventing a public API. The user’s session authorizes the action.

// webmcp-create-report.ts
const mc = (document as any).modelContext ?? (navigator as any).modelContext;

if (mc) {
  mc.registerTool({
    name: "create_report",
    description:
      "Generate a usage report for a date range. Use on the Reports page only. Side effect: queues a job and shows a toast.",
    inputSchema: {
      type: "object",
      properties: {
        start_date: { type: "string", format: "date" },
        end_date: { type: "string", format: "date" },
        format: { type: "string", enum: ["csv", "pdf"], default: "csv" }
      },
      required: ["start_date", "end_date"],
      additionalProperties: false
    },
    execute: async ({ start_date, end_date, format }: { start_date: string; end_date: string; format: "csv" | "pdf" }) => {
      // Example bindings into your UI or in-page client
      const sd = document.querySelector('[data-role="start-date"]') as HTMLInputElement | null;
      const ed = document.querySelector('[data-role="end-date"]') as HTMLInputElement | null;
      const ff = document.querySelector('[data-role="format"]') as HTMLSelectElement | null;
      const go = document.querySelector('[data-role="run-report"]') as HTMLButtonElement | null;

      if (!sd || !ed || !go) return { queued: false, reason: "controls_missing" };
      sd.value = start_date;
      ed.value = end_date;
      if (ff) ff.value = format;
      go.click();

      await new Promise((r) => setTimeout(r, 300));
      return { queued: true, start_date, end_date, format };
    }
  });
}

Notes

• Keep the description crisp about where it applies (“on Reports page”) and what it does.
• If a task is destructive (delete project, rotate API key), require the same confirmation pattern as checkout.

How an agent chooses and runs your tool

This sequence shows the happy path when an agent that supports WebMCP lands on your page.

Agents decide which tool to call from names and descriptions. Invest in descriptions as much as in code. If a tool is page-specific, say so. If there are preconditions (logged in, item in stock), say so.

For more patterns to expose, see the catalog in Essential WebMCP Tools for AI‑Ready Websites.

Without Agent Layer vs with it

You can hand-roll WebMCP. Many teams do. The gaps usually appear after you ship: drift, missing guardrails, and no visibility into which agent called what.

Approach	What you get	What you still do yourself
Plain WebMCP (DIY)	Register tools; agents can call them when supported	Keep selectors in sync; write modals; no analytics; guess which agents use tools
With Agent Layer	Same tools, plus versioned configs, drift health checks, guardrails, analytics, and test scenarios	Implement the UI bindings you prefer; decide which actions need confirmation

If you want to see exactly where your site stands, run the free agent‑readiness audit. It flags missing WebMCP tools, unlabeled fields, JSON‑LD issues, CAPTCHAs, and more, and proposes page‑by‑page tools.

Design guidance that saves hours later

Keep tools small and specific

• One verb per tool: add_to_cart, start_checkout, create_report.
• Avoid “do_everything” tools. They’re hard for agents to select correctly.

Describe preconditions and effects

Agents read descriptions. Include:

• Where to use: “Use on product pages only.”
• Preconditions: “User must be logged in.”
• Side effects: “Navigates to checkout step one.”

Return only what agents need

• Summaries like { added: true, sku } are enough.
• If an agent needs details, let it navigate the UI or call a separate read-only tool.

Feature-detect both addresses

• document.modelContext is current; some agents still look at navigator.modelContext. Always detect both.

Never pass secrets in tool params

• Tools run in-page with the user’s session. Keep tokens and cards in your secure UI flows.

Add human confirmation for sensitive actions

• Payment, account changes, deletion, or irreversible operations should require a user click in the page. Show that in your code.

What breaks in production

• UI drift breaks bindings. A class name change silently breaks a tool. If you roll your own, use stable data-attributes and write checks. Agent Layer’s health checks detect drift and suggest an updated selector.

• Vague descriptions lead to wrong tool picks. If your description says “manage cart,” expect misfires. Make it “Add a product to the cart by SKU.”

• Oversized results. Returning the whole cart or report data slows agents and can exceed message limits. Return a compact summary.

• Missing confirmation on sensitive actions. Even if an agent supports tools, it shouldn’t be able to finalize checkout or delete data without a user click.

• Wrong address. Some implementations only register at document.modelContext, others only at navigator.modelContext. Always feature-detect both.

• SPA timing issues. Tools that click buttons before hydration do nothing. In your execute, consider waiting for a known element or state flag.

• Agents that ignore tools. Many agents still scrape. Build your site to be semantically readable and machine-parseable anyway. If you need a refresher on why scraping is fragile, read Why DOM Scraping and Vision Models are Dead for Agentic Web Workflows.

• Bot gates. CAPTCHAs and blocked robots can stop cloud agents. The audit flags these so you know what an agent can and can’t reach.

Example: a minimal template-by-template plan

If you own a storefront or a SaaS dashboard, aim for two or three tools per page template. Keep it boring and reliable.

• Product: add_to_cart, check_stock.
• Cart: start_checkout (guarded), apply_coupon.
• Search: apply_filters, go_to_page.
• Account: update_profile (guarded), download_invoice.

If you’re on WordPress, we wrote a concrete path to wire these up in WebMCP for WordPress: a practical step‑by‑step guide.

Testing your tools

• Manual: Open a supporting agent (e.g., ChatGPT desktop), load your page, ask it to “Add SKU 12345 to my cart.” Watch the call.
• Programmatic: Use frameworks that support WebMCP (e.g., Vercel agent-browser, Stagehand). They run a Chrome and call tools.
• With Agent Layer: Write test scenarios (“When the intent is ‘Buy 2 mugs’, the agent should pick add_to_cart with quantity=2”). Track pass/fail over time.

FAQ, quick honesty

• Do I need this for agents to use my site? No. Agents can still scrape or click your UI. WebMCP just removes guesswork when it’s available.
• Will this help SEO? There’s no verified effect on Google rankings. WebMCP targets agents that execute tasks, not search crawlers.
• Which agents will use my tools now? ChatGPT desktop and Work do. Many others don’t yet. Check the ecosystem status.

Try it

Add one add_to_cart tool, ship it, and watch an agent call it. If you want help prioritizing and hardening, run the free agent‑readiness audit and review the ecosystem tracker to see where tools run today.