Debugging Widgets

​

Overview

​

What are Widget Protocols?

​

How the Inspector Helps

• Dual-Protocol Testing: Switch between MCP Apps and ChatGPT protocols
• Protocol Toggle: Test cross-compatibility with one click
• Widget Rendering: Preview widgets in both protocols
• Debug Controls: Test different devices, locales, CSP modes
• Display Modes: Test inline, picture-in-picture, fullscreen
• Interactive Debugging: Test widget interactions and tool calls
• Dev Mode Support: Hot reload for widget development

​

Protocol Toggle

• MCP Apps - Tests the SEP-1865 protocol with JSON-RPC communication
• ChatGPT Apps - Tests the Apps SDK protocol with window.openai emulation

​

MCP Apps Debug Controls

​

Device Emulation

• Desktop - Large viewport, hover support
• Mobile - Small viewport, touch support
• Tablet - Medium viewport, both touch and hover

​

Locale & Timezone

• Locale Selector - Choose from 100+ locales (en-US, es-ES, ja-JP, etc.)
• Timezone Selector - Test timezone-specific behavior (MCP Apps only)

​

CSP Mode Toggle

• Permissive - Relaxed CSP for debugging
• Widget-Declared - Enforces widget’s declared CSP (production mode)

​

Capabilities Testing

• Touch - Enable/disable touch input simulation
• Hover - Enable/disable hover state detection

​

Safe Area Insets

• Top - Notch or status bar area
• Bottom - Home indicator area
• Left/Right - Display cutouts

​

Display Mode Controls

• Inline - Default embedded view
• Picture-in-Picture - Floating window (click PiP button)
• Fullscreen - Full browser window (click fullscreen button)

​

Props Management

• Use Tool Input - Use current tool call parameters
• Select Preset - Choose from saved prop configurations
• Create Preset - Save current props for reuse
• Edit Props - Manually modify prop values

​

ChatGPT Apps SDK: window.openai API Emulation

​

API Overview

• Global Properties: Theme, display mode, tool data, widget state
• Methods: Tool calls, follow-up messages, display mode requests
• Events: Global change notifications via openai:set_globals events

​

Global Properties

​

toolInput

const input = window.openai.toolInput;
// { city: "San Francisco", category: "pizza" }

​

toolOutput

const output = window.openai.toolOutput;
// { places: [...], metadata: {...} }

​

toolResponseMetadata

​

widgetState

// Read current state
const state = window.openai.widgetState;

// Update state (persists across widget interactions)
await window.openai.setWidgetState({ favorites: [...] });

​

displayMode

const mode = window.openai.displayMode;
// "inline" | "pip" | "fullscreen"

​

theme

const theme = window.openai.theme;
// "light" | "dark"

​

maxHeight

const height = window.openai.maxHeight;
// 600 (default)

​

locale

const locale = window.openai.locale;
// "en-US" (default)

​

safeArea

const safeArea = window.openai.safeArea;
// { insets: { top: 0, bottom: 0, left: 0, right: 0 } }

​

userAgent

const userAgent = window.openai.userAgent;
// { device: { type: "desktop" }, capabilities: { hover: true, touch: false } }

​

API Methods

​

callTool(name, params)

const result = await window.openai.callTool("get_restaurants", {
  city: "San Francisco",
  category: "pizza",
});

// Result format matches OpenAI's expected structure:
// { content: [{ type: "text", text: "..." }] }

• Sends postMessage to parent (inspector)
• Inspector executes tool via MCP connection
• Result is formatted to match OpenAI’s expected format
• MCP contents array is converted to OpenAI content format
• 30-second timeout for tool calls

​

sendFollowUpMessage(args)

await window.openai.sendFollowUpMessage({
  prompt: "Show me more details about the first restaurant",
});

• Dispatches custom event mcp-inspector:widget-followup
• Message appears in Chat tab
• Can be used to continue conversation from widget interactions

​

setWidgetState(state)

await window.openai.setWidgetState({
  favorites: ["restaurant-1", "restaurant-2"],
  filters: { price: "$$" },
});

• Stores state in browser localStorage
• Keyed by widget instance ID
• State is rehydrated on widget load
• Sent to parent via postMessage for inspector awareness

​

requestDisplayMode(options)

const result = await window.openai.requestDisplayMode({
  mode: "fullscreen",
});
// Returns: { mode: "fullscreen" }

• "inline" - Default embedded view
• "pip" - Picture-in-Picture floating window
• "fullscreen" - Full browser window

• Uses native Fullscreen API when available
• Falls back to CSS-based fullscreen
• On mobile, PiP may be coerced to fullscreen
• Updates displayMode property and dispatches events

​

openExternal(payload)

window.openai.openExternal({
  href: "https://example.com",
});

// Or with string
window.openai.openExternal("https://example.com");

• Uses window.open() with security flags
• Opens in new tab with noopener,noreferrer

​

notifyIntrinsicHeight(height)

await window.openai.notifyIntrinsicHeight(800);

• Sends postMessage with type openai:notifyIntrinsicHeight
• Inspector updates iframe height accordingly
• Height is capped based on display mode (fullscreen/pip respect viewport)
• Used by McpUseProvider with autoSize={true} for automatic height updates

// Manual height notification
const container = document.getElementById("widget-content");
const height = container.scrollHeight;
await window.openai.notifyIntrinsicHeight(height);

// Or use McpUseProvider with autoSize for automatic updates
<McpUseProvider autoSize>
  <MyWidget />
</McpUseProvider>;

​

Console Proxy Toggle

​

Enabling Console Proxy

1. Open the Console panel in the inspector (click the terminal icon)
2. Toggle “Proxy logs to page console” switch
3. Console logs from the widget iframe will now appear in your browser’s developer console

​

Features

• Persistent Preference: Your preference is saved in localStorage and persists across sessions
• Formatted Output: Logs are prefixed with [WIDGET CONSOLE] for easy identification
• Log Level Preservation: Error, warn, info, debug, and trace levels are preserved
• JSON Formatting: Objects are automatically stringified for better readability

​

Use Cases

• Debugging Widget Issues: See all console logs in one place
• Development Workflow: Use browser DevTools features (filtering, searching)
• Error Tracking: Easier to spot errors and warnings

​

Widget State Inspection

​

Viewing Widget State

• 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

​

Debug Information Display

• Real-time state updates
• Interactive tool testing
• State modification capabilities
• Full widget context visibility

​

State Inspection API

// Inspector sends: mcp-inspector:getWidgetState
window.addEventListener("message", (event) => {
  if (event.data?.type === "mcp-inspector:getWidgetState") {
    window.parent.postMessage(
      {
        type: "mcp-inspector:widgetStateResponse",
        toolId: event.data.toolId,
        state: window.openai.widgetState,
      },
      "*",
    );
  }
});

​

Events

​

openai:set_globals

window.addEventListener("openai:set_globals", (event) => {
  const { globals } = event.detail;
  // globals contains all updated properties
  console.log("Theme changed:", globals.theme);
  console.log("Display mode:", globals.displayMode);
});

• Initial widget load
• Display mode changes
• Theme changes
• Any global property update from parent

{
  globals: {
    toolInput: {...},
    toolOutput: {...},
    toolResponseMetadata: null,
    widgetState: {...},
    displayMode: "inline",
    maxHeight: 600,
    theme: "dark",
    locale: "en-US",
    safeArea: {...},
    userAgent: {...}
  }
}

​

React Helper Hooks

function useOpenAiGlobal(key) {
  return useSyncExternalStore(
    (onChange) => {
      const handleSetGlobal = (event) => {
        if (event.detail.globals[key] !== undefined) {
          onChange();
        }
      };
      window.addEventListener("openai:set_globals", handleSetGlobal);
      return () => {
        window.removeEventListener("openai:set_globals", handleSetGlobal);
      };
    },
    () => window.openai[key],
  );
}

// Usage
function MyWidget() {
  const theme = useOpenAiGlobal("theme");
  const toolOutput = useOpenAiGlobal("toolOutput");

  return (
    <div className={theme === "dark" ? "dark" : "light"}>
      {/* Widget content */}
    </div>
  );
}

​

Implementation Details

​

API Injection

1. Widget HTML is fetched from MCP server
2. Inspector injects API script before widget content
3. API object is attached to window.openai and window.webplus (for compatibility)
4. Initial globals event is dispatched
5. Message listeners are set up for parent communication

​

Communication Protocol

• openai:callTool - Tool execution requests
• openai:sendFollowup - Follow-up messages
• openai:requestDisplayMode - Display mode changes
• openai:setWidgetState - State updates

• openai:callTool:response - Tool call results
• openai:globalsChanged - Global property updates
• openai:displayModeChanged - Display mode changes (legacy)

​

State Persistence

• Key format: mcp-inspector-widget-state-${toolId}
• Storage: Browser localStorage (scoped to inspector domain)
• Lifetime: Persists across page reloads
• Scope: Per widget instance

​

Tool Result Formatting

{
  "contents": [{ "type": "text", "text": "Result" }]
}

{
  "content": [{ "type": "text", "text": "Result" }]
}

​

Compatibility

• OpenAI Apps SDK: Full API compatibility
• Legacy APIs: sendFollowupTurn (aliased to sendFollowUpMessage)
• React Router: URL normalization for routing
• Multiple display modes: Inline, PiP, Fullscreen

​

Differences from ChatGPT

1. User Agent: Inspector provides mock user agent data
2. Safe Area: Defaults to zero insets (not mobile-specific)
3. Locale: Defaults to “en-US” (not user-specific)
4. Tool Results: Converted from MCP format to OpenAI format
5. Follow-ups: Appear in inspector Chat tab instead of ChatGPT

​

Testing Your Widget

1. Develop locally with inspector
2. Test all API methods in your widget
3. Verify state persistence across interactions
4. Test display mode transitions
5. Verify tool calls work correctly
6. Check theme adaptation
7. Test in ChatGPT for final verification

​

Official Documentation

• OpenAI Apps SDK - Build a custom UX - Official API documentation
• OpenAI Apps SDK Reference - Complete API reference

​

Connecting Your ChatGPT App

​

Setting Up Your MCP Server

import { MCPServer } from "mcp-use/server";

const server = new MCPServer({
  name: "my-chatgpt-app",
  version: "1.0.0",
});

// Add a tool that returns a widget
server.addTool({
  name: "create_dashboard",
  description: "Create an interactive dashboard",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      data: { type: "object" },
    },
  },
  handler: async (args) => {
    // Return widget URI in metadata
    return {
      contents: [
        {
          type: "text",
          text: "Dashboard created",
        },
      ],
      _meta: {
        "openai/outputTemplate": "dashboard-widget-123",
      },
    };
  },
});

​

Connecting via Inspector

1. Start your MCP server
2. Open the inspector (local or hosted)
3. Connect to your server URL:
   • Local: http://localhost:3000/mcp
   • Remote: https://your-server.com/mcp
4. Server appears in Connected Servers list

​

Authentication Setup

1. Configure OAuth in connection settings
2. Or add custom headers with API keys
3. Complete authentication flow
4. Inspector stores credentials securely

​

Testing Tools

​

Executing Tools

1. Navigate to Tools tab
2. Find your tool in the list
3. Click to select it
4. Enter test parameters
5. Click Execute
6. View results in real-time

​

Viewing Tool Results

• Text Output: Plain text responses
• Structured Data: JSON responses
• Widget References: Links to OpenAI Apps SDK widgets
• Metadata: Tool execution metadata

​

Testing with Different Parameters

1. Execute tool with different parameters
2. Save successful requests for replay
3. Test error handling
4. Verify parameter validation

​

Widget/Component Testing

​

OpenAI Apps SDK Widget Support

• Widget Rendering: Interactive widget display
• Dev Mode: Hot reload during development
• Display Modes: Inline, Picture-in-Picture, Fullscreen
• CSP Handling: Content Security Policy support

​

Rendering Widgets

1. Tool executes successfully
2. Inspector detects widget URI in metadata
3. Widget automatically loads and renders
4. Interactive components become available

• Looks for openai/outputTemplate in tool metadata
• Fetches widget resource from MCP server
• Renders in dedicated widget container

​

Widget Lifecycle Testing

1. Tool Called → Widget iframe created immediately
2. Widget Renders → isPending=true, shows loading state
3. Tool Completes → Widget receives result via window.openai updates
4. Widget Updates → isPending=false, shows data

1. Use a tool that takes >2 seconds to complete
2. Widget should show loading state immediately (not after tool completes)
3. Open browser DevTools console
4. Look for logs showing isPending: true then isPending: false
5. Verify widget transitions from loading UI to data display

[MyWidget] isPending: true, props: {}           // Immediate render
[MyWidget] isPending: false, props: {city: ...} // After tool completes

​

Dev Mode for Widgets

1. Set widget metadata with dev flag:
   Copy

   Ask AI

   _meta: {
     'mcp-use/widget': {
       name: 'my-widget',
       html: 'widget.html',
       dev: true  // Enable dev mode
     }
   }
   
2. Inspector uses dev server URL
3. Changes reload automatically
4. Console logs visible in inspector

​

Widget Display Modes

• Default mode
• Embedded in result panel
• Scrollable content

• Floating window
• Stays visible while scrolling
• Resizable and draggable

• Full browser window
• Maximum visibility
• Exit with ESC or close button

• Widget can request mode changes
• Inspector handles transitions
• State persists during session

​

Widget CSP Handling

• CSP metadata from tool results
• Applied to widget iframe
• Secure sandbox environment
• Script execution allowed

​

Interactive Widget Features

​

Tool Calls from Widgets

1. Widget uses window.openai.callTool()
2. Inspector intercepts the call
3. Executes tool via MCP connection
4. Returns result to widget
5. Widget updates with response

// In your widget
const result = await window.openai.callTool("get_data", {
  userId: "123",
});

​

Follow-up Messages

1. Widget calls window.openai.sendFollowup()
2. Inspector captures the message
3. Message appears in Chat tab
4. ChatGPT processes the follow-up
5. Conversation continues

• User interactions in widget
• Dynamic conversation flow
• Context-aware responses

​

Widget State Management

• Tool Input: Parameters passed to tool
• Tool Output: Results from tool execution
• Widget Data: Resource content for widget
• Display State: Current display mode

​

Console Logging from Widgets

1. Widget console logs appear in inspector
2. Access via console panel in widget container
3. Filter by log level
4. Debug widget issues

• Real-time log streaming
• Log level filtering
• Error highlighting
• Stack trace display

​

Debugging Workflow

​

Step-by-Step Process

1. Connect to Server
   • Add your MCP server in inspector
   • Verify connection status
2. Test Tools
   • Execute each tool independently
   • Verify parameters and responses
   • Check for errors
3. Test Widgets
   • Execute tools that return widgets
   • Verify widget rendering
   • Use Protocol Toggle to test both protocols (if dual-protocol)
   • Test widget interactions and tool calls
   • Test different display modes (inline, PiP, fullscreen)
4. Test Device Compatibility
   • Use Device Emulation (Desktop/Mobile/Tablet)
   • Test different locales and timezones
   • Verify CSP compliance (Widget-Declared mode)
   • Test touch and hover capabilities
5. Test Integration
   • Use Chat tab with LLM
   • Verify tool calls from AI
   • Check widget rendering in context
6. Debug Issues
   • Check console logs
   • Review tool results
   • Verify widget metadata
   • Test error scenarios

​

Common Issues and Solutions

• MCP Apps: Check _meta.ui.resourceUri or _meta["ui/resourceUri"] in metadata
• ChatGPT: Check openai/outputTemplate in metadata
• Verify widget resource exists at the specified path
• Check CSP settings match widget’s network requirements
• Use Protocol Toggle to test if it works in the other protocol
• Review console for errors

• Verify tool name matches
• Check parameter schema
• Review authentication
• Check server logs

• ChatGPT: Verify window.openai API availability in widget
• MCP Apps: Check JSON-RPC postMessage communication
• Check widget iframe sandbox permissions
• Review console for errors
• Test in different display modes
• Try switching protocols with Protocol Toggle

​

Testing Widget Interactions

1. Render Widget: Execute tool to load widget
2. Interact: Click buttons, fill forms in widget
3. Monitor: Watch console for tool calls
4. Verify: Check tool results and widget updates
5. Iterate: Fix issues and retest

​

Verifying Tool Outputs

• Preview Mode: See formatted widget output
• JSON Mode: View raw tool response
• Metadata: Check widget references
• Structure: Verify data format

​

Best Practices

​

Development vs Production Widgets

• Use dev mode for hot reload
• Enable console logging and verbose debugging
• Use Permissive CSP mode for easier debugging
• Test in all display modes and device types
• Test both protocols (MCP Apps and ChatGPT)
• Verify error handling and fallbacks

• Disable dev mode
• Use Widget-Declared CSP mode to catch violations
• Minimize console output
• Test with production CSP restrictions
• Verify performance across device types
• Test internationalization with different locales

​

Testing Widget Responsiveness

• Test in different display modes (inline, PiP, fullscreen)
• Use Device Emulation to test Desktop/Mobile/Tablet
• Verify mobile layouts with safe area insets
• Check resize behavior and auto-resize (MCP Apps)
• Test PiP mode transitions
• Test with different locales and timezones

​

Handling Widget Errors

• Implement error boundaries
• Show user-friendly messages
• Log errors to console
• Provide fallback UI

​

Performance Considerations

• Optimize widget loading
• Minimize initial bundle size
• Lazy load components
• Cache widget resources

​

Next Steps

• MCP Apps - Build widgets with the standard MCP protocol
• ChatGPT Apps SDK - Build ChatGPT-specific widgets
• Widget Components - React hooks and components
• Inspector Overview - Inspector features and usage
• Connection Settings - Advanced inspector configuration