Use WebMCP Tool

There's a new npm package worth a look if you're building anything React-based that might get poked at by an AI agent someday: use-webmcp-tool. It wraps the WebMCP spec's imperative API — the one where you manually call document.modelContext.registerTool and pass around an AbortController to unregister things — into a hook that feels like every other bit of React state management you already write.

The core idea behind WebMCP itself is straightforward. Instead of an AI agent scraping the DOM, parsing the accessibility tree, or squinting at screenshots to figure out what a page does, the page can just declare its own tools. A todo app, for instance, can expose an add-todo function with a name, a description, and a JSON schema for its inputs, and any agent — browser-built-in, running in an iframe, or living in an extension — can discover and call it directly.

What useWebMCP adds is lifecycle management. Call the hook inside a component and the tool registers when that component mounts, then unregisters automatically the moment it unmounts. That's a small detail with a real consequence: the list of tools an agent can see stays synced with what's actually rendered on screen, rather than accumulating stale registrations from components that have long since disappeared. The hook also feature-detects the underlying API and quietly becomes a no-op wherever WebMCP support doesn't exist, since the spec is still explicitly experimental.

The API surface is small but thoughtfully normalized. Return a plain string from your execute function and it becomes a text content block; return nothing and it's treated as a quiet success; return something that's already shaped like an MCP result and it passes through untouched. Errors get the same careful treatment — whether you throw an Error, throw a plain string, or even return an Error object instead of throwing it, the hook funnels all of it into an isError result after firing any onError callback you've supplied. The stated goal is blunt: a failure should never be able to masquerade as a success to the calling agent.

The package is maintained by Chrome, ships as ESM with TypeScript types and no runtime dependencies, and requires React 18 or later as a peer dependency. It comes with a test suite of 21 cases covering mount and unmount behavior, React StrictMode quirks, late API injection, and the full matrix of result and error normalization — including the odder edge cases like thrown non-Error values.