1# Widget Interactivity
2 
3Widgets interact with the outside world using hooks from `mcp-use/react`. `useCallTool()` provides tool calling with built-in state management. `sendFollowUpMessage` from `useWidget()` triggers LLM conversation turns.
4 
5**Use `useCallTool()` for:** Creating items, updating data, triggering actions, submitting forms
6**Use `sendFollowUpMessage` for:** Asking the AI to analyze, compare, summarize, or respond based on widget context
7 
8---
9 
10## useCallTool() Basics
11 
12`useCallTool()` provides a TanStack Query-like state machine for calling MCP tools:
13 
14```tsx
15import { useCallTool } from "mcp-use/react";
16 
17const { callTool, callToolAsync, isPending, isSuccess, isError, data, error } =
18  useCallTool("tool-name");
19 
20// Fire-and-forget with optional callbacks
21callTool({ param: "value" }, {
22  onSuccess: (result) => console.log(result.structuredContent),
23  onError: (err) => console.error(err),
24  onSettled: () => hideSpinner(),
25});
26 
27// Or async/await
28const result = await callToolAsync({ param: "value" });
29```
30 
31**State flags:**
32 
33| Property | Description |
34|---|---|
35| `isPending` | Tool is executing |
36| `isSuccess` | Succeeded — `data` is available |
37| `isError` | Failed — `error` is available |
38| `isIdle` | No call made yet |
39| `callTool` | Fire-and-forget; optional `onSuccess`/`onError`/`onSettled` callbacks |
40| `callToolAsync` | Returns `Promise<CallToolResult>` |
41 
42**Type inference:** When using `mcp-use dev`, types for tool names, inputs, and outputs are auto-generated to `.mcp-use/tool-registry.d.ts`. The hook is fully typed with autocomplete.
43 
44---
45 
46## Simple Button Action
47 
48```tsx
49import { McpUseProvider, useWidget, useCallTool, type WidgetMetadata } from "mcp-use/react";
50import { z } from "zod";
51 
52export const widgetMetadata: WidgetMetadata = {
53  description: "Todo list with actions",
54  props: z.object({
55    todos: z.array(z.object({
56      id: z.string(),
57      title: z.string(),
58      completed: z.boolean()
59    }))
60  }),
61  exposeAsTool: false
62};
63 
64export default function TodoList() {
65  const { props, isPending: isLoading } = useWidget();
66  const { callTool, isPending } = useCallTool("toggle-todo");
67 
68  if (isLoading) {
69    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
70  }
71 
72  return (
73    <McpUseProvider autoSize>
74      <div>
75        {props.todos.map(todo => (
76          <div key={todo.id} style={{ display: "flex", gap: 8, padding: 8 }}>
77            <input
78              type="checkbox"
79              checked={todo.completed}
80              onChange={() => callTool({ id: todo.id, completed: !todo.completed })}
81              disabled={isPending}
82            />
83            <span style={{ textDecoration: todo.completed ? "line-through" : "none" }}>
84              {todo.title}
85            </span>
86          </div>
87        ))}
88      </div>
89    </McpUseProvider>
90  );
91}
92```
93 
94**Corresponding tool:**
95```typescript
96server.tool(
97  {
98    name: "toggle-todo",
99    description: "Toggle todo completion status",
100    schema: z.object({
101      id: z.string(),
102      completed: z.boolean()
103    })
104  },
105  async ({ id, completed }) => {
106    await updateTodo(id, { completed });
107    return text(`Todo ${completed ? "completed" : "uncompleted"}`);
108  }
109);
110```
111 
112---
113 
114## Form Submission
115 
116`isPending` from `useCallTool` replaces manual `submitting` state:
117 
118```tsx
119import { useState } from "react";
120import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
121 
122export default function CreateItemWidget() {
123  const { props, isPending: isLoading } = useWidget();
124  const { callTool, isPending } = useCallTool("create-todo");
125  const [title, setTitle] = useState("");
126 
127  if (isLoading) {
128    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
129  }
130 
131  const handleSubmit = (e: React.FormEvent) => {
132    e.preventDefault();
133    if (!title.trim()) return;
134 
135    callTool({ title }, {
136      onSuccess: () => setTitle(""),
137      onError: () => alert("Failed to create todo"),
138    });
139  };
140 
141  return (
142    <McpUseProvider autoSize>
143      <div style={{ padding: 20 }}>
144        <form onSubmit={handleSubmit}>
145          <input
146            type="text"
147            value={title}
148            onChange={e => setTitle(e.target.value)}
149            placeholder="New todo..."
150            disabled={isPending}
151            style={{ padding: 8, width: 300, marginRight: 8 }}
152          />
153          <button type="submit" disabled={isPending}>
154            {isPending ? "Creating..." : "Add Todo"}
155          </button>
156        </form>
157 
158        <div style={{ marginTop: 16 }}>
159          {props.todos.map(todo => (
160            <div key={todo.id}>{todo.title}</div>
161          ))}
162        </div>
163      </div>
164    </McpUseProvider>
165  );
166}
167```
168 
169**Corresponding tool:**
170```typescript
171server.tool(
172  {
173    name: "create-todo",
174    schema: z.object({
175      title: z.string().describe("Todo title")
176    })
177  },
178  async ({ title }) => {
179    const todo = await createTodo(title);
180    return text(`Created todo: ${todo.title}`);
181  }
182);
183```
184 
185---
186 
187## Delete Action
188 
189```tsx
190const { callTool: deleteTodo, isPending: isDeleting } = useCallTool("delete-todo");
191 
192const handleDelete = (id: string) => {
193  if (!confirm("Are you sure you want to delete this item?")) return;
194 
195  deleteTodo({ id }, {
196    onError: () => alert("Failed to delete item"),
197  });
198};
199 
200return (
201  <McpUseProvider autoSize>
202    <div>
203      {props.todos.map(todo => (
204        <div key={todo.id} style={{ display: "flex", justifyContent: "space-between", padding: 8 }}>
205          <span>{todo.title}</span>
206          <button onClick={() => handleDelete(todo.id)} disabled={isDeleting}>Delete</button>
207        </div>
208      ))}
209    </div>
210  </McpUseProvider>
211);
212```
213 
214---
215 
216## Optimistic Updates
217 
218Update UI immediately, then call tool:
219 
220```tsx
221import { useState, useEffect } from "react";
222import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
223 
224interface Todo {
225  id: string;
226  title: string;
227  completed: boolean;
228}
229 
230export default function OptimisticWidget() {
231  const { props, isPending: isLoading } = useWidget<{ todos: Todo[] }>();
232  const { callToolAsync } = useCallTool("toggle-todo");
233  const [todos, setTodos] = useState<Todo[]>([]);
234 
235  useEffect(() => {
236    if (!isLoading && props.todos) {
237      setTodos(props.todos);
238    }
239  }, [isLoading, props.todos]);
240 
241  const handleToggle = async (id: string) => {
242    // Optimistic update
243    setTodos(prev => prev.map(todo =>
244      todo.id === id ? { ...todo, completed: !todo.completed } : todo
245    ));
246 
247    try {
248      await callToolAsync({ id });
249    } catch {
250      // Revert on failure
251      setTodos(props.todos);
252      alert("Failed to update todo");
253    }
254  };
255 
256  if (isLoading) {
257    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
258  }
259 
260  return (
261    <McpUseProvider autoSize>
262      <div>
263        {todos.map(todo => (
264          <div key={todo.id}>
265            <input
266              type="checkbox"
267              checked={todo.completed}
268              onChange={() => handleToggle(todo.id)}
269            />
270            {todo.title}
271          </div>
272        ))}
273      </div>
274    </McpUseProvider>
275  );
276}
277```
278 
279---
280 
281## Action Buttons
282 
283Multiple actions per item — declare a hook for each tool:
284 
285```tsx
286const { callTool: editItem } = useCallTool("edit-item");
287const { callTool: duplicateItem } = useCallTool("duplicate-item");
288const { callTool: archiveItem } = useCallTool("archive-item");
289const { callTool: deleteItem } = useCallTool("delete-item");
290 
291return (
292  <McpUseProvider autoSize>
293    <div>
294      {props.items.map(item => (
295        <div key={item.id} style={{ padding: 12, border: "1px solid #ddd", marginBottom: 8 }}>
296          <h3>{item.title}</h3>
297          <p>{item.description}</p>
298 
299          <div style={{ display: "flex", gap: 8 }}>
300            <button onClick={() => editItem({ id: item.id })}>Edit</button>
301            <button onClick={() => duplicateItem({ id: item.id })}>Duplicate</button>
302            <button onClick={() => archiveItem({ id: item.id })}>Archive</button>
303            <button onClick={() => deleteItem({ id: item.id })} style={{ color: "red" }}>
304              Delete
305            </button>
306          </div>
307        </div>
308      ))}
309    </div>
310  </McpUseProvider>
311);
312```
313 
314---
315 
316## Inline Editing
317 
318```tsx
319import { useState } from "react";
320import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
321 
322export default function EditableList() {
323  const { props, isPending: isLoading } = useWidget();
324  const { callToolAsync, isPending: isSaving } = useCallTool("update-item");
325  const [editingId, setEditingId] = useState<string | null>(null);
326  const [editValue, setEditValue] = useState("");
327 
328  const startEdit = (id: string, currentValue: string) => {
329    setEditingId(id);
330    setEditValue(currentValue);
331  };
332 
333  const saveEdit = async (id: string) => {
334    try {
335      await callToolAsync({ id, title: editValue });
336      setEditingId(null);
337    } catch {
338      alert("Failed to save");
339    }
340  };
341 
342  const cancelEdit = () => {
343    setEditingId(null);
344    setEditValue("");
345  };
346 
347  if (isLoading) {
348    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
349  }
350 
351  return (
352    <McpUseProvider autoSize>
353      <div>
354        {props.items.map(item => (
355          <div key={item.id} style={{ padding: 8, display: "flex", gap: 8 }}>
356            {editingId === item.id ? (
357              <>
358                <input
359                  type="text"
360                  value={editValue}
361                  onChange={e => setEditValue(e.target.value)}
362                  autoFocus
363                />
364                <button onClick={() => saveEdit(item.id)} disabled={isSaving}>Save</button>
365                <button onClick={cancelEdit}>Cancel</button>
366              </>
367            ) : (
368              <>
369                <span>{item.title}</span>
370                <button onClick={() => startEdit(item.id, item.title)}>Edit</button>
371              </>
372            )}
373          </div>
374        ))}
375      </div>
376    </McpUseProvider>
377  );
378}
379```
380 
381---
382 
383## Batch Actions
384 
385Select multiple items and act on them:
386 
387```tsx
388import { useState } from "react";
389import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
390 
391export default function BatchActions() {
392  const { props, isPending: isLoading } = useWidget();
393  const { callTool: archiveItems, isPending: isArchiving } = useCallTool("archive-items");
394  const { callTool: deleteItems, isPending: isDeleting } = useCallTool("delete-items");
395  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
396 
397  const processing = isArchiving || isDeleting;
398 
399  const toggleSelection = (id: string) => {
400    const newSelection = new Set(selectedIds);
401    if (newSelection.has(id)) {
402      newSelection.delete(id);
403    } else {
404      newSelection.add(id);
405    }
406    setSelectedIds(newSelection);
407  };
408 
409  const handleBatchArchive = () => {
410    archiveItems({ ids: Array.from(selectedIds) }, {
411      onSuccess: () => setSelectedIds(new Set()),
412      onError: () => alert("Failed to archive items"),
413    });
414  };
415 
416  const handleBatchDelete = () => {
417    deleteItems({ ids: Array.from(selectedIds) }, {
418      onSuccess: () => setSelectedIds(new Set()),
419      onError: () => alert("Failed to delete items"),
420    });
421  };
422 
423  if (isLoading) {
424    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
425  }
426 
427  return (
428    <McpUseProvider autoSize>
429      <div>
430        {selectedIds.size > 0 && (
431          <div style={{ padding: 12, backgroundColor: "#f5f5f5", marginBottom: 16 }}>
432            <span>{selectedIds.size} selected</span>
433            <button onClick={handleBatchArchive} disabled={processing} style={{ marginLeft: 8 }}>
434              Archive
435            </button>
436            <button onClick={handleBatchDelete} disabled={processing} style={{ marginLeft: 8 }}>
437              Delete
438            </button>
439          </div>
440        )}
441 
442        {props.items.map(item => (
443          <div key={item.id} style={{ padding: 8, display: "flex", gap: 8 }}>
444            <input
445              type="checkbox"
446              checked={selectedIds.has(item.id)}
447              onChange={() => toggleSelection(item.id)}
448            />
449            <span>{item.title}</span>
450          </div>
451        ))}
452      </div>
453    </McpUseProvider>
454  );
455}
456```
457 
458**Corresponding tool:**
459```typescript
460server.tool(
461  {
462    name: "delete-items",
463    schema: z.object({
464      ids: z.array(z.string()).describe("Item IDs to delete")
465    })
466  },
467  async ({ ids }) => {
468    await Promise.all(ids.map(id => deleteItem(id)));
469    return text(`Deleted ${ids.length} items`);
470  }
471);
472```
473 
474---
475 
476## Handling Tool Errors
477 
478Use `isError` and `error` from the hook instead of manual error state:
479 
480```tsx
481const { callTool, isError, error, isPending } = useCallTool("some-tool");
482 
483return (
484  <McpUseProvider autoSize>
485    <div>
486      {isError && (
487        <div style={{ padding: 12, backgroundColor: "#ffebee", color: "#c62828", marginBottom: 16 }}>
488          {error instanceof Error ? error.message : "Action failed"}
489        </div>
490      )}
491 
492      <button onClick={() => callTool({ /* params */ })} disabled={isPending}>
493        Perform Action
494      </button>
495    </div>
496  </McpUseProvider>
497);
498```
499 
500---
501 
502## Per-Item Loading States
503 
504For per-item loading when sharing one hook instance, track the active ID separately:
505 
506```tsx
507const { callToolAsync } = useCallTool("process-item");
508const [loadingId, setLoadingId] = useState<string | null>(null);
509 
510const handleAction = async (id: string) => {
511  setLoadingId(id);
512  try {
513    await callToolAsync({ id });
514  } catch {
515    alert("Failed");
516  } finally {
517    setLoadingId(null);
518  }
519};
520 
521return (
522  <McpUseProvider autoSize>
523    <div>
524      {props.items.map(item => (
525        <div key={item.id}>
526          <span>{item.title}</span>
527          <button
528            onClick={() => handleAction(item.id)}
529            disabled={loadingId === item.id}
530          >
531            {loadingId === item.id ? "Processing..." : "Process"}
532          </button>
533        </div>
534      ))}
535    </div>
536  </McpUseProvider>
537);
538```
539 
540---
541 
542## Confirmation Dialogs
543 
544```tsx
545const { callTool: deleteItem } = useCallTool("delete-item");
546 
547const handleDelete = (id: string, title: string) => {
548  if (!confirm(`Are you sure you want to delete "${title}"?`)) return;
549 
550  deleteItem({ id }, {
551    onError: () => alert("Failed to delete"),
552  });
553};
554```
555 
556Or with a custom dialog:
557 
558```tsx
559import { useState } from "react";
560import { useCallTool } from "mcp-use/react";
561 
562const { callToolAsync } = useCallTool("delete-item");
563const [confirmDialog, setConfirmDialog] = useState<{ id: string; title: string } | null>(null);
564 
565const handleDeleteClick = (id: string, title: string) => {
566  setConfirmDialog({ id, title });
567};
568 
569const handleConfirmDelete = async () => {
570  if (!confirmDialog) return;
571 
572  try {
573    await callToolAsync({ id: confirmDialog.id });
574    setConfirmDialog(null);
575  } catch {
576    alert("Failed to delete");
577  }
578};
579 
580return (
581  <McpUseProvider autoSize>
582    <div>
583      {props.items.map(item => (
584        <div key={item.id}>
585          <span>{item.title}</span>
586          <button onClick={() => handleDeleteClick(item.id, item.title)}>Delete</button>
587        </div>
588      ))}
589 
590      {confirmDialog && (
591        <div style={{
592          position: "fixed", top: 0, left: 0, right: 0, bottom: 0,
593          backgroundColor: "rgba(0,0,0,0.5)", display: "flex",
594          alignItems: "center", justifyContent: "center"
595        }}>
596          <div style={{ backgroundColor: "white", padding: 24, borderRadius: 8 }}>
597            <h3>Confirm Delete</h3>
598            <p>Delete "{confirmDialog.title}"?</p>
599            <button onClick={handleConfirmDelete}>Delete</button>
600            <button onClick={() => setConfirmDialog(null)}>Cancel</button>
601          </div>
602        </div>
603      )}
604    </div>
605  </McpUseProvider>
606);
607```
608 
609---
610 
611## Triggering LLM Responses: `sendFollowUpMessage`
612 
613`sendFollowUpMessage` from `useWidget()` sends a message to the conversation and triggers a new LLM turn — as if the user typed it. Use this to let widget interactions drive the conversation.
614 
615```tsx
616import { McpUseProvider, useWidget } from "mcp-use/react";
617 
618export default function AnalysisWidget() {
619  const { props, isPending, sendFollowUpMessage } = useWidget();
620 
621  if (isPending) {
622    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
623  }
624 
625  return (
626    <McpUseProvider autoSize>
627      <div style={{ padding: 20 }}>
628        <h2>Results for "{props.query}"</h2>
629        {props.items.map(item => (
630          <div key={item.id} style={{ padding: 8, borderBottom: "1px solid #ddd" }}>
631            <strong>{item.name}</strong> — ${item.price}
632          </div>
633        ))}
634 
635        <button
636          onClick={() => sendFollowUpMessage(
637            `Compare the top 3 results for "${props.query}" and recommend the best one.`
638          )}
639          style={{ marginTop: 16, padding: "8px 16px" }}
640        >
641          Ask AI to Compare
642        </button>
643      </div>
644    </McpUseProvider>
645  );
646}
647```
648 
649### Combining with `useCallTool`
650 
651A widget can use both — `useCallTool` for data mutations and `sendFollowUpMessage` for triggering LLM reasoning:
652 
653```tsx
654import { useState } from "react";
655import { McpUseProvider, useWidget, useCallTool } from "mcp-use/react";
656 
657export default function TodoWidget() {
658  const { props, isPending, state, setState, sendFollowUpMessage } = useWidget();
659  const { callTool: toggleTodo } = useCallTool("toggle-todo");
660 
661  if (isPending) {
662    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
663  }
664 
665  const tasks = state?.tasks || props.tasks || [];
666  const remaining = tasks.filter(t => !t.completed).length;
667 
668  return (
669    <McpUseProvider autoSize>
670      <div style={{ padding: 20 }}>
671        {tasks.map(t => (
672          <div key={t.id} style={{ display: "flex", gap: 8, padding: 8 }}>
673            <input
674              type="checkbox"
675              checked={t.completed}
676              onChange={() => toggleTodo({ id: t.id, completed: !t.completed })}
677            />
678            {t.title}
679          </div>
680        ))}
681 
682        <button
683          onClick={() => sendFollowUpMessage(
684            `I have ${remaining} tasks left. Help me prioritize them.`
685          )}
686          style={{ marginTop: 16, padding: "8px 16px" }}
687        >
688          Ask AI to Prioritize
689        </button>
690      </div>
691    </McpUseProvider>
692  );
693}
694```
695 
696---
697 
698## Complete Example
699 
700```tsx
701import { useState } from "react";
702import { McpUseProvider, useWidget, useCallTool, type WidgetMetadata } from "mcp-use/react";
703import { z } from "zod";
704 
705const propsSchema = z.object({
706  todos: z.array(z.object({
707    id: z.string(),
708    title: z.string(),
709    completed: z.boolean()
710  }))
711});
712 
713type Props = z.infer<typeof propsSchema>;
714 
715export const widgetMetadata: WidgetMetadata = {
716  description: "Interactive todo list",
717  props: propsSchema,
718  exposeAsTool: false
719};
720 
721export default function InteractiveTodoList() {
722  const { props, isPending: isLoading } = useWidget<Props>();
723  const { callTool: createTodo, isPending: isCreating } = useCallTool("create-todo");
724  const { callTool: toggleTodo } = useCallTool("toggle-todo");
725  const { callTool: deleteTodo } = useCallTool("delete-todo");
726  const [newTodo, setNewTodo] = useState("");
727  const [deletingId, setDeletingId] = useState<string | null>(null);
728 
729  if (isLoading) {
730    return <McpUseProvider autoSize><div>Loading todos...</div></McpUseProvider>;
731  }
732 
733  const handleCreate = (e: React.FormEvent) => {
734    e.preventDefault();
735    if (!newTodo.trim()) return;
736 
737    createTodo({ title: newTodo }, {
738      onSuccess: () => setNewTodo(""),
739      onError: () => alert("Failed to create todo"),
740    });
741  };
742 
743  const handleToggle = (id: string, completed: boolean) => {
744    toggleTodo({ id, completed: !completed });
745  };
746 
747  const handleDelete = (id: string) => {
748    setDeletingId(id);
749    deleteTodo({ id }, {
750      onError: () => alert("Failed to delete"),
751      onSettled: () => setDeletingId(null),
752    });
753  };
754 
755  return (
756    <McpUseProvider autoSize>
757      <div style={{ padding: 20 }}>
758        <h2>Todos ({props.todos.length})</h2>
759 
760        <form onSubmit={handleCreate} style={{ marginBottom: 16 }}>
761          <input
762            type="text"
763            value={newTodo}
764            onChange={e => setNewTodo(e.target.value)}
765            placeholder="New todo..."
766            disabled={isCreating}
767            style={{ padding: 8, width: 300, marginRight: 8 }}
768          />
769          <button type="submit" disabled={isCreating}>
770            {isCreating ? "Adding..." : "Add"}
771          </button>
772        </form>
773 
774        <div>
775          {props.todos.map(todo => (
776            <div
777              key={todo.id}
778              style={{
779                display: "flex", alignItems: "center", gap: 8,
780                padding: 8, borderBottom: "1px solid #eee"
781              }}
782            >
783              <input
784                type="checkbox"
785                checked={todo.completed}
786                onChange={() => handleToggle(todo.id, todo.completed)}
787              />
788              <span style={{
789                flex: 1,
790                textDecoration: todo.completed ? "line-through" : "none",
791                color: todo.completed ? "#999" : "inherit"
792              }}>
793                {todo.title}
794              </span>
795              <button
796                onClick={() => handleDelete(todo.id)}
797                disabled={deletingId === todo.id}
798                style={{ color: "red" }}
799              >
800                {deletingId === todo.id ? "Deleting..." : "Delete"}
801              </button>
802            </div>
803          ))}
804        </div>
805 
806        {props.todos.length === 0 && (
807          <p style={{ color: "#999", textAlign: "center" }}>No todos yet</p>
808        )}
809      </div>
810    </McpUseProvider>
811  );
812}
813```
814 
815---
816 
817## Best Practices
818 
8191. **Use `useCallTool` for built-in state management** - No need for manual `isPending`/`error` state
8202. **Declare hooks at the top level** - One hook per tool name; React rules apply
8213. **Use `callTool` for fire-and-forget** - Handle success/error via callbacks
8224. **Use `callToolAsync` for sequential operations** - When you need to await results or chain calls
8235. **Use `isError`/`error` from the hook** - Instead of manual error state for single-tool widgets
8246. **Optimistic updates** - Update local state before the call, revert on error
8257. **Confirm destructive actions** - Use confirm() for deletes
8268. **Use `sendFollowUpMessage` for LLM reasoning** - When you want the AI to analyze, compare, or respond based on widget context rather than mutating data
827 
828---
829 
830## Next Steps
831 
832- **Style widgets** → [ui-guidelines.md](ui-guidelines.md)
833- **Advanced patterns** → [advanced.md](advanced.md)
834- **See examples** → [../patterns/common-patterns.md](../patterns/common-patterns.md)
835