McpUseProvider

View the source code for this module on GitHub: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/react/McpUseProvider.tsx

Universal provider component for mcp-use widgets. It works identically whether your widget runs in MCP Apps clients (Claude, Goose) or in ChatGPT via the Apps SDK, so no protocol-specific conditional logic is needed in your widget code. McpUseProvider composes the common React setup for a widget into a single wrapper. From outermost to innermost it renders StrictMode, then ThemeProvider, then (conditionally) WidgetControls, then ErrorBoundary around your children. When autoSize is enabled it also wraps the tree in a container div that a ResizeObserver measures to notify the host of height changes.

Unified provider component that combines all common React setup for mcp-use widgets.

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

Wraps widget children with the standard mcp-use provider stack. Always includes StrictMode (outermost), ThemeProvider, and ErrorBoundary (innermost). Conditionally adds WidgetControls when debugger is true or viewControls is set, and an auto-sizing container div when autoSize is true. The auto-sizing container uses a ResizeObserver on the wrapping div to detect content height changes and notifies the host through the MCP Apps bridge (ui/notifications/size-changed). Notifications are debounced by 150ms to let animations settle, and a positive height change is only sent when it differs from the last reported height by at least 5px. A zero height is always reported, which lets the host collapse and hide an empty widget. When the widget renders inside the top-level window (not an iframe, where window === window.parent) the height notification is skipped. If ResizeObserver is unavailable or window is undefined (server-side rendering), auto-sizing is a no-op. Props

React.ReactNode
required
The widget content to wrap.

boolean
default:"false"
Enable the debug button in the WidgetControls component. When true, WidgetControls is rendered around the content.

boolean | "pip" | "fullscreen"
default:"false"
Enable view controls in the WidgetControls component. true shows both the picture-in-picture and fullscreen buttons, "pip" shows only the picture-in-picture button, and "fullscreen" shows only the fullscreen button. Any truthy value also causes WidgetControls to be rendered.

boolean
default:"true"
Automatically notify the host about container height changes for auto-sizing using a ResizeObserver on the children container, sent via the MCP Apps ui/notifications/size-changed notification.

boolean
default:"true"
Set color-scheme on the document root to match the active theme, enabling native dark scrollbars and the CSS light-dark() function. Disable only when you need the browser canvas to stay transparent in hosts that render widgets over a differently themed background. Forwarded to ThemeProvider.

Signature

function McpUseProvider({ children, debugger: enableDebugger = false, viewControls = false, autoSize = true, colorScheme = true }: McpUseProviderProps): React.ReactElement

The default for autoSize is true in the current source. Widgets are auto-sized out of the box. Pass autoSize={false} to opt out.

Types

The props object accepted by McpUseProvider.

McpUseProviderProps

Shape of the props object passed to McpUseProvider. Fields

React.ReactNode
required
The widget content to wrap.

boolean
Optional. Enable the debug button in WidgetControls. Defaults to false.

boolean | "pip" | "fullscreen"
Optional. Enable view controls in WidgetControls. Defaults to false.

boolean
Optional. Enable host height notifications via ResizeObserver. Defaults to true.

boolean
Optional. Set color-scheme on the document root to match the active theme. Defaults to true.

Signature

interface McpUseProviderProps {
  children: React.ReactNode;
  debugger?: boolean;
  viewControls?: boolean | "pip" | "fullscreen";
  autoSize?: boolean;
  colorScheme?: boolean;
}

What is included

McpUseProvider builds the component tree with conditional wrappers, from outermost to innermost:

StrictMode (always, outermost): React development-mode checks.
ThemeProvider (always): protocol-aware theme management, syncs with both MCP Apps and ChatGPT. Receives the colorScheme prop.
WidgetControls (conditional): rendered when debugger is true or viewControls is set. Receives debugger and viewControls.
Auto-sizing container div (conditional): rendered when autoSize is true. Styled with width: "100%" and minHeight: 0, and observed by a ResizeObserver.
ErrorBoundary (always, innermost): catches render errors for graceful failures.

Usage

Minimal usage wraps a single widget component. The widget itself is registered server-side and rendered inside the iframe; the example server below shows the matching server tool that drives a weather-display widget.

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

export default function App() {
  return (
    <McpUseProvider>
      <div>My widget content</div>
    </McpUseProvider>
  );
}

Enable the debug button, view controls, and auto-sizing together:

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

export default function App() {
  return (
    <McpUseProvider debugger viewControls autoSize>
      <div>My widget content</div>
    </McpUseProvider>
  );
}

The matching server registers a tool that returns the widget. Use new MCPServer({ ... }) to construct the server:

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

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

server.tool(
  {
    name: "get-weather",
    description:
      "Get current weather for a city (works with ChatGPT and MCP Apps clients)",
    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 },
      message: `Current weather in ${city}`,
    })
);

await server.listen();

When autoSize is enabled (the default) and your widget returns null, for example when there are no results to display, the ResizeObserver reports a zero height. A zero height is always sent to the host (it bypasses the 5px change threshold), so the host can collapse the iframe and hide the empty widget.

McpUseProvider does not include BrowserRouter. If your widget uses react-router for navigation, add it explicitly inside the provider:

import { BrowserRouter } from "react-router";
import { McpUseProvider } from "mcp-use/react";

<McpUseProvider>
  <BrowserRouter>
    <MyWidget />
  </BrowserRouter>
</McpUseProvider>;

WidgetControls: debug and view controls.
ThemeProvider: theme management.
ErrorBoundary: error handling.
useWidget: widget hook for accessing props and actions.

Overview

Server

React

Client

Agent

McpUseProvider

McpUseProvider

Types

McpUseProviderProps

What is included

Usage

​McpUseProvider

​Types

​McpUseProviderProps

​What is included

​Usage

​Related

McpUseProvider

Types

McpUseProviderProps

What is included

Usage

Related