For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt, and this page is available as Markdown at https://rspress.rs/ui/hooks/use-web-mcp.md.
close
Rspress
  • English

      • useWebMcp

      Added in v2.1.0

      useWebMcp registers a tool with the browser's experimental WebMCP API and removes it when the component unmounts. Import it from @rspress/core/runtime:

      import { usePage, useWebMcp } from '@rspress/core/runtime';

export function PageTitleTool() {
  const { page } = usePage();

  useWebMcp({
    name: 'my_site_page_title',
    description: 'Get the current page title',
    annotations: { readOnlyHint: true },
    execute: () => ({ title: page.title }),
  });

  return null;
}

      Mount the component where the capability belongs. Keep site-wide tools in a persistent component; mount tools specific to a page with that page. Tool names must be unique across the document, including the built-in tools.

      Custom tools work independently of the webMcp config option. See the WebMCP guide for browser requirements.

      Options

      OptionDescription
      nameRequired unique tool name.
      descriptionRequired description for agents.
      titleOptional display title.
      inputSchemaJSON Schema describing the input.
      execute(input, options)Required function returning a JSON-serializable value or a promise. options.signal, when provided, carries cancellation from the caller.
      enabledWhether to register the tool. Defaults to true; setting it to false unregisters the tool.
      annotationsOptional boolean hints: readOnlyHint, untrustedContentHint, consequentialHint, and debugging.
      exposedToOptional array of additional secure origins allowed to discover the tool.

      Use WebMcpOptions<TInput, TResult> or parameter annotations for types, and validate inputs and handle cancellation in execute.

      useWebMcp({
  name: 'my_site_lookup',
  description: 'Look up a documentation entry',
  inputSchema: {
    type: 'object',
    properties: { query: { type: 'string' } },
    required: ['query'],
    additionalProperties: false,
  },
  async execute(input: { query: string }, { signal }) {
    if (typeof input?.query !== 'string' || !input.query.trim()) {
      throw new TypeError('query must be a non-empty string');
    }
    const response = await fetch(
      `/api/lookup?q=${encodeURIComponent(input.query)}`,
      { signal },
    );
    if (!response.ok) throw new Error(`Lookup failed: ${response.status}`);
    return response.json();
  },
});

      Return value and lifecycle

      Returns WebMcpState:

      • supported: whether the browser supports WebMCP.
      • registered: whether registration succeeded.
      • error: the registration error, or null on success.

      Tool calls use the latest committed props and state. Updating the handler does not re-register the tool. Disabling or unmounting the component unregisters it.