usewebmcp reference

usewebmcp is the tool-only React package. It registers enabled tools with document.modelContext and unregisters them when disabled or unmounted, without adding prompt, resource, server, or transport hooks. document.modelContext must already exist at runtime through native browser support, @mcp-b/webmcp-polyfill, or @mcp-b/global.

Installation

Install packages

pnpm add usewebmcp react

Minimal example

Hook

`useWebMCP(config, deps?)`

Import

import { useWebMCP } from 'usewebmcp';

Parameter	Type	Description
`config`	`WebMCPConfig`	Tool configuration object
`deps`	`DependencyList`	Optional dependency array that triggers tool re-registration when values change

Returns: WebMCPReturn

Field	Type	Description
`state`	`ToolExecutionState`	Current execution state
`execute(input)`	`(input) => Promise`	Manually invoke the tool from your UI or tests
`reset()`	`() => void`	Reset state to initial values

Config fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique tool identifier
`description`	`string`	Yes	Human-readable description for AI assistants
`enabled`	`boolean`	No	Whether the tool is registered. Defaults to `true`.
`inputSchema`	JSON Schema or Standard JSON Schema v1	No	Defines input parameters. Use `as const` for inference.
`outputSchema`	JSON Schema	No	MCP-B helper metadata for output typing and `structuredContent`.
`annotations`	`ToolAnnotations`	No	WebMCP and MCP behavior hints
`execute(input)`	`(input) => T \| Promise<T>`	Yes	Tool implementation

The WebMCP draft defines readOnlyHint and untrustedContentHint. MCP-specific hints such as idempotentHint remain available when the hook registers against an MCP-B runtime, but they are not part of the current WebMCP proposal.

Conditional registration

enabled: false skips registration. Changing enabled to true registers the latest committed configuration; changing it to false aborts the registration. The hook must still be called unconditionally, following the Rules of Hooks. Execution state and the local execute and reset controls remain available while disabled. Disabling does not cancel the execute implementation, but the runtime may reject an in-flight MCP request when its registration is removed. enabled controls exposure, not authorization.

`ToolExecutionState`

Field	Type	Description
`isExecuting`	`boolean`	Whether the tool is currently running
`lastResult`	`TOutput \| null`	Result from the most recent successful execution
`error`	`Error \| null`	Error from the most recent failed execution
`executionCount`	`number`	Total successful executions

Type inference

Input inference works with two schema formats:

inline JSON Schema literals, or reusable constants preserved with as const
Standard JSON Schema v1 implementations such as Zod 4.2+

Output inference comes from outputSchema when you pass a JSON Schema literal:

the execute return type is inferred from the schema
state.lastResult is typed accordingly
the MCP response includes structuredContent

Output inference

const OUTPUT_SCHEMA = {
  type: 'object',
  properties: {
    total: { type: 'integer' },
  },
  required: ['total'],
  additionalProperties: false,
} as const;

const tool = useWebMCP({
  name: 'count_items',
  description: 'Count items',
  outputSchema: OUTPUT_SCHEMA,
  execute: () => ({ total: 3 }),
});

Re-registration triggers

While enabled, the hook unregisters and re-registers when any of these values change:

name
description
values in deps

Re-enabling also registers the latest metadata, without needing an entry in deps. The latest committed execute implementation applies without re-registration. The hook also stores inputSchema, outputSchema, and annotations in a committed ref, so new object references do not re-register the tool. A registered descriptor retains its current metadata until another trigger re-registers it. Include a primitive schema or annotation revision in deps when that metadata must change. In the browser, the hook updates that ref with React’s useLayoutEffect. This publishes the newest committed callback before passive effects run, covering the window where an external MCP call can arrive immediately after a commit. A render that suspends or is otherwise abandoned never updates the ref. During server rendering, the hook falls back to useEffect, following React’s server-rendering guidance for layout effects.

Tool responses

Existing MCP responses pass through unchanged. Raw strings become text content, while other JSON values become text content plus structuredContent. When outputSchema is defined, the implementation must return a JSON-serializable value. The schema drives TypeScript inference; the hook does not validate the returned value against it at runtime. Object, array, string, number, boolean, and null schemas are supported for inference. The current WebMCP draft does not define or enforce outputSchema; its tool dictionary defines inputSchema.

Exported types

Type	Description
`WebMCPConfig`	Configuration object type
`WebMCPReturn`	Return value type
`ToolExecutionState`	Execution state shape
`ToolExecuteFunction`	Tool implementation function signature
`InferToolInput`	Infer input type from schema
`InferOutput`	Infer output type from schema

Packages

WebMCP platforms and agents

Core runtime

React

Tooling

Installation

Minimal example

Hook

`useWebMCP(config, deps?)`

Config fields

Conditional registration

`ToolExecutionState`

Type inference

Re-registration triggers

Tool responses

Exported types

​Installation

​Minimal example

​Hook

​useWebMCP(config, deps?)

​Config fields

​Conditional registration

​ToolExecutionState

​Type inference

​Re-registration triggers

​Tool responses

​Exported types

​Related pages

Installation

Minimal example

Hook

`useWebMCP(config, deps?)`

Config fields

Conditional registration

`ToolExecutionState`

Type inference

Re-registration triggers

Tool responses

Exported types

Related pages