WebMCP Documentation

In this tutorial, we will create a minimal React app that registers one WebMCP tool using the useWebMCP hook. The hook handles registration on mount and cleanup on unmount automatically. By the end, you will have a React component that exposes a tool to AI agents and shows execution state in the UI.

Prerequisites

Node.js 22.12 or later
A text editor
A modern web browser

What we will build

A React app with a single component that:

Initializes the WebMCP polyfill
Registers a say_hello tool via the useWebMCP hook
Shows execution count and results in the page
Allows you to call the tool from both the UI and the browser console

Scaffold the project

Create a new React project with Vite:

npm create vite@latest my-webmcp-react -- --template react-ts
cd my-webmcp-react

Install the WebMCP dependencies:

npm install @mcp-b/webmcp-polyfill usewebmcp

@mcp-b/webmcp-polyfill provides the document.modelContext runtime. usewebmcp provides the React hook for tool registration.

Initialize the polyfill

Open src/main.tsx and add the polyfill initialization before createRoot:

src/main.tsx

import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App';

initializeWebMCPPolyfill();

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

Calling initializeWebMCPPolyfill() once at the top level makes document.modelContext available before any component mounts.

Create the tool component

Replace the contents of src/App.tsx with:

src/App.tsx

import { useWebMCP } from 'usewebmcp';

const INPUT_SCHEMA = {
  type: 'object',
  properties: {
    name: { type: 'string' },
  },
} as const;

export function App() {
  const helloTool = useWebMCP({
    name: 'say_hello',
    description: 'Returns a hello message',
    inputSchema: INPUT_SCHEMA,
    execute: async (args) => ({
      content: [{ type: 'text', text: `Hello ${args?.name ?? 'world'}!` }],
    }),
  });

  return (
    <div>
      <h1>My First React WebMCP Tool</h1>
      <p>Tool "say_hello" registered.</p>
      <p>Executions: {helloTool.state.executionCount}</p>
      <p>
        Last result:{' '}
        {helloTool.state.lastResult ? JSON.stringify(helloTool.state.lastResult) : 'none'}
      </p>
      {helloTool.state.error && (
        <p style={{ color: 'red' }}>Error: {helloTool.state.error.message}</p>
      )}
      <button onClick={() => helloTool.execute({ name: 'React' })}>Run Tool Locally</button>
    </div>
  );
}

The useWebMCP hook registers the tool when the component mounts and unregisters it when the component unmounts. The named schema also keeps the component easy to scan; inline schema objects do not cause re-registration by reference.

Start the development server

npm run dev

Open http://localhost:5173 in your browser. You should see:

Expected page

My First React WebMCP Tool
Tool "say_hello" registered.
Executions: 0
Last result: none

Call the tool from the UI

Click the Run Tool Locally button. Notice the page updates:

Expected result

Executions: 1
Last result: {"content":[{"type":"text","text":"Hello React!"}]}

Click the button a few more times. The execution count increases with each click.

Verify the tool from the console

Open the browser console (F12) and verify the tool is registered:

const modelContext = document.modelContext;
const tools = await modelContext.getTools();
console.log(tools);

You should see an array containing your say_hello tool. Now feature-detect the Chrome-compatible execution extension and call it:

const tool = tools.find((candidate) => candidate.name === 'say_hello');
if (!tool) throw new Error('say_hello is not registered');

const executeTool = modelContext.executeTool;
if (typeof executeTool !== 'function') {
  throw new Error('This runtime does not expose the optional Chrome executeTool extension');
}

const result = await executeTool.call(modelContext, tool, JSON.stringify({ name: 'Console' }));
console.log(result === null ? null : JSON.parse(result));

The output should be an object containing the tool response:

{
  "content": [{ "type": "text", "text": "Hello Console!" }]
}

Notice that the execution count in the UI also incremented, because the same underlying execute function ran.

What you learned

initializeWebMCPPolyfill() should be called once at app startup, before components mount
useWebMCP registers a tool on mount and unregisters on unmount
Schema object identity does not trigger re-registration; use deps when registered metadata changes
The hook returns state (with executionCount, lastResult, error, isExecuting) and an execute function for local invocation
Tools registered via the hook are discoverable with document.modelContext.getTools() and callable when the runtime exposes Chrome’s optional executeTool() extension

Next steps

Try the Native Chrome Preview to use the browser’s built-in WebMCP API without a polyfill
Connect a Desktop Agent to let Claude or Cursor call your tools
See the usewebmcp reference for the full hook API, output schemas, and advanced patterns

Tutorials

Build Your First React Tool

Prerequisites

What we will build

What you learned

Next steps

​Prerequisites

​What we will build

​What you learned

​Next steps

Prerequisites

What we will build

What you learned

Next steps