Skip to content
Get packs

Guide · Agent skill

How to use the Build MCP App Widgets agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The build-mcp-app skill is an instruction set for an AI agent that helps you build an MCP app: a normal MCP server that also serves small interactive components such as forms, pickers, dashboards and confirmation dialogs, shown inside the chat. This guide explains what the skill changes, how to install it, how to trigger it with plain requests, and what to check before you rely on it. You do not need prior experience with agent skills, but you should already be building or planning an MCP server.

Build MCP App Widgetsanthropics/claude-plugins-official · Apache-2.0

Quick start

  1. 1Download and unzip the skill. Download the build-mcp-app ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
  2. 2Or upload it in the Claude apps. Go to Settings → Capabilities → Skills and upload the ZIP.
  3. 3Settle the deployment model. If you have not built a plain MCP server before, start with the build-mcp-server skill, since this skill adds widgets on top.
  4. 4Describe the widget you need. Make a request that matches the skill, such as a form, picker, dashboard or confirmation dialog shown inline in the chat.
  5. 5Check whether a widget is needed. Compare the need against elicitation and plain text. Only build a widget when the interaction needs more than those options provide.
  6. 6Build and test through a connector. Add the server as a custom connector in claude.ai, using a Cloudflare tunnel for local development, and test the widget in the real iframe sandbox.

What is an agent skill, and what does this one do?

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches the skill's description. This one is aimed at the work of adding interactive UI to an MCP server.

The skill guides the agent through the parts of an MCP app: a tool that returns data and declares which UI resource to show, a separate resource that serves the widget HTML, and a widget script that talks to the host using the App class from @modelcontextprotocol/ext-apps. It also helps the agent decide whether a widget is worth building at all.

  • Decides when a widget beats plain text, and when built-in elicitation is the better choice.
  • Shows how tools and UI resources connect through the _meta.ui.resourceUri key.
  • Explains how widget code sends messages back to the conversation and receives tool results.
  • Covers host-specific settings, abuse protection for authless servers, and the directory submission checklist.

Install the build-mcp-app skill

Download the skill ZIP from this page and unzip it. You can install it in one of two places, depending on who should have access to it.

For a personal install across your projects, unzip it into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Single project: .claude/skills/ inside the project folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to trigger the skill with a natural request

You do not need to type a command. The skill is meant to load when your request matches its description. Phrases that match include asking to build an "MCP app", to add "interactive UI" or "widgets" to an MCP server, to "render components in chat", or to make a tool that shows a "form", "picker", "dashboard" or "confirmation dialog" inline. Mentioning "apps SDK" in an MCP context also matches.

The skill's own guidance is to run the build-mcp-server skill first if the deployment model is not settled yet. Ask for that step first if you are unsure.

  • "Add an interactive contact picker widget to my MCP server."
  • "I want a confirmation dialog shown in chat before the delete_record tool runs."
  • "Build an MCP app that shows a dashboard of today's orders."
  • "Make a form-style widget for collecting shipping details from the user."

What you need before you start

The skill assumes an MCP server project that uses the TypeScript SDK (@modelcontextprotocol/sdk), the @modelcontextprotocol/ext-apps package, and zod for input schemas. For local testing, the skill recommends adding the server as a custom connector in claude.ai, using a Cloudflare tunnel to reach your local machine.

The skill itself runs no scripts and makes no network calls. Those requirements belong to the project you build.

  • An existing MCP server project (TypeScript SDK)
  • The @modelcontextprotocol/ext-apps package
  • zod for input schemas
  • A Claude.ai custom connector, or a Cloudflare tunnel for local testing

Example: a widget-enabled tool

The skill's core pattern uses two separate registrations. The tool returns plain JSON and points to a UI resource with _meta.ui.resourceUri. The resource is registered on its own and serves the HTML with the MIME type RESOURCE_MIME_TYPE, which tells the host to render it as an interactive iframe.

The example below comes from the skill's reference material. It is a contact picker, which is the kind of list a widget handles better than text.

registerAppTool(server, "pick_contact", { description: "Open an interactive contact picker", annotations: { title: "Pick Contact", readOnlyHint: true }, inputSchema: { filter: z.string().optional() }, _meta: { ui: { resourceUri: "ui://widgets/contact-picker.html" } } }, async ({ filter }) => { const contacts = await db.contacts.search(filter); return { content: [{ type: "text", text: JSON.stringify(contacts) }] }; });

Safety notes: scripts, network and local access

The skill runs no scripts and uses no network access itself. Its effects come from the server you build with it, so the risks are in that server's design.

An authless hosted server can be reached by anyone on the internet. The skill's abuse-protection reference notes that claude.ai traffic comes through a small set of shared Anthropic IP ranges, so per-user limits need OAuth. Widgets that control local applications or disks are a separate case: the skill says to understand MCPB packaging and its security implications first.

  • Authless servers have no per-user identity; claude.ai users share egress IPs.
  • Directory submission requires OAuth or authless (none); static bearer tokens are for private deployments only.
  • Widgets that drive local disk or desktop apps need MCPB packaging and security review.

Tips for getting good results

Ask the agent whether a widget is needed before building one. The skill tells it to skip UI for simple text or JSON output. Set autoResize for widgets whose height depends on data, otherwise tall content gets clipped. Keep the inline height at 500px or less, and follow the directory checklist before submitting.

  • Compare each need against elicitation first: flat yes/no, short enums and simple forms are usually better served by elicitation.
  • Use autoResize: true for data-dependent heights.
  • Load the directory-checklist reference before submitting to the connector directory.
  • Use widgets for large or searchable lists, visual previews, charts, diffs and live progress.

What people use it for

  • Building a contact or record picker where the user searches and selects from a long list.
  • Adding a confirmation dialog before a destructive or billable tool action runs.
  • Creating a dashboard or chart view that renders inline in the conversation.
  • Preparing an MCP app for submission to the Claude connector directory.

Frequently asked questions

Is the build-mcp-app skill free?

The source material for this skill is published under the Apache-2.0 licence, as listed on this page. Check the licence file in the repository for the full terms before reuse.

Do I need to know MCP before using this skill?

Yes. The skill is for developers who already build or plan an MCP server. It says to start with the build-mcp-server skill if you have not built a plain MCP server before.

How do I install an agent skill in Claude?

Unzip the skill into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

What is the difference between a widget and elicitation?

Elicitation is a built-in, spec-native way to ask for simple confirmations, short choices or flat forms with no UI code. Widgets are better for searchable lists, visual previews, charts, diffs and live progress.

Does the skill run code or make network requests?

No. The skill itself runs no scripts and uses no network. The server you build with it is what handles requests, so review its design, especially for authless or local-access setups.

Can I submit an MCP app to the Claude connector directory?

The skill's checklist says directory submission requires OAuth or authless (none) authentication, tool annotations, and 3–5 PNG screenshots. Static bearer tokens block listing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you already build an MCP server and want richer in-chat interfaces, or if you need to decide whether a tool should get a widget at all. Skip it if you have never built an MCP server, or if your tools return simple text or JSON, since a widget would only add complexity.

Download the skill