useWidget()

1. MCP Apps bridge (SEP-1865 postMessage), the primary runtime for hosted widget iframes including ChatGPT. The hook connects via ui/initialize and listens for ui/notifications/tool-input, ui/notifications/tool-input-partial, ui/notifications/tool-result, and ui/notifications/host-context-changed.
2. URL params fallback (mcpUseParams), used during local development (the mcp-use dev inspector) where toolInput and toolOutput are injected via the query string. There is no live streaming in this mode.

import {
  useWidget,
  useWidgetProps,
  useWidgetState,
  useWidgetTheme,
} from "mcp-use/react";
import type {
  UseWidgetResult,
  API,
  DisplayMode,
  SafeArea,
  SafeAreaInsets,
  Theme,
  DeviceType,
  UserAgent,
  OpenAiGlobals,
} from "mcp-use/react";

​

Hooks

​

useWidget

import { useWidget } from "mcp-use/react";

​

TProps

object

default:"UnknownObject"

Shape of props, mapped from structuredContent in the tool result (or from toolInput while pending).

​

TState

object

default:"UnknownObject"

Shape of the persisted widget state read and written via setState.

​

TOutput

object

default:"UnknownObject"

Shape of output, the raw structuredContent field from the tool result.

​

TMetadata

object

default:"UnknownObject"

Shape of metadata, the _meta object from the tool result.

​

TToolInput

object

default:"UnknownObject"

Shape of toolInput, the arguments the model passed to the tool.

​

defaultProps

TProps

default:"undefined"

Optional initial props used as the merge base before toolInput or structuredContent arrives. When omitted, the base is an empty object.

​

props

Partial<TProps> | TProps

Merged widget props. Partial<TProps> while isPending is true, then the full TProps once the tool result arrives. Defaults to defaultProps (or {}).

​

toolInput

TToolInput

The arguments the model passed when calling the tool, delivered via ui/notifications/tool-input. Defaults to {} when unavailable.

​

output

TOutput | null

The structuredContent field from the tool result. Widget-only data the LLM never sees. null while the tool is still executing.

​

metadata

TMetadata | null

The _meta object from the tool result (timestamps, cache headers, API version, etc.). Not in the model’s context. null while pending, and always null on the URL params fallback.

​

state

TState | null

Persisted widget state the model can read on future turns. null until setState is first called. The internal model-context key is stripped from the returned value.

​

setState

(state: TState | ((prevState: TState | null) => TState)) => Promise<void>

Update the persisted widget state. Accepts a new value or a functional updater (prev) => next. Sends ui/update-model-context so the LLM sees the new state next turn. Rapid updates before the next user message are deduplicated by the host.

​

theme

Theme

The host’s color-scheme preference, "light" or "dark". Defaults to "light". Changes arrive via ui/notifications/host-context-changed.

​

displayMode

DisplayMode

Current rendering context: "inline", "fullscreen", or "pip". Defaults to "inline". On mobile, "pip" is coerced to "fullscreen" by the host.

​

safeArea

SafeArea

Safe-area inset boundaries (in pixels) for OS chrome (notch, home indicator, system bars). Defaults to { insets: { top: 0, bottom: 0, left: 0, right: 0 } }. From HostContext.safeAreaInsets.

​

maxHeight

number

Maximum height the widget container can grow to, in pixels. Defaults to 600. From HostContext.containerDimensions.maxHeight.

​

maxWidth

number | undefined

Maximum width the widget container can grow to, in pixels. From HostContext.containerDimensions.maxWidth. undefined when unbounded or unavailable (no default is applied).

​

userAgent

UserAgent

Device type and input-capability flags. Defaults to { device: { type: "desktop" }, capabilities: { hover: true, touch: false } }. Derived from HostContext.platform and HostContext.deviceCapabilities.

​

locale

string

The user’s BCP 47 language and region tag (for example "en-US"). Defaults to WIDGET_DEFAULTS.LOCALE. From HostContext.locale.

​

timeZone

string

The user’s IANA timezone (for example "America/New_York"). From HostContext.timeZone. Falls back to the browser timezone (Intl.DateTimeFormat().resolvedOptions().timeZone), or "UTC" when no window is present.

​

mcp_url

string

Base URL of the MCP server running inside the sandbox, derived from window.__mcpPublicUrl with the /mcp-use/public suffix removed. "" when unavailable.

​

callTool

(name: string, args: Record<string, unknown>) => Promise<CallToolResponse>

Call any tool registered on the MCP server (including app-only tools). Sends tools/call via the host and returns a normalized CallToolResponse.

​

sendFollowUpMessage

(content: string | MessageContentBlock[]) => Promise<void>

Add a user-role message to the conversation and trigger a new model turn. A plain string is wrapped as a single text block; an array of MessageContentBlock is sent as-is. Sends ui/message.

​

openExternal

(href: string) => void

Ask the host to open a URL in the user’s browser or a new tab via ui/open-link. The host may deny the request; errors are logged, not thrown.

​

requestDisplayMode

(mode: DisplayMode) => Promise<{ mode: DisplayMode }>

Request a display-mode change via ui/request-display-mode. The host returns the actual granted mode, which may differ from the requested one.

​

isAvailable

boolean

true when the MCP Apps postMessage bridge has connected. false while connecting or on the URL params fallback (where it is always false).

​

isPending

boolean

true while the tool is still executing; becomes false once ui/notifications/tool-result is received. While true, props is Partial<TProps>. On the URL params fallback it is true until toolOutput is present.

​

partialToolInput

Partial<TToolInput> | null

Partial tool arguments streamed in real time while the LLM is still generating them, via ui/notifications/tool-input-partial. A best-effort parse of incomplete JSON (auto-closed brackets), so fields may be missing or change. null on the URL params fallback.

​

isStreaming

boolean

true while partialToolInput is non-null and the complete toolInput has not yet arrived. Always false on the URL params fallback.

​

hostInfo

{ name: string; version: string } | undefined

Name and version of the MCP Apps host from the ui/initialize handshake. undefined outside a supported MCP Apps host.

​

hostCapabilities

Record<string, unknown> | undefined

Capabilities advertised by the host during ui/initialize (SEP-1865 HostCapabilities). undefined outside a supported host or when none were sent.

​

hostContext

HostContext | undefined

Raw host context from the MCP Apps bridge. Includes standardized host style variables at hostContext.styles.variables when provided. undefined outside a supported host.

function useWidget<TProps = UnknownObject, TState = UnknownObject, TOutput = UnknownObject, TMetadata = UnknownObject, TToolInput = UnknownObject>(defaultProps?: TProps): UseWidgetResult<TProps, TState, TOutput, TMetadata, TToolInput>

import { useWidget } from "mcp-use/react";

interface WeatherProps {
  city: string;
  temperature: number;
}

const WeatherWidget: React.FC = () => {
  const { props, isPending, toolInput, theme } = useWidget<WeatherProps>();

  if (isPending) return <p>Loading...</p>;

  return (
    <div data-theme={theme}>
      <h1>{props.city}</h1>
      <p>{props.temperature}C</p>
      <p>Requested: {toolInput.city}</p>
    </div>
  );
};

import { MCPServer, widget } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "mcp-apps-example",
  version: "1.0.0",
  description: "Dual-protocol widget support (ChatGPT and MCP Apps clients)",
});

server.tool(
  {
    name: "get-weather",
    description: "Get current weather for a city",
    schema: z.object({ city: z.string().describe("City name") }),
    widget: {
      name: "weather-display",
      invoking: "Fetching weather data...",
      invoked: "Weather data loaded",
    },
  },
  async ({ city }) =>
    widget({
      props: { city, temperature: 22 },
      message: `Current weather in ${city}: 22C`,
    }),
);

await server.listen();

​

useWidgetProps

​

TProps

object

default:"UnknownObject"

Shape of the returned props.

​

defaultProps

TProps

default:"undefined"

Optional initial props used as the merge base, forwarded to useWidget.

​

returns

Partial<TProps>

The merged widget props. Fields may be undefined while the tool is still executing.

function useWidgetProps<TProps = UnknownObject>(defaultProps?: TProps): Partial<TProps>

import { useWidgetProps } from "mcp-use/react";

const props = useWidgetProps<{ city: string; temperature: number }>();
// { city: "Paris", temperature: 22 }

​

useWidgetState

​

TState

object

required

Shape of the persisted state.

​

defaultState

TState

default:"undefined"

Optional initial state. Applied via setState only when the current state is null and the runtime is available.

​

returns

readonly [TState | null, (state: TState | ((prev: TState | null) => TState)) => Promise<void>]

A readonly tuple of the current state (null until set) and the setState updater. The updater accepts a value or a functional updater and persists via ui/update-model-context.

function useWidgetState<TState>(defaultState?: TState): readonly [TState | null, (state: TState | ((prev: TState | null) => TState)) => Promise<void>]

import { useWidgetState } from "mcp-use/react";

const [favorites, setFavorites] = useWidgetState<string[]>([]);

await setFavorites(["item1", "item2"]);
await setFavorites((prev) => [...(prev ?? []), "newItem"]);

​

useWidgetTheme

​

returns

Theme

The host’s color-scheme preference, "light" or "dark". Defaults to "light".

function useWidgetTheme(): Theme

import { useWidgetTheme } from "mcp-use/react";

const theme = useWidgetTheme(); // "light" | "dark"

​

Types

​

UseWidgetResult

​

TProps

object

default:"UnknownObject"

Shape of props.

​

TState

object

default:"UnknownObject"

Shape of state.

​

TOutput

object

default:"UnknownObject"

Shape of output.

​

TMetadata

object

default:"UnknownObject"

Shape of metadata.

​

TToolInput

object

default:"UnknownObject"

Shape of toolInput.

type UseWidgetResult<TProps = UnknownObject, TState = UnknownObject, TOutput = UnknownObject, TMetadata = UnknownObject, TToolInput = UnknownObject> = UseWidgetResultBase<TState, TOutput, TMetadata, TToolInput> & ({ isPending: true; props: Partial<TProps> } | { isPending: false; props: TProps })

​

API

​

WidgetState

UnknownObject

default:"UnknownObject"

Shape of the persisted widget state passed to setWidgetState.

​

callTool

(name: string, args: Record<string, unknown>) => Promise<CallToolResponse>

Call a tool on your MCP server and return the full response.

​

sendFollowUpMessage

(args: { prompt: string }) => Promise<void>

Trigger a follow-up turn in the conversation.

​

openExternal

(payload: { href: string }) => void

Open an external link, redirect the web page, or open a mobile app.

​

requestDisplayMode

(args: { mode: DisplayMode }) => Promise<{ mode: DisplayMode }>

Transition the app between inline, fullscreen, and pip. The host may reject the request, and on mobile pip is always coerced to fullscreen.

​

setWidgetState

(state: WidgetState) => Promise<void>

Persist widget state that will be shown to the model.

​

notifyIntrinsicHeight

(height: number) => Promise<void>

Notify OpenAI about intrinsic height changes for auto-sizing.

​

uploadFile

((file: File) => Promise<FileMetadata>) | undefined

Upload a file to the host. Optional: only present when the OpenAI extension exposes file APIs. Detect availability with useFiles().isSupported.

​

getFileDownloadUrl

((file: FileMetadata) => Promise<{ downloadUrl: string }>) | undefined

Get a temporary download URL for a previously uploaded file. Optional: only present when the OpenAI extension exposes file APIs.

interface API<WidgetState extends UnknownObject = UnknownObject> {
  callTool: (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
  sendFollowUpMessage: (args: { prompt: string }) => Promise<void>;
  openExternal(payload: { href: string }): void;
  requestDisplayMode: (args: { mode: DisplayMode }) => Promise<{ mode: DisplayMode }>;
  setWidgetState: (state: WidgetState) => Promise<void>;
  notifyIntrinsicHeight: (height: number) => Promise<void>;
  uploadFile?: (file: File) => Promise<FileMetadata>;
  getFileDownloadUrl?: (file: FileMetadata) => Promise<{ downloadUrl: string }>;
}

​

DisplayMode

type DisplayMode = "pip" | "inline" | "fullscreen"

​

SafeArea

​

insets

SafeAreaInsets

The four-sided inset measurements, in pixels.

type SafeArea = {
  insets: SafeAreaInsets;
}

​

SafeAreaInsets

​

top

number

Inset from the top edge, in pixels.

​

bottom

number

Inset from the bottom edge, in pixels.

​

left

number

Inset from the left edge, in pixels.

​

right

number

Inset from the right edge, in pixels.

type SafeAreaInsets = {
  top: number;
  bottom: number;
  left: number;
  right: number;
}

​

Theme

type Theme = "light" | "dark"

​

DeviceType

type DeviceType = "mobile" | "tablet" | "desktop" | "unknown"

​

UserAgent

​

device

{ type: DeviceType }

The reported device class.

​

capabilities

{ hover: boolean; touch: boolean }

Input capabilities: whether the device supports hover and whether it supports touch.

type UserAgent = {
  device: { type: DeviceType };
  capabilities: {
    hover: boolean;
    touch: boolean;
  };
}

​

OpenAiGlobals

​

ToolInput

UnknownObject

default:"UnknownObject"

Shape of the tool input arguments.

​

ToolOutput

UnknownObject

default:"UnknownObject"

Shape of the tool output.

​

ToolResponseMetadata

UnknownObject

default:"UnknownObject"

Shape of the tool response metadata.

​

WidgetState

UnknownObject

default:"UnknownObject"

Shape of the persisted widget state.

​

theme

Theme

Current color-scheme preference.

​

userAgent

UserAgent

Device type and input-capability flags.

​

locale

string

The user’s BCP 47 locale tag.

​

maxHeight

number

Maximum container height, in pixels.

​

displayMode

DisplayMode

Current display mode.

​

safeArea

SafeArea

Safe-area insets for the current layout.

​

toolInput

ToolInput

The arguments the model passed to the tool.

​

toolOutput

ToolOutput | null

The tool output, or null while pending.

​

toolResponseMetadata

ToolResponseMetadata | null

The tool response metadata, or null while pending.

​

widgetState

WidgetState | null

The persisted widget state, or null when unset.

interface OpenAiGlobals<ToolInput extends UnknownObject = UnknownObject, ToolOutput extends UnknownObject = UnknownObject, ToolResponseMetadata extends UnknownObject = UnknownObject, WidgetState extends UnknownObject = UnknownObject> {
  theme: Theme;
  userAgent: UserAgent;
  locale: string;
  maxHeight: number;
  displayMode: DisplayMode;
  safeArea: SafeArea;
  toolInput: ToolInput;
  toolOutput: ToolOutput | null;
  toolResponseMetadata: ToolResponseMetadata | null;
  widgetState: WidgetState | null;
}

​

Widget lifecycle

1. First render (isPending === true): the widget mounts immediately, props is Partial<TProps>, and output and metadata are null. Render a loading state here.
2. After the tool completes (isPending === false): props is the full TProps, and output and metadata are populated. The widget re-renders with full data.

const MyWidget: React.FC = () => {
  const { props, isPending } = useWidget<{ city: string; temperature: number }>();

  if (isPending) return <LoadingSpinner />;

  // props.city and props.temperature are non-optional here
  return (
    <div>
      {props.city} - {props.temperature}C
    </div>
  );
};

​

Default values

• theme: "light"
• displayMode: "inline"
• safeArea: { insets: { top: 0, bottom: 0, left: 0, right: 0 } }
• maxHeight: 600
• userAgent: { device: { type: "desktop" }, capabilities: { hover: true, touch: false } }
• locale: WIDGET_DEFAULTS.LOCALE
• timeZone: browser timezone, or "UTC" when no window
• props: defaultProps when provided, otherwise {}
• output: null
• metadata: null
• state: null
• maxWidth: no default (stays undefined when unavailable)

​

Related

• McpUseProvider for unified widget setup including auto-sizing.
• WidgetControls for debug and view controls.
• ThemeProvider for theme management.
• ErrorBoundary for widget error handling.