Skip to main content
The <WidgetControls /> component adds control buttons for widget debugging and view controls (fullscreen/pip). It combines debug button and view controls with shared hover logic, making it easy to add development and testing capabilities to your widgets.
You can use <McpUseProvider viewControls /> to automatically include the <WidgetControls /> component.

​
Import

import { WidgetControls } from 'mcp-use/react';

​
Props

PropTypeDefaultDescription
childrenReact.ReactNoderequiredThe widget content to wrap
debuggerbooleanfalseEnable debug button to display widget debug information
viewControlsboolean | "pip" | "fullscreen"falseEnable view controls. true = both pip and fullscreen, "pip" = only pip, "fullscreen" = only fullscreen
position"top-left" | "top-center" | "top-right" | "center-left" | "center-right" | "bottom-left" | "bottom-center" | "bottom-right""top-right"Position of the control buttons
attachToHTMLElement | nullundefinedElement to attach controls to (for custom positioning)
showLabelsbooleantrueShow labels on control buttons
classNamestring""Additional CSS classes

​
Basic Usage

import { WidgetControls } from 'mcp-use/react';

function MyWidget() {
  return (
    <WidgetControls debugger viewControls>
      <div>My widget content</div>
    </WidgetControls>
  );
}

​
Debug Button

The debug button opens an overlay showing:
  • Props: Current widget props from toolInput
  • Output: Tool output data (toolOutput)
  • Metadata: Response metadata (toolResponseMetadata)
  • State: Persistent widget state (widgetState)
  • Theme: Current theme (light/dark)
  • Display Mode: Current display mode (inline/pip/fullscreen)
  • Safe Area: Safe area insets for mobile
  • User Agent: Device capabilities
  • Locale: User locale
  • window.openai Keys: All available keys on the window.openai object
The debug overlay also includes interactive testing:
  • Call Tool: Test calling other MCP tools
  • Send Follow-up Message: Send messages to ChatGPT conversation
  • Open External: Test opening external URLs
  • Set State: Update widget state

​
View Controls

View controls allow users to change the widget’s display mode:
  • Fullscreen Button: Expands widget to fullscreen mode
  • Picture-in-Picture Button: Shows widget in a floating window
These controls automatically appear/disappear based on the current display mode and availability.

​
Position Customization

Control buttons can be positioned in 8 different locations: 
// Top right (default)
<WidgetControls position="top-right" debugger>
  <MyWidget />
</WidgetControls>

// Bottom left
<WidgetControls position="bottom-left" debugger>
  <MyWidget />
</WidgetControls>

// Center right
<WidgetControls position="center-right" debugger>
  <MyWidget />
</WidgetControls>

​
Usage with McpUseProvider

WidgetControls is automatically included when using McpUseProvider with the debugger or viewControls props: 
import { McpUseProvider } from 'mcp-use/react';

<McpUseProvider debugger viewControls>
  <MyWidget />
</McpUseProvider>
This is the recommended approach as it also includes other necessary providers.
  • McpUseProvider - Unified provider that includes WidgetControls
  • useWidget - Hook for accessing widget data and actions