<McpUseProvider />

Universal provider component for MCP Apps and ChatGPT Apps SDK widgets

The <McpUseProvider /> is a universal provider component that works with both MCP Apps and ChatGPT Apps SDK protocols. It automatically includes StrictMode, ThemeProvider, optional WidgetControls, and ErrorBoundary, providing a consistent setup regardless of which protocol your widget is using.

Protocol-Agnostic: This component works identically whether your widget is running in MCP Apps clients or ChatGPT. No conditional logic needed!

Import

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

Props

Prop	Type	Default	Description
children	React.ReactNode	required	The widget content to wrap
debugger	boolean	false	Enable debug button in WidgetControls component
viewControls	boolean | "pip" | "fullscreen"	false	Enable view controls (fullscreen/pip). true shows both, "pip" shows only pip, "fullscreen" shows only fullscreen
autoSize	boolean	false	Automatically notify the host about container height changes using ResizeObserver

What’s Included

The McpUseProvider automatically wraps your widget with:

1. StrictMode (outermost) - React’s development mode checks
2. ThemeProvider - Protocol-aware theme management (syncs with both MCP Apps and ChatGPT)
3. WidgetControls (conditional) - Debug and view controls if enabled (works with both protocols)
4. ErrorBoundary (innermost) - Error handling for graceful failures
5. Auto-sizing container (conditional) - ResizeObserver wrapper if autoSize={true} (adapts to protocol)

Breaking change (v1.20.1): McpUseProvider no longer includes BrowserRouter. If your widget uses react-router for navigation, add it explicitly:

import { BrowserRouter } from "react-router";

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

Basic Usage

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

function MyWidget() {
  return (
    <McpUseProvider>
      <div>My widget content</div>
    </McpUseProvider>
  );
}

With Debug Controls

Enable the debug button to inspect widget state, props, and test tool calls:

<McpUseProvider debugger>
  <MyWidget />
</McpUseProvider>

With View Controls

Enable fullscreen and picture-in-picture controls:

<McpUseProvider viewControls>
  <MyWidget />
</McpUseProvider>

With Auto-sizing

Enable automatic height notifications for dynamic content:

<McpUseProvider autoSize>
  <MyWidget />
</McpUseProvider>

Widgets that conditionally render null: When autoSize={true} is enabled and your widget returns null (e.g., when there are no results to display), the iframe will automatically collapse to zero height. This allows hosts to properly hide empty widgets.

function SearchWidget() {
  const { props } = useWidget<{ results: string[] }>();
  
  // Widget collapses when no results
  if (props.results?.length === 0) {
    return null;
  }
  
  return <div>{/* render results */}</div>;
}

Complete Example

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

function ProductWidget() {
  const { props } = useWidget<{ productName: string }>();

  return (
    <div>
      <h1>{props.productName}</h1>
      {/* Widget content */}
    </div>
  );
}

export default function App() {
  return (
    <McpUseProvider debugger viewControls autoSize>
      <ProductWidget />
    </McpUseProvider>
  );
}

Related Components

• WidgetControls - Debug and view controls
• ThemeProvider - Theme management
• ErrorBoundary - Error handling
• useWidget - Widget hook for accessing props and actions