Skip to main content
Use the Inspector to debug a widget before you try it in a production host. The fastest loop is: connect your server, run the tool that returns the widget, inspect the widget data, then test layout, display modes, and CSP. For building widgets, start with Build widgets. For hook fields and host actions, use the useWidget() API reference.

​
Connect the widget server

Run your mcp-use app locally:
Open http://localhost:3000/inspector and connect to http://localhost:3000/mcp. If the server is remote, connect to its MCP endpoint instead. Use Direct first, then try Via Proxy only when the browser cannot reach the server directly.

​
Run the widget-returning tool

Open the Tools tab, select the tool that returns the widget, and run it with a small input. The widget should render below the tool result. The raw result should include the widget metadata and the structured data passed to the widget. If the tool succeeds but no widget renders, check these values first:
  • widget.name in the server tool definition
  • the matching folder under resources/
  • the tool result metadata that points to the widget resource
  • browser console errors from the widget iframe

​
Switch protocols when compatibility matters

The Inspector can test MCP Apps behavior and ChatGPT Apps SDK compatibility for widgets that support both runtimes. Use the protocol toggle when it appears: Prefer useWidget() and other mcp-use/react hooks in widget code. They abstract over the runtime differences that the Inspector is testing. See Apps SDK compatibility when you need ChatGPT-specific behavior.

​
Inspect props, output, metadata, and state

Use the widget debug panels to confirm what the widget receives. When props are missing, compare the server’s outputSchema with the widget’s expected prop shape. They should describe the same fields.

​
Test layout and display modes

Use the debug controls to test the widget in the contexts a host may provide. Check:
  • inline, picture-in-picture, and fullscreen display modes
  • desktop, tablet, and mobile sizing
  • touch and hover behavior
  • light and dark themes
  • locale and timezone-dependent formatting
  • safe-area insets for mobile layouts
The host may grant a different display mode than the widget requests. Read displayMode from useWidget() when the current mode matters.

​
Test Content Security Policy

Use the widget-declared CSP mode before shipping a widget that loads external APIs, images, scripts, styles, or embeds. If the widget works in permissive mode but fails with widget-declared CSP, update the widget CSP configuration. See Content Security Policy for the server and widget settings.

​
Use console output

Open browser DevTools while the widget is rendered. Console messages from the widget iframe help identify runtime errors, blocked requests, CSP violations, missing props, and failed tool calls. Keep console output intentional. Log the minimum state needed to debug the widget, then remove noisy logs before release.

​
Test the widget in chat

After the tool works directly, open the Chat tab and ask the model to use the tool. Use chat to verify end-to-end behavior:
  • the model chooses the right tool
  • the tool receives valid arguments
  • the model-visible text output is useful
  • the widget renders with the same structured data
  • widget actions such as tool calls, state updates, follow-up messages, and display-mode requests behave as expected
Use the Tools tab again when you need to isolate whether a failure is in the tool, widget, or model behavior.

​
Troubleshoot missing widgets

If no widget appears, start with the smallest failing case.

​
Next steps

  • Use Build widgets to review the server and widget structure.
  • Use Interactivity to add tool calls, state, follow-up messages, and display controls.
  • Use useWidget() for the full hook reference.