skills.rest
SocialGouv
SocialGouvOFFICIAL
Explore all skills by this author →
WebsiteGitHub

build-mcp-app

Build MCP servers that serve interactive UI widgets rendered inline in chat hosts.

16|1|Updated Mar 20, 2026
Search Tags:#Claude#MCP#server development#interactive UI#widgets#ext-apps#iframe sandbox
One-click install
npx skills add https://github.com/SocialGouv/iterion --skill build-mcp-app-socialgouv
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: build-mcp-app
Source: https://github.com/SocialGouv/iterion/tree/main/vendor/github.com/SocialGouv/claw-code-go/internal/tools/bundled_skills/mcp-server-dev/skills/build-mcp-app
Command: npx skills add https://github.com/SocialGouv/iterion --skill build-mcp-app-socialgouv

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @modelcontextprotocol/sdk, @modelcontextprotocol/ext-apps, zod, express, and includes references (resource) components.

What problem does it solve? Plain MCP tools return only text or JSON, which falls short when a user must pick from a large list, confirm a destructive action, or view spatial data like charts and diffs. This Skill guides you through adding interactive UI widgets to an MCP server so tools can render pickers, forms, dashboards, and confirmation dialogs directly inside Claude, ChatGPT, or any host implementing the apps surface. ## Core Features & Use Cases - Widget-enabled tool registration: Attach a ui:// HTML resource to any tool via _meta.ui.resourceUri using registerAppTool and registerAppResource from @modelcontextprotocol/ext-apps, with automatic graceful degradation on hosts without the apps surface. - Bidirectional widget runtime: Use the App class inside the sandboxed iframe to receive tool results, send messages into the conversation, call server tools, open links, and adapt to host theme and display mode. - Production guidance: Reference docs cover iframe CSP/sandbox constraints, payload size budgeting, authless abuse protection with rate limiting, widget HTML templates, and the connector-directory submission checklist. - Use Case: You are building a contacts MCP server and want users to pick a contact from a searchable list instead of typing an ID. This Skill walks you through registering a picker tool, serving the widget HTML with the inlined ext-apps bundle, and piping the selection back into the conversation. ## Quick Start Ask the AI to use the build-mcp-app skill to add an interactive contact picker widget to your MCP server.

Frequently Asked Questions about build-mcp-app

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add an interactive UI widget to an MCP server tool?▼

Register the tool with registerAppTool and declare a UI resource via _meta.ui.resourceUri, then register that resource separately with registerAppResource serving HTML under the text/html;profile=mcp-app MIME type. The host fetches the resource and renders it in a sandboxed iframe when the tool is called.

When should I use an MCP widget instead of elicitation?▼

Use elicitation for simple yes/no confirmations, short enum picks, or flat forms since it is spec-native with zero UI code. Use a widget for large searchable lists, visual previews, charts or maps, and live-updating progress that elicitation cannot render.

Why does my MCP app widget render as a blank rectangle?▼

Blank widgets are almost always CSP violations, most commonly importing ext-apps from a CDN whose transitive dependency fetches get blocked. Inline the ext-apps/app-with-deps bundle into the widget HTML at server startup and check the iframe's own devtools console for errors.

Can MCP app widgets open external links or load remote images?▼

No, the iframe sandbox blocks window.open, target=_blank anchors, and remote img-src loads. Use app.openLink for navigation and fetch images server-side, embedding them as data: URLs in the tool result payload.

What is the tool result size limit for MCP app widgets?▼

Claude.ai and Claude Desktop truncate tool results at roughly 150,000 characters, substituting a file-pointer string that breaks JSON.parse in the widget. Cap payloads near 130KB by pruning unreferenced columns, truncating rows, and serving heavy assets via a separate callServerTool helper.

Do MCP app widgets work on hosts without the apps surface?▼

Yes, widgets degrade automatically. Hosts that do not support the apps surface ignore the _meta.ui declaration and render the tool's plain text or JSON content normally, so the tool handler should always return meaningful data.

Related Skills

Explore More Software Engineering Skills→
saadmsftsaadmsft

claude-mcp-server-dev-build-mcp-app

Automate building interactive UI widgets for MCP servers.

Community
Advanced
ever-justever-just
3

mcp-server-discoverability

Publishes MCP servers to registries and configures OAuth discovery for agent access.

Community
Intermediate
lucasfthlucasfth

build-mcpb

Package a local MCP server with its runtime into a single .mcpb bundle.

Community
Intermediate
Unique-AGUnique-AG
5

unique-cli-elicitation

Route clarifications and confirmations through a structured elicitation UI.

Official
Advanced