Webmcp skill

WebMCP Skill

Guide for exposing website features to browser agents via the WebMCP API.

WebMCP vs Server MCP

	Server MCP	WebMCP
Runtime	Node/Python server	Browser tab (JavaScript)
API	MCP SDK server.tool()	document.modelContext.registerTool()
Discovery	Client connects to server URL	Agent visits page; tools registered in-page
Auth	OAuth, API keys	Existing web session/cookies

For server-side MCP, use an mcp-builder skill instead. This skill is browser-only.

When to Use

• Adding agent-callable tools to a web app
• Replacing fragile DOM-scraping flows with structured tool calls
• Exposing forms, cart, search, or settings actions to browser agents
• User mentions WebMCP, modelContext, or agent-ready web tools

When NOT to Use

• Building a standalone MCP server (backend)
• Headless automation without a visible browser tab
• Non-web environments (CLI, mobile native)

Prerequisites

Before registering tools, verify:

• Secure context — HTTPS or localhost
• Origin isolation — document is origin-keyed; WebMCP disabled if document.domain is set or Origin-Agent-Cluster: ?0
• Permissions policy — tools feature allowed (default self; cross-origin iframes need allow="tools")
• Browser support — Chrome flag for local dev or origin trial for production (see references/browser-setup.md)
• Visible tab — tool execute runs in an open browser context; no headless calls

API Choice

Simple HTML form submit?
  └─ Yes → Consider declarative HTML annotations (spec still evolving; see examples/form-tool.html)
  └─ No  → Use imperative registerTool() (recommended for SPAs and complex logic)

Prefer the imperative API until declarative form synthesis is stable in the spec.

Implementation Workflow

Copy this checklist and track progress:

Task Progress:
- [ ] Step 1: Audit UI actions worth exposing
- [ ] Step 2: Map each action to one tool (reuse existing app functions)
- [ ] Step 3: Define name, title, description, inputSchema
- [ ] Step 4: Implement execute with structured return values
- [ ] Step 5: Set annotations (readOnlyHint, untrustedContentHint)
- [ ] Step 6: Register on mount; unregister on unmount via AbortSignal
- [ ] Step 7: Test with Chrome flag + Model Context Tool Inspector

Step 1: Audit actions

List user-facing actions agents should perform: search, filter, add to cart, submit form, navigate, etc. Skip actions that require opaque visual interaction unless wrapped in a dedicated tool.

Step 2: Reuse existing logic

Call the same functions your UI buttons use. Do not duplicate business logic in execute.

Step 3: Define the tool

Name rules (from spec):

• 1–128 characters
• ASCII alphanumeric, _, -, . only
• Unique within the page's tool map

Description: Plain language stating what the tool does and what side effects it has. Agents rely on this to choose tools and request user consent.

inputSchema: JSON Schema object. Keep parameters minimal — only what the action needs.

Step 4: Implement execute

Return structured JSON agents can parse. Prefer { error: "..." } over thrown exceptions for expected failures.

execute: async ({ sku, quantity = 1 }) => {
  if (!sku) return { error: 'sku is required' }
  const result = await cartService.add(sku, quantity)
  return { success: true, cartItemCount: result.count }
}

Step 5: Annotations

annotations: {
  readOnlyHint: true,           // tool does not mutate state
  untrustedContentHint: true    // output includes user-generated content
}

See references/security.md for when to set each.

Step 6: Register and clean up

const controller = new AbortController()

await document.modelContext.registerTool(
  {
    name: 'add_to_cart',
    title: 'Add to cart',
    description: 'Adds a product to the shopping cart by SKU. Does not checkout.',
    inputSchema: {
      type: 'object',
      properties: {
        sku: { type: 'string', description: 'Product SKU' },
        quantity: { type: 'integer', minimum: 1, default: 1 }
      },
      required: ['sku']
    },
    annotations: { readOnlyHint: false },
    execute: async ({ sku, quantity = 1 }) => {
      const result = await cartService.add(sku, quantity)
      return { success: true, cartItemCount: result.count }
    }
  },
  { signal: controller.signal }
)

// On page unload or component unmount:
controller.abort()

Step 7: Dynamic tools

If tools change at runtime, listen for registration updates:

document.modelContext.ontoolchange = () => {
  // Refresh UI or internal tool list
}

Tool Design Rules

1. One action per tool — search_products and add_to_cart are separate tools
2. Descriptions match behavior — never describe "view cart" if execute triggers purchase
3. State side effects explicitly — "Adds item; does not charge" vs "Completes purchase"
4. Confirm destructive actions in-app — show a dialog inside execute before purchases, deletes, or sends
5. Minimize inputSchema fields — avoid requesting age, location, or history unless strictly needed
6. No injection in metadata — descriptions and return values must not contain hidden agent instructions
7. Mark UGC as untrusted — forum posts, reviews, comments → untrustedContentHint: true

Framework Integration

Vanilla / SPA

Register after app initialization when DOM and state are ready.

React

useEffect(() => {
  const controller = new AbortController()
  void document.modelContext.registerTool({ /* ... */ }, { signal: controller.signal })
  return () => controller.abort()
}, [dependencies])

Register after hydration on SSR apps. Pass stable dependencies only.

Angular

Chrome documents experimental WebMCP support in Angular. Follow framework-specific guides when available; fall back to imperative registerTool in a service ngOnInit.

Cross-origin iframes

Parent must allow tools in the iframe:

<iframe src="https://embed.example.com" allow="tools"></iframe>

Use exposedTo in registerTool options to expose tools to specific origins. See references/api-reference.md.

Testing

1. Enable Chrome flag: chrome://flags/#enable-webmcp-testing → Enabled → relaunch
2. Install Model Context Tool Inspector Extension
3. Load your page — verify tools appear in the inspector
4. Manually invoke each tool with valid and invalid inputs
5. Prompt the inspector agent in natural language; confirm it picks the right tool
6. Check return values are clear and JSON Schema validates inputs

Full setup: references/browser-setup.md

Common Errors

Error	Cause	Fix
SecurityError	Not origin-isolated	Remove document.domain; check Origin-Agent-Cluster header
NotAllowedError	tools policy blocked	Top-level page or add allow="tools" on iframe
InvalidStateError	Duplicate tool name	Unregister first or use unique names
API undefined	Flag off or unsupported browser	Enable flag or join origin trial

Additional Resources

• API details: references/api-reference.md
• Security guidance: references/security.md
• Browser setup: references/browser-setup.md
• Examples: examples/imperative-tool.ts, examples/react-spa-tool.tsx, examples/form-tool.html
• W3C spec: https://webmachinelearning.github.io/webmcp/
• Chrome docs: https://developer.chrome.com/docs/ai/webmcp