WebMCP hook

API reference for useFullCalendarWebMCP covering options, registration lifecycle, Strict Mode behavior, and a minimal React example.

React hook that registers FullCalendar WebMCP tools against your host persistence.

Signature

import { useFullCalendarWebMCP } from "@protocoltooling/fullcalendar";

function useFullCalendarWebMCP(options: FullCalendarWebMCPOptions): void;

Options

PropType

calendarRefRefObject<FullCalendarHandle | null>

Ref attached to <FullCalendar />.

TypeRefObject<FullCalendarHandle | null>

eventsCalendarEventRepository

Your persistence object (list / get / create / update / delete). Not the FullCalendar events array.

TypeCalendarEventRepository

onEventsChanged() => unknown | Promise<unknown>

Called after agent create, update, or delete so you can refresh UI state from your source of truth.

Type() => unknown | Promise<unknown>

onRegistrationError?(error: unknown) => void

Called if tool registration fails (for example duplicate tool names).

Type(error: unknown) => void

capabilities?FullCalendarWebMCPCapabilities

Least-privilege tool exposure. Disabled capabilities omit tools from registration. See Security.

TypeFullCalendarWebMCPCapabilities

Example

import FullCalendar from "@fullcalendar/react";
import { useCallback, useRef, useState } from "react";
import { useFullCalendarWebMCP, type CalendarEvent } from "@protocoltooling/fullcalendar";
import { repository } from "./events-service";

export function Calendar() {
  const calendarRef = useRef<FullCalendar>(null);
  const [events, setEvents] = useState<CalendarEvent[]>([]);

  const refreshEvents = useCallback(async () => {
    setEvents(await repository.list());
  }, []);

  useFullCalendarWebMCP({
    calendarRef,
    events: repository,
    onEventsChanged: refreshEvents,
    onRegistrationError: (error) => console.error(error),
  });

  return (
    <FullCalendar
      ref={calendarRef}
      events={events.map((event) => ({
        ...event,
        end: event.end ?? undefined,
      }))}
    />
  );
}

Lifecycle

Registration: Tools register in useEffect. Unmount aborts registration and cleans up.
Strict Mode: Safe under development double-mount; no duplicate tools left behind.
Late WebMCP runtime: If document.modelContext is missing at mount, the hook polls every 250 ms until it appears or the component unmounts.
Fresh options: Tool handlers always use the latest events repository and callbacks without re-registering on every render.

See CalendarEventRepository, Types, Security, and Troubleshooting.