Verified Agent Skill record

build-MCP-app

This skill guides developers in adding interactive UI widgets — forms, pickers, dashboards, confirmation dialogs, and display components — to an MCP server using the @modelcontextprotocol/ext-apps SDK. It covers the two-registration pattern (tool plus resource), the iframe-sandboxed widget runtime via the App class, and design rules for deciding when a widget beats plain text or spec-native elicitation. It is intended for use after the build-mcp-server skill has settled the deployment model.

Tasks

Register a widget-enabled tool using registerAppTool with _meta.ui.resourceUri pointing to a ui:// resource, ensuring the handler returns plain text/JSON data rather than HTML
Register a corresponding app resource using registerAppResource with mimeType set to RESOURCE_MIME_TYPE ('text/html;profile=mcp-app') to serve the widget HTML template
Check whether standard MCP elicitation covers the use case (yes/no confirm, short enum pick, flat form) before building a custom widget, skipping the widget if elicitation suffices
Inline the @modelcontextprotocol/ext-apps/app-with-deps bundle into the widget HTML by replacing the /*__EXT_APPS_BUNDLE__*/ placeholder, avoiding remote CDN imports that the iframe CSP blocks

Inputs

_meta.ui.resourceUri on a tool (e.g. ui://widgets/contact-picker.html)
Tool input arguments such as a filter string passed by Claude
Tool handler return value as plain text or JSON content (received by the widget via the ontoolresult event)
hostContext.safeAreaInsets pixel values for notches and composer overlay

Outputs

Tool results containing plain text/JSON data plus a widget reference via _meta.ui.resourceUri
Resources serving HTML with mimeType RESOURCE_MIME_TYPE ('text/html;profile=mcp-app')
Widget-initiated messages injected into the conversation via app.sendMessage
Silent context updates sent to the model via app.updateModelContext

Limitations and checks

Widgets cannot access the host page's DOM, cookies, or storage
Widgets cannot make network calls to arbitrary origins (CSP-restricted; must route through callServerTool)
Widgets cannot open popups or navigate directly (window.open and <a target='_blank'> are blocked; must use app.openLink)
frameDomains is currently restricted in the Claude host
Widgets cannot reliably load remote images (must be inlined as data: URLs server-side)
Elicitation lacks scroll and search for large or searchable lists
Verify every widget-enabled tool handler returns meaningful plain text/JSON data so that hosts without apps-surface support degrade gracefully
Confirm the resource mimeType is exactly RESOURCE_MIME_TYPE and that the ext-apps bundle is inlined at the /*__EXT_APPS_BUNDLE__*/ placeholder rather than imported from a CDN