Dynamic Tools & Resources

Dynamic tools and resources let React components register MCP capabilities on mount and automatically unregister them on unmount. This enables UI-driven tool availability — tools exist only while the component that defines them is rendered. A dynamic tool is a real server tool. FrontMcpProvider registers it with the server through server.registerTool(), so it is listed like any other tool, runs through the server’s tools:call-tool flow (plugin hooks, authorities, quota and availableWhen apply), reaches every client — including in-browser agents through the WebMCP plugin — and connected clients get notifications/tools/list_changed when it appears or goes away.

useDynamicTool

Registers an MCP tool for the lifetime of the component. Supports both zod schemas (recommended) and raw JSON Schema.

With Zod Schema (Recommended)

import { useDynamicTool } from '@frontmcp/react';
import { z } from '@frontmcp/sdk';

function CartControls() {
  const { addToCart } = useCart();

  useDynamicTool({
    name: 'add_to_cart',
    description: 'Add an item to the shopping cart',
    schema: z.object({
      itemId: z.string().describe('Product ID'),
      quantity: z.number().describe('Quantity to add').optional(),
    }),
    execute: async (args) => {
      // args is typed as { itemId: string; quantity?: number }
      await addToCart(args.itemId, args.quantity ?? 1);
      return { content: [{ type: 'text', text: 'Added to cart' }] };
    },
  });

  return <div>Cart controls active</div>;
}

When a zod schema is provided:

The schema is converted to JSON Schema automatically via toJSONSchema from zod/v4
Input is validated via safeParse before reaching your execute callback
Invalid input returns an error CallToolResult with issue details
The execute callback receives fully typed, validated args

With JSON Schema (Backward Compat)

useDynamicTool({
  name: 'add_to_cart',
  description: 'Add an item to the shopping cart',
  inputSchema: {
    type: 'object',
    properties: {
      itemId: { type: 'string', description: 'Product ID' },
      quantity: { type: 'number', description: 'Quantity to add' },
    },
    required: ['itemId'],
  },
  execute: async (args) => {
    await addToCart(args.itemId as string, (args.quantity as number) ?? 1);
    return { content: [{ type: 'text', text: 'Added to cart' }] };
  },
});

Options

Option	Type	Default	Description
`name`	`string`	—	Required. MCP tool name
`description`	`string`	—	Required. Description for agents
`schema`	`z.ZodObject`	—	Zod schema (mutually exclusive with `inputSchema`)
`inputSchema`	`Record<string, unknown>`	—	JSON Schema (mutually exclusive with `schema`)
`execute`	`(args) => Promise<CallToolResult>`	—	Required. Tool handler
`enabled`	`boolean`	`true`	Conditionally enable/disable
`server`	`string`	—	Target a named server
`annotations`	`ToolAnnotations`	—	MCP hints, e.g. `{ readOnlyHint: true }`
`availableWhen`	`EntryAvailability`	—	Where the tool is offered, e.g. `{ surface: ['webmcp'] }`
`app`	`string`	—	Server app the tool joins (servers with several apps)

Name Conflicts

Dynamic tool names share the server’s namespace. A dynamic tool whose name a server tool (or another provider’s dynamic tool) already has is not registered: the provider reports it through its onError prop, or with a console.warn when there is none, and the component keeps rendering. Names must be 1–64 characters. Registering the tool again (a remount, say) tries it again.

Servers With Several Apps

A dynamic tool joins one of the server’s apps, whose plugin hooks then apply to it. A server made with create() has a single app, so there is nothing to choose. A server with several local apps (FrontMcpInstance.createDirect({ apps: [...] })) refuses a tool that doesn’t say which app it joins, so name the app once per server on the provider. That covers every dynamic tool: useDynamicTool, mcpComponent, store actions and useApiClient.

<FrontMcpProvider server={server} dynamicToolApps={{ default: 'browser' }}>
  <App /> {/* its dynamic tools join the `browser` app */}
</FrontMcpProvider>

dynamicToolApps is keyed by server name: the primary server goes by the provider’s name ('default' unless set), and each entry of servers by its key. A tool can name its own app instead, with useDynamicTool({ ..., app: 'billing' }).

Offering a Tool Only to In-Browser Agents

With the WebMCP plugin installed, availableWhen decides which callers see a tool:

useDynamicTool({
  name: 'fill_checkout_form',
  description: 'Fill the checkout form with the given address',
  schema: z.object({ street: z.string(), city: z.string() }),
  annotations: { destructiveHint: false },
  availableWhen: { surface: ['webmcp'] }, // only agents in the browser, not MCP clients
  execute: async (address) => {
    form.fill(address);
    return { content: [{ type: 'text', text: 'Form filled' }] };
  },
});

Conditional Registration

Use enabled to conditionally register/unregister tools based on application state:

function AdminTools({ isAdmin }: { isAdmin: boolean }) {
  useDynamicTool({
    name: 'delete_user',
    description: 'Delete a user account (admin only)',
    schema: z.object({ userId: z.string() }),
    execute: async (args) => {
      await deleteUser(args.userId);
      return { content: [{ type: 'text', text: 'User deleted' }] };
    },
    enabled: isAdmin, // Tool only available when isAdmin is true
  });

  return null;
}

Stale Closure Prevention

The execute function is stored in a ref internally, so it always captures the latest closure values. You don’t need to memoize it.

Execution

A call runs your execute through the server’s flows, but your code itself runs outside the server’s request turn. In a browser build (which has no AsyncContext, so the server serves one request at a time) a tool that calls the server back or waits on the network does not block other requests.

useDynamicResource

Registers an MCP resource for the lifetime of the component.

import { useDynamicResource } from '@frontmcp/react';

function UserPreferences({ preferences }: { preferences: UserPrefs }) {
  useDynamicResource({
    uri: 'app://user-preferences',
    name: 'user-preferences',
    description: 'Current user preferences',
    mimeType: 'application/json',
    read: async () => ({
      contents: [
        {
          uri: 'app://user-preferences',
          mimeType: 'application/json',
          text: JSON.stringify(preferences),
        },
      ],
    }),
  });

  return <div>Preferences loaded</div>;
}

Options

Option	Type	Default	Description
`uri`	`string`	—	Required. Resource URI
`name`	`string`	—	Required. Human-readable name
`description`	`string`	—	Description for agents
`mimeType`	`string`	—	Content MIME type
`read`	`() => Promise<ReadResourceResult>`	—	Required. Read handler
`enabled`	`boolean`	`true`	Conditionally enable/disable
`server`	`string`	—	Target a named server

useComponentTree

Exposes the DOM subtree under a ref as a JSON MCP resource. Useful for giving agents visibility into the rendered component hierarchy.

import { useRef } from 'react';
import { useComponentTree } from '@frontmcp/react';

function Dashboard() {
  const rootRef = useRef<HTMLDivElement>(null);

  useComponentTree({
    rootRef,
    uri: 'react://component-tree',
    maxDepth: 10,
    includeProps: true,
  });

  return (
    <div ref={rootRef}>
      <div data-component="Sidebar">...</div>
      <div data-component="MainContent">...</div>
    </div>
  );
}

Options

Option	Type	Default	Description
`rootRef`	`RefObject<HTMLElement \| null>`	—	Required. Root element ref
`uri`	`string`	`'react://component-tree'`	Resource URI
`maxDepth`	`number`	`10`	Maximum traversal depth
`includeProps`	`boolean`	`false`	Include `data-*` attributes as props
`server`	`string`	—	Target a named server

Output Format

The resource returns a JSON tree with component, tag, children, and optional props:

{
  "component": "Dashboard",
  "tag": "div",
  "children": [
    { "component": "Sidebar", "tag": "div", "children": [] },
    { "component": "MainContent", "tag": "div", "children": [] }
  ]
}

Elements with data-component attributes use that value as component. Others fall back to the tag name.

Mount/Unmount Lifecycle

Dynamic tools and resources follow React’s effect lifecycle:

Mount: The tool/resource is registered with the DynamicRegistry; the provider registers tools with the server
Update: If dependencies change, the old registration is cleaned up and a new one is created
Unmount: The tool/resource is automatically unregistered (and the tool removed from the server)

Changes are applied to the server on a microtask, so React StrictMode’s mount → unmount → mount settles into one registration. When two mounted components register the same name, the later definition replaces the earlier one on the server too. This means agents only see tools that correspond to currently rendered UI. When a user navigates away from a page, its tools disappear; when they navigate back, the tools reappear.

function App() {
  const [page, setPage] = useState<'home' | 'settings'>('home');

  return (
    <FrontMcpProvider server={server}>
      {page === 'home' && <HomePage />}     {/* home tools registered */}
      {page === 'settings' && <Settings />} {/* settings tools registered */}
    </FrontMcpProvider>
  );
}

Get Started

Concepts

Build

Deploy

Plugins

Adapters

Extensibility

Testing

React SDK

Guides

Dynamic Tools & Resources

useDynamicTool

With Zod Schema (Recommended)

With JSON Schema (Backward Compat)

Options

Name Conflicts

Servers With Several Apps

Offering a Tool Only to In-Browser Agents

Conditional Registration

Stale Closure Prevention

Execution

useDynamicResource

Options

useComponentTree

Options

Output Format

Mount/Unmount Lifecycle

​useDynamicTool

​With Zod Schema (Recommended)

​With JSON Schema (Backward Compat)

​Options

​Name Conflicts

​Servers With Several Apps

​Offering a Tool Only to In-Browser Agents

​Conditional Registration

​Stale Closure Prevention

​Execution

​useDynamicResource

​Options

​useComponentTree

​Options

​Output Format

​Mount/Unmount Lifecycle

useDynamicTool

With Zod Schema (Recommended)

With JSON Schema (Backward Compat)

Options

Name Conflicts

Servers With Several Apps

Offering a Tool Only to In-Browser Agents

Conditional Registration

Stale Closure Prevention

Execution

useDynamicResource

Options

useComponentTree

Options

Output Format

Mount/Unmount Lifecycle