MCP Apps: Build Interactive UIs for AI Agent Tools

Direct answer

MCP Apps is the official Model Context Protocol extension for returning interactive user interfaces from MCP tools. Instead of forcing an agent to describe a chart, form, dashboard, document viewer, or multi-step workflow as text, an MCP server can declare a ui:// resource and let a compatible host render it inline in a sandboxed iframe. The practical result is a shared interaction pattern across clients such as Claude, ChatGPT, Goose, Visual Studio Code, and Microsoft 365 Copilot.

For developers, the important boundary is this: MCP Apps adds a presentation and interaction layer to MCP; it does not replace MCP tools, authentication, user consent, or server-side authorization. Start with a normal tool, add a UI resource only where direct manipulation materially improves the workflow, and keep every privileged operation behind an ordinary MCP tool call.

What MCP Apps solves

Text is excellent for explanations and compact results. It is awkward for tasks where people need to explore or make several related choices. A user reviewing sales data may want to filter a chart, inspect a record, and export a result. A deployment workflow may need a form with dependent fields. A document-review tool may need inline highlights and approve/reject controls.

The official MCP announcement describes MCP Apps as the first official MCP extension and gives these examples: dashboards, forms, visualizations, document review, real-time monitoring, and multi-step workflows. The extension keeps the conversation as the context while giving the user a real interface for the parts that text handles poorly.

A useful mental model is:

Visual 1 — Original request flow for an MCP App. The iframe is the presentation boundary; the MCP server remains the authority for tools, data, and authorization.

How the extension works

An MCP App combines two primitives:

1. A tool descriptor containing _meta.ui.resourceUri, normally pointing to a ui:// resource.
2. A UI resource containing HTML, JavaScript, CSS, and the app metadata needed by the host.

When the model calls the tool, a compatible host fetches the resource, renders it in a sandboxed iframe, and passes tool data into the view. The app and host communicate through JSON-RPC messages carried over postMessage. The view can request another server tool, send a message, update model context, open an external link through the host, or react to new tool results, subject to host policy and user consent.

A minimal tool descriptor looks like this:

1{
2  "name": "visualize_data",
3  "description": "Visualize sales data as an interactive chart",
4  "inputSchema": {
5    "type": "object",
6    "properties": {
7      "region": { "type": "string" }
8    }
9  },
10  "_meta": {
11    "ui": {
12      "resourceUri": "ui://charts/sales-dashboard"
13    }
14  }
15}

The official extension repository provides the @modelcontextprotocol/ext-apps SDK, server helpers, React bindings, an App Bridge for hosts, and working examples. It also includes starter patterns for React, Vue, Svelte, Preact, Solid, and vanilla JavaScript. The framework is optional: the wire protocol is based on standard web primitives and JSON-RPC.

MCP Apps versus a normal web app

Visual 2 — Comparison table synthesized from the official MCP Apps documentation and Microsoft’s Copilot implementation guidance. MCP Apps is complementary to, not a replacement for, a complete web application.

Build a first app without overengineering

Install the official SDK in a JavaScript or TypeScript project:

1npm install @modelcontextprotocol/ext-apps

For a new project, begin with one read-only tool and one view. The official repository’s examples are useful starting points, including maps, Three.js scenes, PDF viewing, system monitoring, and data exploration. The repository also exposes four Agent Skills for scaffolding a new app, adding UI to an existing MCP server, migrating an OpenAI App, or converting a web app into a hybrid MCP App.

Inside the view, the SDK’s App class handles the host connection and common calls:

1import { App } from "@modelcontextprotocol/ext-apps";
2
3const app = new App();
4await app.connect();
5
6app.ontoolresult = (result) => {
7  renderChart(result);
8};
9
10async function refreshDetails(id: string) {
11  return app.callServerTool({
12    name: "fetch_details",
13    arguments: { id },
14  });
15}
16
17async function reportSelection(label: string) {
18  await app.updateModelContext({
19    content: [{ type: "text", text: `User selected ${label}` }],
20  });
21}

Treat this as an interaction example, not a complete server. The server still needs to register the ui:// resource, return the tool metadata, validate all arguments, and enforce authorization independently of anything shown in the browser view.

Security model and production checklist

MCP Apps run code supplied by an MCP server, so the UI boundary deserves the same attention as a plugin or third-party integration. The official documentation says that hosts should use sandboxed iframes. The sandbox prevents the app from reading the parent page’s DOM, cookies, or local storage and keeps communication on the postMessage channel.

Microsoft’s MCP Apps guidance adds a practical production warning: Copilot supports OAuth 2.1 and Microsoft Entra SSO for remote MCP servers, while anonymous authentication is appropriate only for development. It also recommends checking host capability availability and showing a fallback when an API is not present.

Use this checklist before shipping:

• Validate every tool argument on the server; never trust UI state.
• Keep destructive tools behind explicit consent and clear tool annotations.
• Use OAuth 2.1 or the host’s supported enterprise identity flow for production.
• Define a restrictive content-security policy for external connections and resources.
• Avoid placing secrets, access tokens, or sensitive records in HTML or client-side state.
• Check optional host APIs before calling them and provide a text fallback.
• Log tool calls and authorization decisions on the server.
• Test the same app in each target host because extension support is not identical.
• Keep the UI useful when JavaScript fails or the host does not support MCP Apps.

The sandbox is not permission to treat an untrusted server as safe. Users and operators should still vet the server, its dependencies, its network access, and the tools it exposes.

Host support and interoperability

Support is expanding, but it is not uniform. The MCP documentation lists Claude, Claude Desktop, Visual Studio Code GitHub Copilot, Microsoft 365 Copilot, Goose, Postman, MCPJam, and Archestra.AI among the clients with MCP Apps support. The official launch post separately describes support from Claude, Goose, Visual Studio Code, and ChatGPT at launch time.

Visual Studio Code’s developer guide is especially useful for implementers: it documents MCP Apps alongside tools, prompts, resources, elicitation, OAuth, and other MCP capabilities, and explains that users can manage tool confirmation from the tools picker. Microsoft’s guidance documents which MCP Apps and OpenAI Apps SDK bridge capabilities are supported in Microsoft 365 Copilot and which are not.

Official demo reference: the MCP Apps repository includes a visual gallery and runnable examples such as a Three.js scene, interactive map, PDF viewer, system monitor, cohort heatmap, and budget allocator. Use those examples as the visual and interoperability reference rather than inventing a mock screenshot.

Visual 3 — Official interactive demo and example gallery. The repository is the source and credit for the examples linked above.

For broader agent-integration context, see the site’s guides to portable Agent Plugins and MCP skills, MCP tool-server threat modeling, and harness engineering for coding agents. These cover packaging, security review, and reliable execution around the UI layer.

Common implementation mistakes

Treating the iframe as a trusted backend

The view is a client. It may be modified, interrupted, run in a reduced-capability host, or never rendered at all. Authorization and business rules belong in the server tool implementation.

Assuming OpenAI Apps SDK APIs map one-to-one

MCP Apps and the OpenAI Apps SDK share patterns, but hosts expose different capability surfaces. Microsoft’s compatibility table shows that some OpenAI bridge APIs have no direct MCP Apps equivalent or are unsupported in Copilot. Detect capabilities instead of assuming them.

Building a dashboard when text is better

A UI adds bundle size, testing, accessibility work, and host-compatibility risk. Use an app when the user benefits from sorting, filtering, editing, visual comparison, or repeated actions. For a one-line answer, return text.

Making the UI the only path

A tool should still produce a useful structured or textual result. That improves accessibility, debugging, non-supporting clients, and automated evaluation. The UI should enhance the tool, not make the server unusable outside one host.

Forgetting accessibility and keyboard flows

Inline agent UIs are still interfaces. Provide labels, focus states, keyboard navigation, readable contrast, responsive layouts, and status announcements. Test with the host’s theme and constrained viewport, not only in a desktop browser.

FAQ

Is MCP Apps a new model API?

No. It is an MCP extension for interactive presentation and interaction. The model still chooses MCP tools, and the server still owns data access and authorization.

Can MCP Apps call tools?

Yes. A view can request server tools through the host bridge when the host supports that capability. The server must validate the request like any other tool call.

Do I need React?

No. The official SDK includes framework examples, but MCP Apps can be implemented with vanilla JavaScript or another web framework using the documented bridge protocol.

Are MCP Apps safe by default?

They have a security model based on sandboxed iframes, host-controlled messaging, content policies, and user consent. That reduces risk but does not make an untrusted MCP server harmless. Review the server and keep sensitive enforcement on the backend.

Should every MCP tool have a UI?

No. Add a UI when visual exploration, configuration, approval, or multi-step interaction is materially easier than a text response. Keep simple lookups and explanations text-first.

Conclusion

MCP Apps gives MCP developers a missing layer: a portable way to put useful interfaces inside an agent conversation without abandoning MCP’s tool and resource model. The best first implementation is deliberately small—a read-only chart, inspector, or form backed by one validated tool and a reliable text fallback.

The engineering challenge is not drawing a widget. It is preserving the trust boundary while making the interaction portable: validate on the server, restrict the iframe, request only the host capabilities you need, test across clients, and keep authorization independent of the UI. With that discipline, MCP Apps can turn an agent from a text-only dispatcher into a more usable workspace for exploration and action.

Sources and visual credits

• MCP Apps announcement — Model Context Protocol Blog — primary launch and architecture source.
• MCP Apps documentation — current interaction, security, framework, and client-support documentation.
• Official MCP Apps SDK and examples — SDK, specification, Agent Skills, demos, and visual examples.
• MCP developer guide — Visual Studio Code — host support and tool behavior.
• MCP apps in Microsoft 365 Copilot — production authentication, capability, and compatibility guidance.

Visual credits: Visual 1 is an original Mermaid diagram by the author. Visual 2 is an original comparison table based on the cited official documentation. Visual 3 links to and credits the official modelcontextprotocol/ext-apps repository and its examples; no unofficial screenshots are used.