thevibeworks/claude-code-docs/build-mcp-app
Claude Code and agent skill by thevibeworks/claude-code-docs
- community
Checking that the SKILL.md file is still in the repository.
This skill should be used when the user wants to build an "MCP app", add "interactive UI" or "widgets" to an MCP server, "render components in chat", build "MCP UI resources", make a tool that shows a "form", "picker", "dashboard" or "confirmation dialog" inline in the conversation, or mentions "apps SDK" in the context of MCP. Use AFTER the build-mcp-server skill has settled the deployment model, or when the user already knows they want UI widgets.
Install
npx vskill@latest install thevibeworks/claude-code-docs/build-mcp-appSKILL.md
The same SKILL.md was published earlier as thevibeworks/claude-code-docs/build-mcp-app.
Build an MCP App (Interactive UI Widgets)
An MCP app is a standard MCP server that also serves UI resources — interactive components rendered inline in the chat surface. Build once, runs in Claude and ChatGPT and any other host that implements the apps surface.
The UI layer is additive. Under the hood it's still tools, resources, and the same wire protocol. If you haven't built a plain MCP server before, the build-mcp-server skill covers the base layer. This skill adds widgets on top.
Testing in Claude: Add the server as a custom connector in claude.ai (via a Cloudflare tunnel for local dev) — this exercises the real iframe sandbox andhostContext. See https://claude.com/docs/connectors/building/testing.
Claude host specifics
_meta.ui.* key | Where | Effect | |
|---|---|---|---|
resourceUri | tool | Which ui:// resource the host renders for this tool's results. | |
visibility: ["app"] | tool | Hide a widget-only helper tool (e.g. geometry/image fetcher called via callServerTool) from Claude's tool list. | |
prefersBorder: false | resource | Drop the host's outer card border (mobile). | |
csp.{connectDomains, resourceDomains, baseUriDomains} | resource | Declare external origins; default is block-all. frameDomains is currently restricted in Claude. |
hostContext.safeAreaInsets: {top, right, bottom, left}(px) — honor these for notches and the composer overlay.- Directory submission requires OAuth or authless (
none) — static bearer is private-deploy only and blocks listing — plus toolannotationsand 3–5 PNG screenshots; seereferences/directory-checklist.md.
When a widget beats plain text
Don't add UI for its own sake — most tools are fine returning text or JSON. Add a widget when one of these is true:
| Signal | Widget type | |
|---|---|---|
| Tool needs structured input Claude can't reliably infer | Form | |
| User must pick from a list Claude can't rank (files, contacts, records) | Picker / table | |
| Destructive or billable action needs explicit confirmation | Confirm dialog | |
| Output is spatial or visual (charts, maps, diffs, previews) | Display widget | |
| Long-running job the user wants to watch | Progress / live status |
If none apply, skip the widget. Text is faster to build and faster for the user.
Widgets vs Elicitation — route correctly
Before building a widget, check if elicitation covers it. Elicitation is spec-native, zero UI code, works in any compliant host.
| Need | Elicitation | Widget | |
|---|---|---|---|
| Confirm yes/no | ✅ | overkill | |
| Pick from short enum | ✅ | overkill | |
| Fill a flat form (name, email, date) | ✅ | overkill | |
| Pick from a large/searchable list | ❌ (no scroll/search) | ✅ | |
| Visual preview before choosing | ❌ | ✅ | |
| Chart / map / diff view | ❌ | ✅ | |
| Live-updating progress | ❌ | ✅ |
If elicitation covers it, use it. See ../build-mcp-server/references/elicitation.md.
Architecture: two deployment shapes
Remote MCP app (most common)
Hosted streamable-HTTP server. Widget templates are served as resources; tool results reference them. The host fetches the resource, renders it in an iframe sandbox, and brokers messages between the widget and Claude.
MCPB-packaged MCP app (local + UI)
Same widget mechanism, but the server runs locally inside an MCPB bundle. Use this when the widget needs to drive a local application — e.g., a file picker that browses the actual local disk, a dialog that controls a desktop app.
For MCPB packaging mechanics, defer to the `build-mcpb` skill. Everything below applies to both shapes.
How widgets attach to tools
A widget-enabled tool has two separate registrations:
- The tool declares a UI resource via
_meta.ui.resourceUri. Its handler returns plain text/JSON — NOT the HTML. - The resource is registered separately and serves the HTML.
When Claude calls the tool, the host sees _meta.ui.resourceUri, fetches that resource, renders it in an iframe, and pipes the tool's return value into the iframe via the ontoolresult event.
The URI scheme ui:// is convention. The mime type MUST be RESOURCE_MIME_TYPE ("text/html;profile=mcp-app") — this is how the host knows to render it as an interactive iframe, not just display the source.
Widget runtime — the App class
Inside the iframe, your script talks to the host via the App class from @modelcontextprotocol/ext-apps. This is a persistent bidirectional connection — the widget stays alive as long as the conversation is active, receiving new tool results and sending user actions.
The /*__EXT_APPS_BUNDLE__*/ placeholder gets replaced by the server at startup with the contents of @modelcontextprotocol/ext-apps/app-with-deps — see references/iframe-sandbox.md for why this is necessary and the rewrite snippet. Do not import { App } from "https://esm.sh/..."; the iframe's CSP blocks the transitive dependency fetches and the widget renders blank.
| Method | Direction | Use for | |
|---|---|---|---|
app.ontoolresult = fn | Host → widget | Receive the tool's return value | |
app.ontoolinput = fn | Host → widget | Receive the tool's input args (what Claude passed) | |
app.sendMessage({...}) | Widget → host | Inject a message into the conversation | |
app.updateModelContext({...}) | Widget → host | Update context silently (no visible message) | |
app.callServerTool({name, arguments}) | Widget → server | Call another tool on your server | |
app.openLink({url}) | Widget → host | Open a URL in a new tab (sandbox blocks window.open) | |
app.getHostContext() / app.onhostcontextchanged | Host → widget | Theme, host CSS vars, containerDimensions, displayMode, deviceCapabilities | |
app.requestDisplayMode({mode}) | Widget → host | Ask for inline / pip / fullscreen | |
app.downloadFile({name, mimeType, content}) | Widget → host | Host-mediated download (base64 content) | |
new App(info, caps, {autoResize: true}) | — | Iframe height tracks rendered content |
sendMessage is the typical "user picked something, tell Claude" path. updateModelContext is for state that Claude should know about but shouldn't clutter the chat. openLink is required for any outbound navigation — window.open and <a target="_blank"> are blocked by the sandbox attribute.
What widgets cannot do:
- Access the host page's DOM, cookies, or storage
- Make network calls to arbitrary origins (CSP-restricted — route through
callServerTool) - Open popups or navigate directly — use
app.openLink({url}) - Load remote images reliably — inline as
data:URLs server-side
Keep widgets small and single-purpose. A picker picks. A chart displays. Don't build a whole sub-app inside the iframe — split it into multiple tools with focused widgets.
Scaffold: minimal picker widget
Install:
Server (`src/server.ts`):
For local-only widget apps (driving a desktop app, reading local files), swap the transport to StdioServerTransport and package via the build-mcpb skill.
Widget (`widgets/picker.html`):
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingcontent/github/claude-plugins-official/plugins/mcp-server-dev/skills/build-mcp-app/SKILL.md
Popularity
- Repository stars
- 156
- Repository forks
- 24
- 7-day trend score
- 0
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/thevibeworks/claude-code-docs/build-mcp-app)