Skip to content
Back to search

webmcp-react

React hooks for exposing your app's functionality as WebMCP tools - transport-agnostic, SSR-safe, Strict Mode safe, W3C spec-aligned

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agentcathq--webmcp-react/badge.svg)](/listings/agentcathq--webmcp-react)

HTML

<a href="/listings/agentcathq--webmcp-react"><img src="/api/listings/agentcathq--webmcp-react/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install webmcp-react zod

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 255 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # webmcp-react
  2. React hooks for exposing typed tools on `document.modelContext`, aligned with the current [WebMCP](https://github.com/webmachinelearning/webmcp) specification.
  3. [![npm version](https://img.shields.io/npm/v/webmcp-react)](https://www.npmjs.com/package/webmcp-react)
  4. [![npm downloads](https://img.shields.io/npm/dm/webmcp-react)](https://www.npmjs.com/package/webmcp-react)
  5. [![license](https://img.shields.io/npm/l/webmcp-react)](./LICENSE)
  6. [![CI](https://github.com/agentcathq/webmcp-react/actions/workflows/ci.yml/badge.svg)](https://github.com/agentcathq/webmcp-react/actions/workflows/ci.yml)
  7. [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](./tsconfig.json)
  8. - **Zod-first.** Define inputs with Zod and get full type inference in handlers
  9. - **JSON Schema support.** Pass raw JSON Schema when you do not use Zod
  10. - **Built-in polyfill.** Installs a lightweight polyfill when native WebMCP is unavailable
  11. - **SSR-safe.** Works with Next.js, Remix, and other server-rendering frameworks
  12. - **StrictMode-safe.** Prevents duplicate registrations and orphaned tools
  13. - **Spec-aligned.** Tracks the WebMCP specification and native Chrome behavior release by release
  14. ## Requirements
  15. - React 18 or later
  16. - Zod 3.25 or later, or Zod 4, as a peer dependency. Tools can also be defined with [JSON Schema](#json-schema).
  17. ## Install
  18. ```bash
  19. npm install webmcp-react zod
  20. ```
  21. ## Quick start
  22. Wrap your app in `<WebMCPProvider>` and register tools with `useMcpTool`:
  23. ```tsx
  24. import { WebMCPProvider, useMcpTool } from "webmcp-react";
  25. import { z } from "zod";
  26. function SearchTool() {
  27. useMcpTool({
  28. name: "search",
  29. description: "Search the catalog",
  30. input: z.object({ query: z.string() }),
  31. handler: async ({ query }) => ({
  32. content: [{ type: "text", text: `Results for: ${query}` }],
  33. }),
  34. });
  35. return null;
  36. }
  37. export default function App() {
  38. return (
  39. <WebMCPProvider name="my-app" version="1.0">
  40. <SearchTool />
  41. </WebMCPProvider>
  42. );
  43. }
  44. ```
  45. The tool is now registered on `document.modelContext` and any WebMCP-compatible agent can call it.
  46. ### Agent skills
  47. This repository ships [agent skills](./skills) that install webmcp-react and scaffold tools for you. Install them with the [skills CLI](https://skills.sh):
  48. ```bash
  49. npx skills add agentcathq/webmcp-react
  50. ```
  51. The skills work with Cursor, Claude Code, GitHub Copilot, Cline, and [18+ other agents](https://vercel.com/docs/agent-resources/skills).
  52. ## Playground
  53. Try it live: [**WebMCP Wordle Demo**](https://agentcathq.github.io/webmcp-react/playground/)
  54. The playground is a fully playable Wordle clone built on `webmcp-react` hooks. Tools register and unregister as the game moves through its phases (idle, playing, won, lost). You can make guesses with the keyboard or through an AI agent. A DevPanel shows the current tool state, and an easy-mode toggle enables a hint tool.
  55. To play with an AI agent:
  56. - **Codex.** Open the demo in Codex and ask it to play. Codex discovers and calls the page's WebMCP tools directly.
  57. - **Claude, Cursor, and other MCP clients.** Install the [WebMCP Bridge extension](https://chromewebstore.google.com/detail/webmcp-bridge/chgjbookknohehmaocfijekhaocaanaf), open the demo in Chrome, and activate the extension for the page.
  58. ## How it works
  59. [WebMCP](https://github.com/webmachinelearning/webmcp) is a proposed web standard from the W3C Web Machine Learning Community Group. It adds `document.modelContext` to the browser, an API that lets any page expose typed, callable tools to AI agents. Chrome ships the API in [Early Preview](https://developer.chrome.com/blog/webmcp-epp).
  60. This library provides the React bindings for that API. `<WebMCPProvider>` installs a polyfill when native support is absent, and each `useMcpTool` call registers a tool that agents can discover and execute.
  61. ![How webmcp-react works](./docs/architecture.svg)
  62. ## Connect to AI clients
  63. Agents with built-in WebMCP browser support, such as Codex, discover and call tools directly from the page. Clients that cannot access `document.modelContext` directly, such as Claude Code and Cursor, connect through the [WebMCP Bridge extension](https://chromewebstore.google.com/detail/webmcp-bridge/chgjbookknohehmaocfijekhaocaanaf), which exposes your registered tools to any MCP client.
  64. 1. Install the extension from the [Chrome Web Store](https://chromewebstore.google.com/detail/webmcp-bridge/chgjbookknohehmaocfijekhaocaanaf).
  65. 2. Configure your MCP client. See the [extension setup guide](./extension/README.md) for details.
  66. The extension will be deprecated when Chrome provides native bridging to desktop clients.
  67. ### Testing in Chrome
  68. Google's [WebMCP extension](https://github.com/GoogleChromeLabs/webmcp-extension) lists a page's tools and runs an agent against them from a side panel, which is handy while building tools. It only sees tools registered through Chrome's native API, so on a page running the polyfill it finds nothing. Turn on `chrome://flags/#enable-webmcp-testing` (the extension needs Chrome 155 or newer) and `<WebMCPProvider>` will use the native API instead of the polyfill.
  69. ## Usage
  70. ### Execution state
  71. `useMcpTool` returns reactive state you can use to build UI around tool execution:
  72. ```tsx
  73. function TranslateTool() {
  74. const { state, execute } = useMcpTool({
  75. name: "translate",
  76. description: "Translate text to Spanish",
  77. input: z.object({ text: z.string() }),
  78. handler: async ({ text }) => {
  79. const result = await translate(text, "es");
  80. return { content: [{ type: "text", text: result }] };
  81. },
  82. });
  83. return (
  84. <div>
  85. <button onClick={() => execute({ text: "Hello" })} disabled={state.isExecuting}>
  86. {state.isExecuting ? "Translating..." : "Translate"}
  87. </button>
  88. {state.lastResult && <p>{state.lastResult.content[0].text}</p>}
  89. {state.error && <p className="error">{state.error.message}</p>}
  90. </div>
  91. );
  92. }
  93. ```
  94. ### Cancellation
  95. Each execution receives its own `AbortSignal`. Pass it to `fetch` and other cancellable work. Chrome 153+ aborts the signal when the agent cancels the call. On older browsers the library substitutes a never-aborting signal, so the second argument is always safe to use:
  96. ```tsx
  97. useMcpTool({
  98. name: "fetch_report",
  99. description: "Fetch a report by ID",
  100. input: z.object({ id: z.string() }),
  101. handler: async ({ id }, { signal }) => {
  102. const res = await fetch(`/api/reports/${id}`, { signal });
  103. return { content: [{ type: "text", text: await res.text() }] };
  104. },
  105. });
  106. ```
  107. ### Title and annotations
  108. Give a tool a human-friendly display `title`, and describe its behavior to agents with `annotations`. The current WebMCP specification defines four annotations: `readOnlyHint`, `untrustedContentHint`, `consequentialHint` and `debugging`. Set `consequentialHint` on tools that do something hard to undo, like placing an order, so agents know to check with the user first.
  109. ```tsx
  110. useMcpTool({
  111. name: "search_users",
  112. title: "Search users",
  113. description: "Find users by name or email",
  114. input: z.object({ query: z.string() }),
  115. annotations: {
  116. readOnlyHint: true,
  117. },
  118. handler: async ({ query }) => { /* ... */ },
  119. });
  120. ```
  121. ### Dynamic tools
  122. Tools register on mount and unregister on unmount. Render them conditionally like any React component:
  123. ```tsx
  124. function App({ user }) {
  125. return (
  126. <WebMCPProvider name="app" version="1.0">
  127. <PublicTools />
  128. {user.isAdmin && <AdminTools />}
  129. </WebMCPProvider>
  130. );
  131. }
  132. ```
  133. ### Callbacks
  134. Run side effects on success or failure:
  135. ```tsx
  136. useMcpTool({
  137. name: "checkout",
  138. description: "Complete a purchase",
  139. input: z.object({ cartId: z.string() }),
  140. handler: async ({ cartId }) => { /* ... */ },
  141. onSuccess: (result) => analytics.track("checkout_complete"),
  142. onError: (error) => toast.error(error.message),
  143. });
  144. ```
  145. `onError` fires when the handler throws. A handler that returns `{ isError: true }` on its own still counts as a success, so `onSuccess` fires for it.
  146. ### JSON Schema
  147. Pass `inputSchema` directly to define a tool without Zod:
  148. ```tsx
  149. useMcpTool({
  150. name: "calculate",
  151. description: "Basic arithmetic",
  152. inputSchema: {
  153. type: "object",
  154. properties: {
  155. a: { type: "number" },
  156. b: { type: "number" },
  157. op: { type: "string", enum: ["add", "subtract", "multiply", "divide"] },
  158. },
  159. required: ["a", "b", "op"],
  160. },
  161. handler: async (args) => {
  162. const { a, b, op } = args as { a: number; b: number; op: string };
  163. const result = { add: a + b, subtract: a - b, multiply: a * b, divide: a / b }[op];
  164. return { content: [{ type: "text", text: String(result) }] };
  165. },
  166. });
  167. ```
  168. ### TypeScript
  169. `webmcp-react` already types `document.modelContext`, so theres no need to add Google's `webmcp-types` as well. The two packages declare the same global differently and clash if you install both, see [TypeScript and webmcp-types](./docs/api.md#typescript-and-webmcp-types) for details and a workaround.
  170. ### SSR
  171. The library works with Next.js, Remix, and any server-rendering framework. The build includes a `"use client"` banner, so no extra configuration is needed.
  172. ## Browser support
  173. | Environment | Behavior |
  174. | --- | --- |
  175. | Chrome with native `document.modelContext` | The library uses the native API. The polyfill is not installed. |
  176. | All other browsers | The library installs its polyfill, which implements the registration and consumer APIs. |
  177. The polyfill follows native Chrome behavior. See the [polyfill section of the API reference](./docs/api.md#polyfill-behavior) for the exact Chrome versions each behavior tracks.
  178. ## Versioning and stability
  179. `webmcp-react` follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Breaking changes to the public API bump the major version. Every release is documented in the [changelog](./CHANGELOG.md), including the WebMCP specification and Chrome changes it tracks.
  180. `outputSchema` and `structuredContent` are documented library extensions to the WebMCP specification. They are part of the public API and follow the same versioning policy.
  181. ## API
  182. See the [full API reference](./docs/api.md).
  183. ## Contributing
  184. Bug reports, feature requests, and pull requests are welcome. Read the [contributing guide](./CONTRIBUTING.md) before you open a pull request. This project follows the [Contributor Covenant Code of Conduct](./CODE_OF_CONDUCT.md).
  185. ## License
  186. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.