MCP Apps are based on the MCP ext-apps specification — an open standard for rendering interactive UI widgets inside AI conversations.
Unlike the proprietary Apps SDK, MCP Apps work across multiple clients (e.g. Claude, Goose, VSCode). Skybridge implements the protocol via the McpAppAdaptor so you use the same hooks regardless of runtime.
Here’s what happens when an MCP Apps client renders a widget:
- User asks the AI to perform an action (e.g., “Show me flight options to Paris”)
- The client calls your MCP tool (e.g.,
search_flights)
- Your tool returns a result with data and a reference to a UI resource
- The client fetches the resource (your compiled React component) and renders it in an iframe
- The widget communicates with the host via the MCP protocol and is hydrated with your tool’s
structuredContent and _meta properties
The widget–host connection looks like this:
The Host UI in this diagram designates the MCP Client (Claude, Goose, VSCode, etc.), and the Guest App is your App running in an iframe.
The MCP ext-apps protocol
Widgets run inside an iframe and talk to the host via the same MCP protocol used by your server. The ext-apps spec defines guest-to-host requests and host-to-guest notifications for the widget:
Guest-to-host requests
| Method | Description |
|---|
ui/initialize | Handshake to establish connection |
ui/open-link | Open external URLs |
ui/message | Send follow-up messages to the conversation |
ui/request-display-mode | Request display mode change |
ui/update-model-context | Update widget state for the model |
tools/call | Invoke MCP tools |
Host-to-guest notifications
| Notification | Description |
|---|
ui/notifications/host-context-changed | Theme, locale, display mode, viewport, or other host context updated |
ui/notifications/tool-input | Tool arguments provided |
ui/notifications/tool-result | Tool execution completed |
ui/notifications/tool-cancelled | Tool call was cancelled |
ui/notifications/tool-input-partial | Streaming partial tool arguments (e.g. while the model is still sending) |
Skybridge Hook Mapping
Skybridge wraps the MCP ext-apps protocol with the same React hooks as the Apps SDK. The McpAppAdaptor translates hook usage into the protocol under the hood:
| Protocol | Skybridge Hook | Purpose |
|---|
ui/notifications/tool-input, tool-result, metadata | useToolInfo() | Access tool input, output, and _meta |
ui/update-model-context | useWidgetState(), data-llm | Persistent widget state / model context |
tools/call | useCallTool() | Make additional tool calls |
ui/message | useSendFollowUpMessage() | Send follow-up messages |
ui/open-link | useOpenExternal() | Open external URLs |
ui/request-display-mode | useDisplayMode() | Access/change display mode |
ui/notifications/host-context-changed (theme, maxHeight, safeArea) | useLayout() | Theme, max height, safe area insets |
ui/notifications/host-context-changed (locale, userAgent) | useUser() | Locale and device/capabilities |
| Modal (polyfilled) | useRequestModal() | Request modal display (renders in-iframe) |
MCP Apps methods not yet supported in Skybridge
The following MCP ext-apps protocol methods are not yet wrapped by Skybridge hooks:
| Protocol Method | Purpose |
|---|
ui/notifications/tool-input-partial | Streaming partial tool arguments (e.g. while the model is still sending) |
ui/notifications/tool-cancelled | Tool call was cancelled |
tool-input-partial and tool-cancelled directly via useMcpAppContext when running in MCP Apps clients, if needed. Support may be added in a future release.
MCP Apps limitations
Not all Skybridge features exist in the ext-apps spec. When using Skybridge in MCP Apps clients, the following features are either not supported or polyfilled:
| Feature | Apps SDK | MCP Apps |
|---|
| useFiles, useSetOpenInAppUrl | ✅ | ❌ Not supported |
| useRequestModal | Portaled to host | ⚠️ Polyfilled (renders in-iframe) |
| useWidgetState, data-llm | Persisted by host | ⚠️ Polyfilled (state doesn’t persist across widget renders) |
Testing MCP Apps
Please see the Test Your App guide for more information.
DevTools uses the Apps SDK runtime. Use DevTools for fast iteration, then validate in an MCP Apps client (e.g. Goose) for final testing.
.svg?fit=max&auto=format&n=Mov2w4kOhZcG1Kz1&q=85&s=598d3bed1ba52ebcb88755026b1e7d78)