mirror of
https://github.com/mcp-use/mcp-use.git
synced 2026-09-14 18:06:01 +08:00
Enrico
125 lines
5.5 KiB
Plaintext
125 lines
5.5 KiB
Plaintext
---
|
|
title: "Debug widgets in the Inspector"
|
|
description: "Test MCP Apps widgets, ChatGPT compatibility, layout, CSP, and widget data in the Inspector."
|
|
icon: "bug"
|
|
---
|
|
|
|
{/* TODO: Add Inspector media when a screenshot or short clip would clarify the workflow. */}
|
|
|
|
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
|
|
npm run dev
|
|
```
|
|
|
|
Open `http://localhost:3000/mcp/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.
|