WebMCP Documentation

usewebmcp is the strict-core React package. It registers tools with document.modelContext on mount and unregisters them on unmount without adding MCP-B-only hooks. document.modelContext must already exist at runtime through native browser support, @mcp-b/webmcp-polyfill, or @mcp-b/global.

Installation

pnpm add usewebmcp react

Minimal example

Hook

`useWebMCP(config, deps?)`

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 (lowercase with underscores)
`description`	`string`	Yes	Human-readable description for AI assistants
`inputSchema`	JSON Schema or Standard 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	Metadata hints such as `readOnlyHint` and `idempotentHint`
`execute(input)`	`(input) => T \| Promise<T>`	Yes*	Preferred tool implementation function
`handler(input)`	`(input) => T \| Promise<T>`	Yes*	Backward-compatible alias for `execute`
`formatOutput(output)`	`(output) => string`	No	Deprecated. Prefer `outputSchema`.
`onSuccess(result, input)`	`(result, input) => void`	No	Callback after successful execution
`onError(error, input)`	`(error, input) => void`	No	Callback after failed execution

One of execute or handler is required. If both are present, execute wins.

`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:

JSON Schema literals with as const
Standard Schema v1 implementations such as Zod v4, Valibot, and ArkType

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

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

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

The hook unregisters and re-registers when any of these values change:

name
description
inputSchema reference
outputSchema reference
annotations reference
values in deps

These callbacks are stored in refs and do not trigger re-registration:

execute
handler
onSuccess
onError
formatOutput

Define inputSchema, outputSchema, and annotations outside the component or memoize them. Fresh object references on every render force unnecessary re-registration.

Output schema contract

When outputSchema is defined, the implementation must return a JSON-serializable value that matches that schema for MCP-B helpers that consume it. Object, array, string, number, boolean, and null schemas are supported for type inference and hook result shaping. Native Chrome WebMCP does not currently define or enforce outputSchema; the browser standard 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 standard

Core runtime

React

Tooling

usewebmcp reference

Installation

Minimal example

Hook

`useWebMCP(config, deps?)`

Config fields

`ToolExecutionState`

Type inference

Re-registration triggers

Output schema contract

Exported types

​Installation

​Minimal example

​Hook

​useWebMCP(config, deps?)

​Config fields

​ToolExecutionState

​Type inference

​Re-registration triggers

​Output schema contract

​Exported types

​Related pages

Installation

Minimal example

Hook

`useWebMCP(config, deps?)`

Config fields

`ToolExecutionState`

Type inference

Re-registration triggers

Output schema contract

Exported types

Related pages