1# Widget Basics
2 
3Widgets are React components that provide visual UI for MCP tools. They let users browse, compare, and interact with data visually.
4 
5**Use widgets for:** Product lists, calendars, dashboards, search results, file browsers, any visual data representation
6 
7---
8 
9## When to Use Widgets
10 
11**Use a widget when:**
12- ✅ Browsing or comparing multiple items
13- ✅ Visual representation improves understanding (charts, images, layouts)
14- ✅ Interactive selection is easier visually than through text
15- ✅ User needs to see data structure at a glance
16 
17**Use plain tool (no widget) when:**
18- ❌ Output is simple text or a single value
19- ❌ No visual representation adds value
20- ❌ Quick conversational response is sufficient
21 
22**When in doubt:** Use a widget. It makes the experience better.
23 
24---
25 
26## Minimal Widget
27 
28### 1. Create Tool with Widget Config
29 
30```typescript
31// index.ts
32import { MCPServer, widget, text } from "mcp-use/server";
33import { z } from "zod";
34 
35const server = new MCPServer({
36  name: "my-server",
37  version: "1.0.0"
38});
39 
40server.tool(
41  {
42    name: "show-weather",
43    description: "Display weather for a city",
44    schema: z.object({
45      city: z.string().describe("City name")
46    }),
47    widget: {
48      name: "weather-display",        // Must match filename: resources/weather-display.tsx
49      invoking: "Fetching weather...", // Optional: shown while loading
50      invoked: "Weather loaded"        // Optional: shown when complete
51    }
52  },
53  async ({ city }) => {
54    const data = await getWeather(city);
55 
56    return widget({
57      props: {
58        city: data.city,
59        temp: data.temperature,
60        conditions: data.conditions,
61        icon: data.icon
62      },
63      output: text(`Weather in ${city}: ${data.temperature}°C, ${data.conditions}`)
64    });
65  }
66);
67```
68 
69### 2. Create Widget Component
70 
71```tsx
72// resources/weather-display.tsx
73import { McpUseProvider, useWidget, type WidgetMetadata } from "mcp-use/react";
74import { z } from "zod";
75 
76const propsSchema = z.object({
77  city: z.string(),
78  temp: z.number(),
79  conditions: z.string(),
80  icon: z.string()
81});
82 
83export const widgetMetadata: WidgetMetadata = {
84  description: "Display weather information for a city",
85  props: propsSchema,
86  exposeAsTool: false  // ← Critical: prevents duplicate tool registration
87};
88 
89type Props = z.infer<typeof propsSchema>;
90 
91export default function WeatherDisplay() {
92  const { props, isPending } = useWidget<Props>();
93 
94  if (isPending) {
95    return (
96      <McpUseProvider autoSize>
97        <div>Loading weather...</div>
98      </McpUseProvider>
99    );
100  }
101 
102  return (
103    <McpUseProvider autoSize>
104      <div style={{ padding: 20 }}>
105        <h2>{props.city}</h2>
106        <img src={props.icon} alt={props.conditions} width={64} />
107        <div style={{ fontSize: 48 }}>{props.temp}°C</div>
108        <p>{props.conditions}</p>
109      </div>
110    </McpUseProvider>
111  );
112}
113```
114 
115**Key requirements:**
1161. Export `widgetMetadata` with props schema
1172. Infer type from schema and pass to `useWidget<Props>()`
1183. `exposeAsTool` defaults to `false` — correct when pairing with a custom tool
1194. Wrap root in `<McpUseProvider autoSize>`
1205. **Always check `isPending` before accessing `props`**
121 
122**Production builds (`mcp-use build`):** Never use bare `useWidget()` without a props generic — fields default to `unknown` and TypeScript will fail (e.g. TS2322). If you use `callTool` from `useWidget()`, treat `structuredContent` and nested values as `unknown` until you parse with Zod, narrow with `typeof`/`Array.isArray`, or assign to typed variables; do not pass `unknown` directly as JSX children or string props.
123 
124---
125 
126## Widget Metadata
127 
128The `widgetMetadata` export defines your widget's contract:
129 
130```typescript
131export const widgetMetadata: WidgetMetadata = {
132  description: "Brief description of what this widget displays",
133  props: z.object({
134    // Define all props the widget expects
135    id: z.string(),
136    title: z.string(),
137    count: z.number(),
138    items: z.array(z.object({
139      name: z.string(),
140      value: z.number()
141    }))
142  }),
143  exposeAsTool: false  // Default; omit or set explicitly when pairing with a custom tool
144};
145```
146 
147**Fields:**
148- `description` - What the widget displays/does
149- `props` - Zod schema defining expected props shape
150- `exposeAsTool` - Set to `true` to auto-register as a tool (default: `false`)
151- `metadata.invoking` - Status text shown in inspector while tool runs (auto-default: `"Loading {name}..."`)
152- `metadata.invoked` - Status text shown in inspector after tool completes (auto-default: `"{name} ready"`)
153 
154```typescript
155export const widgetMetadata: WidgetMetadata = {
156  description: "Display weather information for a city",
157  props: propsSchema,
158  metadata: {
159    invoking: "Fetching weather...", // Shimmer text while tool runs
160    invoked: "Weather loaded",       // Static text when complete
161    csp: { connectDomains: ["https://api.weather.com"] },
162  },
163};
164```
165 
166These status texts appear as animated shimmer text (pending) and static text (complete) in the MCP Inspector and ChatGPT. The values also flow to `openai/toolInvocation/invoking`/`invoked` in tool metadata automatically.
167 
168---
169 
170## useWidget() Hook
171 
172The `useWidget()` hook provides access to props and widget state:
173 
174```typescript
175const {
176  props,        // Widget props from tool response
177  isPending,    // True while props are loading
178  setState,     // Update widget state
179  state,        // Current widget state
180} = useWidget();
181```
182 
183**To call tools from a widget**, use the dedicated `useCallTool()` hook — see [interactivity.md](interactivity.md).
184 
185### props
186Data passed from tool's `widget({ props })` response:
187 
188```typescript
189const { props } = useWidget();
190 
191// Access props after isPending check
192if (!isPending) {
193  console.log(props.city);      // "Tokyo"
194  console.log(props.temp);      // 28
195}
196```
197 
198**Always check `isPending` before accessing `props`:**
199```typescript
200❌ const { props } = useWidget();
201   return <div>{props.city}</div>;  // Error! props undefined while loading
202 
203✅ const { props, isPending } = useWidget();
204   if (isPending) return <div>Loading...</div>;
205   return <div>{props.city}</div>;  // Safe
206```
207 
208### isPending
209Boolean indicating if props are still loading.
210 
211**CRITICAL:** Widgets render **before** the tool completes execution. On first render:
212- `isPending` is `true`
213- `props` is an empty object `{}`
214- Accessing `props` fields will cause errors
215 
216**Widget Lifecycle:**
2171. Widget mounts immediately when tool is called → `isPending = true`, `props = {}`
2182. Tool executes and returns `widget({ props })`
2193. Widget re-renders → `isPending = false`, `props` contains data
220 
221```typescript
222const { isPending } = useWidget();
223 
224if (isPending) {
225  return (
226    <McpUseProvider autoSize>
227      <div>Loading...</div>
228    </McpUseProvider>
229  );
230}
231 
232// Now safe to access props - guaranteed to have data
233```
234 
235**Multiple patterns for handling isPending:**
236 
237```typescript
238// ✅ Pattern 1: Early return (recommended)
239if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
240return <McpUseProvider autoSize><div>{props.data}</div></McpUseProvider>;
241 
242// ✅ Pattern 2: Conditional rendering
243return (
244  <McpUseProvider autoSize>
245    {isPending ? <div>Loading...</div> : <div>{props.data}</div>}
246  </McpUseProvider>
247);
248 
249// ✅ Pattern 3: Optional chaining (when props might be undefined)
250return <McpUseProvider autoSize><div>{props?.data ?? "Loading..."}</div></McpUseProvider>;
251```
252 
253---
254 
255## McpUseProvider
256 
257**Required wrapper** for all widgets. Provides context and handles iframe sizing.
258 
259```typescript
260import { McpUseProvider } from "mcp-use/react";
261 
262export default function MyWidget() {
263  const { props, isPending } = useWidget();
264 
265  if (isPending) {
266    return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
267  }
268 
269  return (
270    <McpUseProvider autoSize>
271      <div>
272        {/* Your widget content */}
273      </div>
274    </McpUseProvider>
275  );
276}
277```
278 
279**Props:**
280- `autoSize={true}` - Automatically resize iframe to content (recommended)
281- `autoSize={false}` - Fixed height, widget handles scrolling
282 
283**Must wrap:**
284- ✅ Every return path (including loading states)
285- ✅ Root element of component
286 
287---
288 
289## Props Handling Patterns
290 
291### Simple Props
292```typescript
293export const widgetMetadata: WidgetMetadata = {
294  props: z.object({
295    message: z.string(),
296    count: z.number()
297  }),
298  exposeAsTool: false
299};
300 
301export default function SimpleWidget() {
302  const { props, isPending } = useWidget();
303 
304  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
305 
306  return (
307    <McpUseProvider autoSize>
308      <div>
309        <p>{props.message}</p>
310        <p>Count: {props.count}</p>
311      </div>
312    </McpUseProvider>
313  );
314}
315```
316 
317### Array Props
318```typescript
319export const widgetMetadata: WidgetMetadata = {
320  props: z.object({
321    items: z.array(z.object({
322      id: z.string(),
323      name: z.string()
324    }))
325  }),
326  exposeAsTool: false
327};
328 
329export default function ListWidget() {
330  const { props, isPending } = useWidget();
331 
332  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
333 
334  return (
335    <McpUseProvider autoSize>
336      <ul>
337        {props.items.map(item => (
338          <li key={item.id}>{item.name}</li>
339        ))}
340      </ul>
341    </McpUseProvider>
342  );
343}
344```
345 
346### Nested Props
347```typescript
348export const widgetMetadata: WidgetMetadata = {
349  props: z.object({
350    user: z.object({
351      name: z.string(),
352      profile: z.object({
353        bio: z.string(),
354        avatar: z.string()
355      })
356    })
357  }),
358  exposeAsTool: false
359};
360 
361export default function ProfileWidget() {
362  const { props, isPending } = useWidget();
363 
364  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
365 
366  const { user } = props;
367 
368  return (
369    <McpUseProvider autoSize>
370      <div>
371        <img src={user.profile.avatar} alt={user.name} />
372        <h2>{user.name}</h2>
373        <p>{user.profile.bio}</p>
374      </div>
375    </McpUseProvider>
376  );
377}
378```
379 
380### Optional Props
381```typescript
382export const widgetMetadata: WidgetMetadata = {
383  props: z.object({
384    title: z.string(),
385    subtitle: z.string().optional(),  // May be undefined
386    items: z.array(z.string())
387  }),
388  exposeAsTool: false
389};
390 
391export default function FlexibleWidget() {
392  const { props, isPending } = useWidget();
393 
394  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
395 
396  return (
397    <McpUseProvider autoSize>
398      <div>
399        <h1>{props.title}</h1>
400        {props.subtitle && <h2>{props.subtitle}</h2>}
401        <ul>
402          {props.items.map((item, i) => <li key={i}>{item}</li>)}
403        </ul>
404      </div>
405    </McpUseProvider>
406  );
407}
408```
409 
410---
411 
412## File Location
413 
414Widgets live in `resources/` directory:
415 
416```
417my-server/
418├── index.ts              # Server code
419├── resources/
420│   ├── weather-display.tsx    # Widget component
421│   ├── product-list.tsx
422│   └── calendar-view.tsx
423└── package.json
424```
425 
426**Naming convention:**
427- Use kebab-case for widget names
428- Tool config: `widget: { name: "weather-display" }`
429- File: `resources/weather-display.tsx`
430 
431---
432 
433## TypeScript Types
434 
435For type safety, infer props type from schema:
436 
437⚠️ **CRITICAL:** Always define your Zod schema in a separate constant before `widgetMetadata`. Never infer types from `widgetMetadata.props` - TypeScript will lose type information and the result will be `unknown`.
438 
439```typescript
440import { z } from "zod";
441import { McpUseProvider, useWidget, type WidgetMetadata } from "mcp-use/react";
442 
443const propsSchema = z.object({
444  city: z.string(),
445  temp: z.number(),
446  conditions: z.string()
447});
448 
449export const widgetMetadata: WidgetMetadata = {
450  description: "Display weather",
451  props: propsSchema,
452  exposeAsTool: false
453};
454 
455type Props = z.infer<typeof propsSchema>;
456 
457export default function WeatherWidget() {
458  const { props, isPending } = useWidget<Props>();
459 
460  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
461 
462  // Now props is fully typed!
463  return (
464    <McpUseProvider autoSize>
465      <div>
466        <h2>{props.city}</h2>  {/* ✓ TypeScript knows this is string */}
467        <p>{props.temp}°C</p>   {/* ✓ TypeScript knows this is number */}
468      </div>
469    </McpUseProvider>
470  );
471}
472```
473 
474---
475 
476## Common Mistakes
477 
478### ❌ Missing isPending Check
479```typescript
480// ❌ Bad - props undefined during loading
481export default function BadWidget() {
482  const { props } = useWidget();
483 
484  return (
485    <McpUseProvider autoSize>
486      <div>{props.title}</div>  {/* Error! */}
487    </McpUseProvider>
488  );
489}
490 
491// ✅ Good
492export default function GoodWidget() {
493  const { props, isPending } = useWidget();
494 
495  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
496 
497  return (
498    <McpUseProvider autoSize>
499      <div>{props.title}</div>
500    </McpUseProvider>
501  );
502}
503```
504 
505### ❌ Missing McpUseProvider
506```typescript
507// ❌ Bad - Missing provider
508export default function BadWidget() {
509  const { props, isPending } = useWidget();
510 
511  if (isPending) return <div>Loading...</div>;
512 
513  return <div>{props.title}</div>;  {/* Won't render correctly */}
514}
515 
516// ✅ Good
517export default function GoodWidget() {
518  const { props, isPending } = useWidget();
519 
520  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
521 
522  return (
523    <McpUseProvider autoSize>
524      <div>{props.title}</div>
525    </McpUseProvider>
526  );
527}
528```
529 
530### `exposeAsTool` — default is `false`
531```typescript
532// ✅ Default — widget is a resource only, exposed via a custom tool
533export const widgetMetadata: WidgetMetadata = {
534  description: "...",
535  props: z.object({ ... })
536  // exposeAsTool defaults to false
537};
538 
539// ✅ Explicit opt-in to auto-registration
540export const widgetMetadata: WidgetMetadata = {
541  description: "...",
542  props: z.object({ ... }),
543  exposeAsTool: true  // Auto-registers widget as a tool
544};
545```
546 
547### ❌ Missing Type Parameter on useWidget
548```typescript
549// ❌ Bad - props is UnknownObject, no autocomplete or type safety
550const propsSchema = z.object({
551  title: z.string(),
552  count: z.number()
553});
554 
555export default function BadWidget() {
556  const { props } = useWidget();  // props is UnknownObject
557  return <div>{props.title}</div>;  // No IDE support, runtime errors possible
558}
559 
560// ✅ Good - props is fully typed with IDE support
561const propsSchema = z.object({
562  title: z.string(),
563  count: z.number()
564});
565 
566type Props = z.infer<typeof propsSchema>;
567 
568export default function GoodWidget() {
569  const { props } = useWidget<Props>();  // props is properly typed
570  return <div>{props.title}</div>;  // Full autocomplete and type checking
571}
572```
573 
574### ❌ Inferring Type from widgetMetadata.props
575```typescript
576// ❌ Bad - Type inference fails, Props is unknown
577export const widgetMetadata: WidgetMetadata = {
578  description: "...",
579  props: z.object({
580    title: z.string(),
581    count: z.number()
582  })  // Inline schema definition
583};
584 
585type Props = z.infer<typeof widgetMetadata.props>;  // Props is unknown!
586 
587export default function BadWidget() {
588  const { props } = useWidget<Props>();
589  return <div>{props.title}</div>;  // No autocomplete, no type safety
590}
591 
592// ✅ Good - Extract schema first for proper type inference
593const propsSchema = z.object({
594  title: z.string(),
595  count: z.number()
596});
597 
598export const widgetMetadata: WidgetMetadata = {
599  description: "...",
600  props: propsSchema  // Reference the schema variable
601};
602 
603type Props = z.infer<typeof propsSchema>;  // Props is properly typed!
604 
605export default function GoodWidget() {
606  const { props } = useWidget<Props>();
607  return <div>{props.title}</div>;  // Full autocomplete and type checking
608}
609```
610 
611**Why this happens:** The `WidgetMetadata` type is generic, so TypeScript can't preserve the specific Zod schema type when defined inline. Always extract your schema to a separate constant before using it in `widgetMetadata`.
612 
613---
614 
615## Testing Widgets
616 
617### Option 1: Inspector (interactive)
618 
6191. Start dev server: `npm run dev`
6202. Open inspector: `http://localhost:3000/inspector`
6213. Click "List Tools" → Find your tool
6224. Click "Call Tool" → Enter test input
6235. Widget renders in inspector
624 
625**Quick iteration:**
626- Change widget code → Auto-reload
627- Adjust props schema → Update tool call input
628- Test edge cases (empty lists, missing optional props)
629 
630### Option 2: Headless screenshot (agent-friendly)
631 
632For visual feedback loops where you want to verify a widget change without leaving the terminal — call the tool, save a PNG, eyeball it, edit, repeat:
633 
634```bash
635# Saved-server form (assumes you ran `mcp-use client connect dev <url>` once)
636npx mcp-use client dev screenshot --tool get-weather city=Tokyo \
637  --width 800 --height 600 --theme light \
638  --output ./weather.png
639 
640# Ad-hoc form — no saved server, pass auth headers inline if needed
641npx mcp-use client screenshot --mcp http://localhost:3000/mcp \
642  --tool get-weather city=Tokyo
643```
644 
645- Args are `key=value` pairs, `key:='<json>'` for nested values, or one full JSON object
646- The saved-server form reuses the auth from `mcp-use client connect` (OAuth or `--auth <token>`); the ad-hoc form accepts `-H "Header: value"` (repeatable) for authenticated servers
647- Add `--device-scale-factor 2` for Retina output
648- For sandboxed environments without a local Chrome, point `--cdp-url <ws>` at a hosted Chromium (e.g. Notte) and `--inspector <publicly-reachable-url>` at a deployed inspector
649 
650Equivalently, `mcp-use client <name> tools call <tool> ... --screenshot` calls the tool *and* saves a widget PNG in one step — useful for one-shot verification.
651 
652---
653 
654## Complete Example
655 
656```typescript
657// index.ts
658import { MCPServer, widget, text } from "mcp-use/server";
659import { z } from "zod";
660 
661const server = new MCPServer({
662  name: "product-server",
663  version: "1.0.0"
664});
665 
666server.tool(
667  {
668    name: "search-products",
669    description: "Search products by keyword",
670    schema: z.object({
671      query: z.string().describe("Search query")
672    }),
673    widget: {
674      name: "product-list",
675      invoking: "Searching products...",
676      invoked: "Products loaded"
677    }
678  },
679  async ({ query }) => {
680    const products = await searchProducts(query);
681 
682    return widget({
683      props: {
684        products,
685        query,
686        totalCount: products.length
687      },
688      output: text(`Found ${products.length} products matching "${query}"`)
689    });
690  }
691);
692 
693server.listen();
694```
695 
696```tsx
697// resources/product-list.tsx
698import { McpUseProvider, useWidget, type WidgetMetadata } from "mcp-use/react";
699import { z } from "zod";
700 
701export const widgetMetadata: WidgetMetadata = {
702  description: "Display product search results",
703  props: z.object({
704    products: z.array(z.object({
705      id: z.string(),
706      name: z.string(),
707      price: z.number(),
708      image: z.string()
709    })),
710    query: z.string(),
711    totalCount: z.number()
712  }),
713  exposeAsTool: false
714};
715 
716export default function ProductList() {
717  const { props, isPending } = useWidget();
718 
719  if (isPending) {
720    return (
721      <McpUseProvider autoSize>
722        <div style={{ padding: 20 }}>Loading products...</div>
723      </McpUseProvider>
724    );
725  }
726 
727  return (
728    <McpUseProvider autoSize>
729      <div style={{ padding: 20 }}>
730        <h2>Search: "{props.query}"</h2>
731        <p>Found {props.totalCount} products</p>
732 
733        <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(200px, 1fr))", gap: 16 }}>
734          {props.products.map(product => (
735            <div key={product.id} style={{ border: "1px solid #ddd", padding: 12, borderRadius: 8 }}>
736              <img src={product.image} alt={product.name} style={{ width: "100%", height: 150, objectFit: "cover" }} />
737              <h3 style={{ fontSize: 16, margin: "8px 0" }}>{product.name}</h3>
738              <p style={{ fontSize: 18, fontWeight: "bold" }}>${product.price}</p>
739            </div>
740          ))}
741        </div>
742      </div>
743    </McpUseProvider>
744  );
745}
746```
747 
748---
749 
750## Next Steps
751 
752- **Manage widget state** → [state.md](state.md)
753- **Add interactivity** → [interactivity.md](interactivity.md)
754- **Style with themes** → [ui-guidelines.md](ui-guidelines.md)
755- **Advanced patterns** → [advanced.md](advanced.md)
756