nota-america/forgecat-agent-profiles / profiles/anthropics/claude-plugins-official/anthropics_claude-plugins-official_mcp-server-dev/for-claude/.claude/skills/build-mcp-app
build-mcp-app
VerifiedThis 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.1 KB |
| references/apps-sdk-messages.md | markdown | 6.0 KB |
| references/iframe-sandbox.md | markdown | 4.4 KB |
| references/widget-templates.md | markdown | 8.7 KB |
references/iframe-sandbox.md
View on GitHub# Iframe sandbox constraints
MCP-app widgets run inside a sandboxed `<iframe>` in the host (Claude Desktop,
claude.ai). The sandbox and CSP attributes lock down what the widget can do.
Every item below was observed failing with a silent blank iframe until the
fix was applied — the error only appears in the iframe's own devtools console,
not the host's.
---
## Problem → fix table
| Symptom | Root cause | Fix |
|---|---|---|
| Widget renders as blank rectangle, no error | CSP `script-src` blocks esm.sh fetching transitive `@modelcontextprotocol/sdk` deps | Inline the `ext-apps/app-with-deps` bundle into the HTML |
| `window.open()` does nothing | Sandbox lacks `allow-popups` | Use `app.openLink({ url })` |
| `<a target="_blank">` does nothing | Same | `e.preventDefault()` + `app.openLink({ url })` on click |
| External `<img src>` broken | CSP `img-src` + referrer hotlink blocking | Fetch server-side, ship as `data:` URL in the tool result payload |
| Widget edits don't appear after server restart | Host caches UI resources | Fully quit the host (⌘Q / Alt+F4) and relaunch |
| Top-level `await` throws | Older iframe contexts | Wrap module body in an async IIFE |
---
## Inlining the ext-apps bundle
`@modelcontextprotocol/ext-apps` ships a self-contained browser build at the
`app-with-deps` export (~300KB). It's minified ESM ending in `export{…}`; to
use it from an inline `<script type="module">` block, rewrite the export
statement into a global assignment at build time:
```ts
import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
const require = createRequire(import.meta.url);
const bundle = readFileSync(
require.resolve("@modelcontextprotocol/ext-apps/app-with-deps"),
"utf8",
).replace(/export\{([^}]+)\};?\s*$/, (_, body) =>
"globalThis.ExtApps={" +
body.split(",").map((pair) => {
const [local, exported] = pair.split(" as ").map((s) => s.trim());
return `${exported ?? local}:${local}`;
}).join(",") + "};",
);
const widgetHtml = readFileSync("./widgets/widget.html", "utf8")
.replace("/*__EXT_APPS_BUNDLE__*/", () => bundle);
```
Widget side:
```html
<script type="module">
/*__EXT_APPS_BUNDLE__*/
const { App } = globalThis.ExtApps;
(async () => {
const app = new App({ name: "…", version: "…" }, {});
// …
})();
</script>
```
The `() => bundle` replacer form (rather than a bare string) is important —
`String.replace` interprets `$…` sequences in a string replacement, and the
minified bundle is full of them.
---
## Outbound links
```js
// ✗ blocked
window.open(url, "_blank");
// ✗ blocked
<a href="…" target="_blank">…</a>
// ✓ host-mediated
await app.openLink({ url });
```
Intercept anchor clicks:
```js
el.addEventListener("click", (e) => {
e.preventDefault();
app.openLink({ url: el.href });
});
```
---
## External images
CSP `img-src` defaults (plus many CDN referrer policies) block
`<img src="https://external-cdn/…">` from loading. Inline them server-side in
the tool handler:
```ts
async function toDataUrl(url: string): Promise<string | undefined> {
try {
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
if (!res.ok) return undefined;
const buf = Buffer.from(await res.arrayBuffer());
const mime = res.headers.get("content-type") ?? "image/jpeg";
return `data:${mime};base64,${buf.toString("base64")}`;
} catch {
return undefined;
}
}
// in the tool handler
const inlined = await Promise.all(
items.map(async (it) =>
it.thumb ? { ...it, thumb: await toDataUrl(it.thumb) ?? it.thumb } : it,
),
);
```
Add `referrerpolicy="no-referrer"` on the `<img>` as a fallback for any URL
that survives un-inlined.
---
## Dark mode
```js
const applyTheme = (theme) =>
document.documentElement.classList.toggle("dark", theme === "dark");
app.onhostcontextchanged = (ctx) => applyTheme(ctx.theme);
await app.connect();
applyTheme(app.getHostContext()?.theme);
```
```css
:root { --ink:#0f1111; --bg:#fff; color-scheme:light; }
:root.dark { --ink:#e6e6e6; --bg:#1f2428; color-scheme:dark; }
:root.dark .thumb { mix-blend-mode: normal; } /* multiply → images vanish in dark */
```
---
## Debugging
The iframe has its own console. In Claude Desktop, open DevTools (View → Toggle
Developer Tools), then switch the context dropdown (top-left of the Console
tab) from "top" to the widget's iframe. CSP violations, uncaught exceptions,
and import errors all surface there — the host's main console stays silent.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |