Agent-Skills.md

Agent Skills: WebMCP Browser Tools

>-

UncategorizedID: oimiragieo/agent-studio/webmcp-browser-tools

Repository

oimiragieo/agent-studio
oimiragieo
19

Install this agent skill to your local

pnpm dlx add-skill https://github.com/oimiragieo/agent-studio/tree/HEAD/.claude/skills/webmcp-browser-tools

Skill Files

Browse the full folder contents for webmcp-browser-tools.

Download Skill

Loading file tree…

.claude/skills/webmcp-browser-tools/SKILL.md

Skill Metadata

Name
webmcp-browser-tools
Description
>-

WebMCP Browser Tools

WebMCP is a browser API specification — published as a W3C Community Group Draft by contributors from Google and Microsoft (February 2026) — that enables web applications to expose their own UI functionality as MCP tools to AI agents.

Direction of data flow: Web App → exposes tools → AI Agent calls them.

This is the reverse of web scraping. The web app author decides what functions agents can call. The agent doesn't read the page — it calls structured tools the page registered.

Critical Distinction

| Scenario | Correct Tool | | ----------------------------------------------------------------------------------------- | ---------------------------------------- | | Agent fetches content from an external website (BLS, Ongig, news sites) | WebFetch or mcp__Exa__web_search_exa | | Web app exposes its own actions (add to cart, filter results, submit form) to an AI agent | WebMCP | | Agent automates a browser (click, fill, navigate) | mcp__chrome-devtools__* or Playwright |

WebMCP is not a web scraper, crawler, or search engine. It is a tool registration protocol for web apps that want to be first-class AI-callable services.

Status (as of 2026-02-22)

  • Spec: W3C Community Group Draft — https://github.com/webmachinelearning/webmcp
  • Browser support: Early preview in Chrome 146 Canary (shipped February 2026) behind the Experimental Web Platform Features flag. Stable rollout expected mid–late 2026.
  • Installable packages: YES — the @mcp-b/ ecosystem provides working npm packages today (polyfill + React integration)

Available npm packages

| Package | Purpose | | -------------------------- | ------------------------------------------------------ | | @mcp-b/react-webmcp | React hooks to expose components as MCP tools (v1.1.1) | | @mcp-b/webmcp-polyfill | Strict WebMCP core polyfill for any framework | | @mcp-b/webmcp-types | TypeScript type definitions | | @mcp-b/transports | Browser transport layer (WebSocket/postMessage) | | @mcp-b/webmcp-ts-sdk | Adapts the official MCP TypeScript SDK for browsers | | @mcp-b/create-webmcp-app | Scaffolding tool for new WebMCP apps |

Install:

npm install @mcp-b/react-webmcp
# or for raw usage:
npm install @mcp-b/transports @modelcontextprotocol/sdk zod

How WebMCP Works

A web app registers tools with the browser. An AI agent (that has been granted access) can call those tools. The handler runs as client-side JavaScript with full access to the page's state.

// Web app registers tools for AI agents to call
if ('modelContext' in window.navigator) {
  window.navigator.modelContext.provideContext({
    tools: [
      {
        name: 'filterProducts',
        description: 'Filter the product list by a natural language query',
        inputSchema: {
          type: 'object',
          properties: {
            query: { type: 'string', description: 'Natural language filter' },
          },
          required: ['query'],
        },
        execute({ query }, agent) {
          // Runs in-browser, has access to current UI state
          const results = productService.filter(query);
          return { content: [{ type: 'text', text: JSON.stringify(results) }] };
        },
      },
    ],
  });
}

React integration (via @mcp-b/react-webmcp)

import { useTool } from '@mcp-b/react-webmcp';

function ProductList({ products }) {
  useTool({
    name: 'filterProducts',
    description: 'Filter products visible on screen',
    inputSchema: {
      /* ... */
    },
    execute({ query }) {
      return products.filter(p => p.name.includes(query));
    },
  });
  return (
    <ul>
      {products.map(p => (
        <li key={p.id}>{p.name}</li>
      ))}
    </ul>
  );
}

Key Differences from Standard MCP

| Aspect | Standard MCP Server | WebMCP | | -------------- | --------------------------- | ------------------------------------------------------- | | Location | Separate server process | Browser client-side JS | | Context access | Isolated from UI | Shares live UI state, DOM, user session | | Status | Production-ready | Chrome Canary preview (stable ~mid-2026) | | Installation | npm server package | @mcp-b/ npm packages (polyfill) or native browser API | | Setup | Separate process, stdio/SSE | In-page script, browser transport | | Auth | Server-level | Browser security model + page context |

When to Use This Skill

Use Skill({ skill: 'webmcp-browser-tools' }) when:

  • Designing a web app that should expose UI actions to AI agents (e.g., a dashboard that agents can query, a form workflow agents can submit)
  • Integrating an existing web app with Claude via browser-side tools rather than building a backend MCP server
  • Planning agent-to-web-app collaboration where the agent and user share the same browser interface (human-in-the-loop workflows)
  • Evaluating whether to use WebMCP vs. backend MCP for a new product feature

Do NOT use this skill when:

  • You need to fetch or scrape content from external sites → use WebFetch or mcp__Exa__web_search_exa
  • You need browser automation (click, fill, navigate) → use mcp__chrome-devtools__*
  • The web app does not support WebMCP → build a standard backend MCP server instead

Real-World Use Cases

  • E-commerce agent: Product page registers searchInventory, addToCart, applyPromoCode — agent calls them without scraping
  • Analytics dashboard: Dashboard registers runQuery(metric, timeRange) — agent can answer data questions without screen-reading
  • Browser IDE: Code editor registers insertSnippet, runTests, openFile — agent assists without Playwright automation
  • Figma/design tool: Registers createComponent, applyTheme — agent can directly modify designs

agent-studio Integration Path

Today (Chrome Canary + @mcp-b polyfill)

  1. Install @mcp-b/webmcp-polyfill or @mcp-b/react-webmcp in the target web app
  2. Register tools using window.navigator.modelContext.provideContext()
  3. Claude Code (with the mcp__chrome-devtools__* tools available) can discover and call registered tools on the page

When Chrome Stable Ships (~mid-2026)

  1. No polyfill needed — native browser API available
  2. Update this skill's examples to reflect the stable API surface
  3. Consider creating a dedicated webmcp-integration workflow for onboarding web apps as agent-callable services

Monitoring

Watch: https://github.com/webmachinelearning/webmcp for:

  • Chrome intent-to-ship / origin trial announcements
  • Firefox and Safari implementation signals
  • Breaking changes in the window.navigator.modelContext API surface
  • @mcp-b/ package releases for updated polyfill patterns

Anti-Patterns

  • Do NOT use WebMCP to scrape or read content from sites you don't control — that's WebFetch / Exa
  • Do NOT confuse with Anthropic's MCP (Model Context Protocol) — same underlying protocol, different surface: WebMCP is the browser-side extension of MCP
  • Do NOT build production systems that require Chrome stable WebMCP until the API ships; use the @mcp-b/webmcp-polyfill for progressive enhancement today
  • Do NOT register tools that require server-side data access — those belong in a backend MCP server, not a browser tool

Assigned Agents

| Agent | Role | | -------------- | ------------------------------------------------------------------------- | | frontend-pro | Primary — designing and implementing WebMCP tool registration in web apps | | developer | Supporting — integration architecture, polyfill setup, TypeScript types | | researcher | Supporting — tracking spec evolution, browser support status |

Iron Laws

  1. ALWAYS gate WebMCP usage behind if ('modelContext' in window.navigator) feature detection
  2. NEVER use WebMCP for external page fetching or web scraping — use WebFetch or Exa instead
  3. ALWAYS define JSON Schema for tool inputs before writing the handler (schema-first design)
  4. NEVER register WebMCP tools that replicate backend requests — exploit current page state instead
  5. ALWAYS use the polyfill (@mcp-b/webmcp-polyfill) for development until Chrome stable ships the native API

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | --------------------------------------- | ----------------------------------------- | --------------------------------------------------- | | No feature detection guard | Crashes in non-WebMCP browsers | Always check 'modelContext' in window.navigator | | Using WebMCP for external URL fetching | Wrong direction of data flow | Use WebFetch or Exa for external content | | Skipping JSON Schema for tool inputs | Ambiguous contracts, runtime errors | Define schema for all tool inputs before handler | | Registering backend-equivalent tools | Duplicates MCP server, ignores page state | Tools should expose UI-specific actions and state | | Relying on native API in production now | Chrome stable ships ~mid-2026 | Use @mcp-b/webmcp-polyfill until native is stable |

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

After completing:

  • New WebMCP pattern or API update → .claude/context/memory/learnings.md
  • Browser support change (Chrome flag, origin trial) → .claude/context/memory/learnings.md
  • Architecture decision for agent-browser integration → .claude/context/memory/decisions.md
  • Breaking change in @mcp-b/ packages → .claude/context/memory/issues.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.