> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfront.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Dynamic Tools & Resources

> Register MCP tools and resources dynamically from React components

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.

## useDynamicTool

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

### With Zod Schema (Recommended)

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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)

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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 |

### Conditional Registration

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

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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.

***

## useDynamicResource

Registers an MCP resource for the lifetime of the component.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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`:

```json theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
  "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:

1. **Mount**: The tool/resource is registered with the `DynamicRegistry`
2. **Update**: If dependencies change, the old registration is cleaned up and a new one is created
3. **Unmount**: The tool/resource is automatically unregistered

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.

```tsx theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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>
  );
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.