572

Build agent-ready React apps with WebMCP

Expose application features to AI agents with createWebMCP in plain TypeScript or useWebMCP inside React components.

November 15, 2026

MCP gives AI agents a structured way to discover and call tools. These tools usually come from an MCP server connected through a transport: the server describes what is available, accepts typed input, runs application logic, and returns a result.

WebMCP brings the same tool-based interaction to a web page. The page registers its capabilities through document.modelContext, and the browser makes them available to compatible agents. The website does not need a separate MCP server just to expose functionality that already exists in the client.

This is more reliable than asking an agent to reconstruct every workflow from clicks and form inputs. A WebMCP tool provides an explicit contract:

  • name identifies the tool.
  • description explains when it should be used.
  • inputSchema describes its arguments with JSON Schema.
  • execute connects the tool to existing application logic.
  • annotations indicate whether the operation is read-only, consequential, or intended for debugging.

The lifecycle is straightforward: the page registers a tool, an agent discovers it, the browser invokes execute with structured input, and the result goes back to the agent. The page can remove the registration when a route, component, or feature is no longer available.

Reactuse provides two small APIs for this:

  • createWebMCP works anywhere in the browser, without React.
  • useWebMCP connects one tool to a React component's lifecycle.

WebMCP is still experimental, so both APIs expose supported and work as progressive enhancements.

WebMCP inside React

When a tool belongs to a component or route, use useWebMCP:

import { useWebMCP } from '@siberiacancode/reactuse';
 
const TodoTool = ({ addTodo }: { addTodo: (text: string) => void }) => {
  const webMCP = useWebMCP({
    name: 'add-todo',
    title: 'Add a todo',
    description: "Adds an item to the user's todo list",
    inputSchema: {
      type: 'object',
      properties: {
        text: { type: 'string', minLength: 1 }
      },
      required: ['text'],
      additionalProperties: false
    },
    execute: (input) => {
      const text = typeof input.text === 'string' ? input.text.trim() : '';
      if (!text) throw new Error('Todo text is required');
 
      addTodo(text);
      return { success: true };
    }
  });
 
  if (webMCP.error) {
    return <p role='alert'>Could not register the todo tool.</p>;
  }
 
  return null;
};

The hook registers the tool after mount and unregisters it on unmount. Its execute callback reads the latest props and state, so the registered tool does not keep a stale React closure.

It returns supported, registered, and error, plus manual register() and unregister() methods. Set immediately: false when registration should happen only after authentication, feature activation, or another application event.

WebMCP without React

Despite the library name, you do not need React to use WebMCP. createWebMCP creates a standalone registry that can live in a plain TypeScript module, client-side service, or another framework:

import { createWebMCP } from '@siberiacancode/reactuse';
 
const webMCP = createWebMCP();
 
if (webMCP.supported) {
  await webMCP.register({
    name: 'get-theme',
    title: 'Get current theme',
    description: 'Returns the current color theme',
    inputSchema: {
      type: 'object',
      properties: {},
      additionalProperties: false
    },
    annotations: { readOnlyHint: true },
    execute: () => ({ theme: document.documentElement.dataset.theme ?? 'light' })
  });
}
 
window.addEventListener('pagehide', webMCP.clear, { once: true });

The registry owns every tool registered through it:

  • register(tool) adds a tool.
  • unregister(name) removes one tool.
  • clear() removes them all.
  • supported reports whether document.modelContext is available.

Registering the same name again replaces the previous registration. This makes createWebMCP useful for application shells, plugin systems, route handlers, and any code where React lifecycle hooks would be unnecessary.

Multiple tools can share one registry:

const webMCP = createWebMCP();
 
await Promise.all([
  webMCP.register({
    name: 'get-workspace',
    description: 'Returns the current workspace',
    annotations: { readOnlyHint: true },
    execute: () => getCurrentWorkspace()
  }),
  webMCP.register({
    name: 'create-project',
    description: 'Creates a project in the current workspace',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string', minLength: 1 }
      },
      required: ['name'],
      additionalProperties: false
    },
    execute: (input) => {
      const name = typeof input.name === 'string' ? input.name.trim() : '';
      if (!name) throw new Error('Project name is required');
 
      return createProject(name);
    }
  })
]);

Call clear() when the registry's owner is disposed.

Which one should you use?

Use createWebMCP when WebMCP should exist outside React or when one owner manages several tools.

Use useWebMCP when one tool follows the lifecycle of a component.

In both cases, keep tool names and descriptions specific, validate input again inside execute, check current permissions before changing data, and respect the execution AbortSignal for cancellable work.