> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug widgets in the Inspector

> Test MCP Apps widgets, ChatGPT compatibility, layout, CSP, and widget data in the Inspector.

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](/typescript/mcp-apps/widgets). For hook fields and host actions, use the [`useWidget()` API reference](/typescript/api-reference/react/usewidget).

## Connect the widget server

Run your mcp-use app locally:

```bash theme={null}
npm run dev
```

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:

| Protocol         | What it tests                                                          |
| ---------------- | ---------------------------------------------------------------------- |
| **MCP Apps**     | The standard MCP Apps bridge over `postMessage`.                       |
| **ChatGPT Apps** | ChatGPT compatibility behavior, including Apps SDK-style host globals. |

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](/typescript/mcp-apps/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.

| Data       | What to verify                                                      |
| ---------- | ------------------------------------------------------------------- |
| `props`    | The structured data the widget renders.                             |
| `output`   | The raw structured tool output, when exposed separately.            |
| `metadata` | Widget-only metadata such as timestamps, cache info, or host hints. |
| `state`    | Persisted widget state after user interactions.                     |
| tool input | Arguments passed to the tool that produced the widget.              |

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](/typescript/mcp-apps/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.

| Symptom                                     | Check                                                                        |
| ------------------------------------------- | ---------------------------------------------------------------------------- |
| Tool result appears, but no widget appears. | Confirm `widget.name` matches a folder under `resources/`.                   |
| Widget frame appears blank.                 | Check iframe console errors and missing required props.                      |
| Widget loads in permissive CSP only.        | Add the required domains to widget CSP.                                      |
| ChatGPT protocol fails, but MCP Apps works. | Check [Apps SDK compatibility](/typescript/mcp-apps/apps-sdk-compatibility). |
| A widget action fails.                      | Verify the tool name, arguments, auth state, and iframe console logs.        |

## Next steps

* Use [Build widgets](/typescript/mcp-apps/widgets) to review the server and widget structure.
* Use [Interactivity](/typescript/mcp-apps/interactivity) to add tool calls, state, follow-up messages, and display controls.
* Use [`useWidget()`](/typescript/api-reference/react/usewidget) for the full hook reference.