Webmcp Setup

---
name: webmcp-setup
description: >
  Set up a WebMCP project — enable Chrome flags, install MCP-B polyfill,
  scaffold tool registration, and configure development environment. Use when
  starting a new WebMCP-enabled website from scratch.
---

# WebMCP Project Setup

## Before writing code

**Fetch live docs**:
1. Fetch `https://webmachinelearning.github.io/webmcp/` — the **W3C Community Group draft report**, which is the normative spec for `navigator.modelContext`. Start here, not with vendor docs.
2. Fetch `https://developer.chrome.com/docs/ai/webmcp` for Chrome's implementation notes and API overview.
3. Web-search `site:github.com mcp-b polyfill README` for polyfill installation and quickstart.
4. Web-search `webmcp chrome flag enable` for current browser flag names and version requirements — these change per milestone.
5. Web-search `site:chromestatus.com webmcp` for feature status and shipping milestones.

**Standards status**: WebMCP is a **W3C Community Group Draft Report** hosted by the Web Machine Learning CG — it is *not* a W3C Standard and is *not* on the W3C Standards Track. Chrome is the reference implementation; other engines have participated in discussion without shipping. Plan for the API surface to move, keep the polyfill path viable, and re-check browser support rather than assuming it broadened.

## Conceptual Architecture

### What Setup Involves

WebMCP project setup prepares a website to expose tools to AI agents:
1. **Enable browser support** — Chrome 146+ Canary with the `WebMCP for Testing` flag, or install the MCP-B polyfill
2. **Install polyfill (if needed)** — `mcp-b` packages for vanilla JS or React
3. **Scaffold tool registration** — create the entry point where tools are registered via `navigator.modelContext.registerTool()`
4. **Configure development environment** — set up testing with AI agents

### Project Structure (Vanilla JS)

```
my-webmcp-site/
├── src/
│   ├── webmcp/
│   │   ├── tools.js              # Tool definitions and registration
│   │   ├── schemas.js            # JSON Schemas for tool inputs
│   │   └── interactions.js       # User interaction handlers
│   ├── index.html                # Page with optional declarative form attributes
│   └── app.js                    # Main application entry
├── package.json
└── tests/
    └── webmcp.test.js
```

### Project Structure (React + MCP-B)

```
my-webmcp-react-app/
├── src/
│   ├── webmcp/
│   │   ├── tools.ts              # Tool definitions
│   │   ├── schemas.ts            # JSON Schemas
│   │   ├── McpProvider.tsx        # MCP-B React provider/hooks wrapper
│   │   └── interactions.ts       # User interaction logic
│   ├── App.tsx
│   └── index.tsx
├── package.json
├── tsconfig.json
└── tests/
    └── webmcp.test.tsx
```

### Setup Decision Checklist

- **Browser target** — Native Chrome 146+ (flag-gated) or polyfill for broader support?
- **Framework** — Vanilla JS, React, Vue, or server-rendered HTML?
- **API approach** — Imperative (JS `registerTool`), Declarative (HTML attributes), or both?
- **Tool scope** — Which user journeys will be exposed as tools?
- **Authentication** — What user role is required before registering sensitive tools?
- **Testing strategy** — Which AI agents to test with (Gemini, Claude, etc.)?

### Chrome Flag Setup

To enable native WebMCP in Chrome Canary:
1. Install Chrome 146+ Canary
2. Navigate to `chrome://flags`
3. Search for the WebMCP flag (name may change — search for it live)
4. Enable the flag and restart Chrome

### MCP-B Polyfill Setup

For browsers without native WebMCP, the MCP-B polyfill provides the same API surface. Fetch the README for exact installation commands, as packages and APIs may have changed.

### Best Practices

- Start with one or two simple read-only tools before adding transactional ones
- Use the polyfill for development even if targeting native Chrome — it works everywhere
- Register tools after the page has loaded and the user is authenticated
- Group related tools logically (all cart tools together, all search tools together)
- Test tool discovery with at least one AI agent before going to production

Fetch the latest Chrome blog post and MCP-B README for exact commands, package names, and API patterns before scaffolding.