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.
Fetches build-mcp-app from anthropics/claude-plugins-official and configures it for Cursor.
3
Select Cursor when prompted
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ────────────────
│ · Cline · Codex · Goose · Windsurf
│ ●Cursor(selected)
│ · Cursor · Aider · Continue
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/build-mcp-app
Restart Cursor to activate build-mcp-app. Access via /build-mcp-app in your agent's command palette.
⚠
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
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.
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.
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.
import{ McpServer }from"@modelcontextprotocol/sdk/server/mcp.js";import{ registerAppTool, registerAppResource,RESOURCE_MIME_TYPE}from"@modelcontextprotocol/ext-apps/server";import{ z }from"zod";const server =newMcpServer({ name:"contacts", version:"1.0.0"});// 1. The tool — returns DATA, declares which UI to showregisterAppTool(server,"pick_contact",{ description:"Open an interactive contact picker", inputSchema:{ filter: z.string().optional()}, _meta:{ ui:{ resourceUri:"ui://widgets/contact-picker.html"}},},async({ filter })=>{const contacts =await db.contacts.search(filter);// Plain JSON — the widget receives this via ontoolresultreturn{ content:[{ type:"text", text:JSON.stringify(contacts)}]};});// 2. The resource — serves the HTMLregisterAppResource( server,"Contact Picker","ui://widgets/contact-picker.html",{},async()=>({ contents:[{ uri:"ui://widgets/contact-picker.html", mimeType:RESOURCE_MIME_TYPE, text: pickerHtml,// your HTML string}],}),);
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.
<scripttype="module">/* ext-apps bundle inlined at build time → globalThis.ExtApps *//*__EXT_APPS_BUNDLE__*/const{App}= globalThis.ExtApps;const app =newApp({name:"ContactPicker",version:"1.0.0"},{});// Set handlers BEFORE connecting app.ontoolresult=({ content })=>{const contacts =JSON.parse(content[0].text);render(contacts);};await app.connect();// Later, when the user clicks something:functiononPick(contact){ app.sendMessage({role:"user",content:[{type:"text",text:`Selected contact: ${contact.id}`}],});}</script>
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 notimport { 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 (light/dark), locale, etc.
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.
›Claude Desktop or compatible AI client with skill support
›Clear understanding of task or problem to solve
›Willingness to iterate and refine outputs
Time Estimate
15-45 minutes depending on use case complexity
Steps
1Install skill using provided installation command
2Test with simple use case relevant to your work
3Evaluate output quality and relevance
4Iterate on prompts to improve results
5Integrate into regular workflow if valuable
Common Pitfalls
⚠Expecting perfect results without iteration
⚠Not providing enough context in prompts
⚠Using skill for tasks outside its intended scope
⚠Accepting outputs without review and validation
Best Practices
✓ Do
+Start with clear, specific prompts
+Provide relevant context and constraints
+Review and refine all outputs before using
+Iterate to improve output quality
+Document successful prompt patterns
✗ Don't
−Don't use without understanding skill limitations
−Don't skip validation of outputs
−Don't share sensitive information in prompts
−Don't expect skill to replace human judgment
💡 Pro Tips
★Be specific about desired format and style
★Ask for multiple options to choose from
★Request explanations to understand reasoning
★Combine AI efficiency with human expertise
When to Use This
✓ Use when
Use when skill capabilities match your task, clear ROI on time saved, and you can validate outputs. Best for repetitive tasks, learning, and quality improvement.
✗ Avoid when
Avoid when task requires deep expertise you can't validate, involves sensitive decisions, or when learning process is more valuable than speed of completion.
Learning Path
1Familiarize yourself with skill capabilities and limitations
2Start with low-risk, non-critical tasks
3Progress to more complex and valuable use cases
4Build expertise through regular use and experimentation
