Mcp Apps

What is Mcp Apps about?

Mcp Apps provides a standardized way for MCP tools to deliver interactive user interfaces that render directly inside conversational AI platforms such as Claude, ChatGPT, VS Code, Postman, and others. By declaring a ui:// resource in a tool definition, the host fetches the HTML/JS bundle and displays it in a sandboxed iframe, enabling bidirectional communication between the UI and the LLM.

How to use Mcp Apps?

1. Install the SDK (for both client‑side view development and server‑side registration):

   npm install -S @modelcontextprotocol/ext-apps \
     @modelcontextprotocol/client@2.0.0-beta.5 \
     @modelcontextprotocol/server@2.0.0-beta.5 \
     @modelcontextprotocol/core@2.0.0-beta.5 \
     zod@^4.2.0
   

2. Create a new app – either manually or via the provided Agent Skills:

   # Using Claude or any Agent Skills‑compatible AI
   /plugin marketplace add modelcontextprotocol/ext-apps
   /plugin install mcp-apps@modelcontextprotocol-ext-apps
   # Then ask the agent: "Create an MCP App"
   

3. Define the UI – add a ui:// resource containing your HTML/JS (React, Vue, Svelte, etc.) and export an App class from @modelcontextprotocol/ext-apps.
4. Register the tool on your MCP server – use helpers from @modelcontextprotocol/ext-apps/server to attach the UI metadata to the tool definition.
5. Configure the client – add the server to the client’s mcpServers map (Node.js examples use the @modelcontextprotocol/server-<name> packages via npx). Example snippet:

   {
     "mcpServers": {
       "map": {
         "command": "npx",
         "args": ["-y", "@modelcontextprotocol/server-map", "--stdio"]
       }
     }
   }
   

6. Run – start the client (Claude Desktop, VS Code, etc.) and the UI will appear inline when the tool is invoked.

Key Features

• Agent Skills – four ready‑to‑use skills (create-mcp-app, migrate-oai-app, add-app-to-server, convert-web-app) that automate scaffolding, migration, and integration.
• Multi‑framework support – starter templates for React, Vue, Svelte, Preact, Solid, and vanilla JS.
• Bidirectional postMessage transport – seamless communication between the UI iframe and the host, enabling tool calls from the UI and data push from the host.
• Extensible SDK – core package, React hooks, and an app‑bridge for embedding views in custom hosts.
• Comprehensive examples – map viewer, 3D scene, shader toy, PDF viewer, real‑time monitoring, etc., all bundled in the examples/ directory.
• Open spec – versioned specification (2026‑01‑26 stable) hosted alongside the code.

Use Cases

• Data visualization – render interactive charts, heatmaps, or 3‑D globes directly inside a chat conversation.
• Form entry & dashboards – collect user input, configure parameters, and display KPI dashboards without leaving the chat UI.
• Media playback – embed video, audio, or real‑time transcription streams.
• Tool augmentation – convert existing OpenAI Apps or web apps into MCP‑compatible interactive experiences.
• Rapid prototyping – let AI agents generate full‑stack MCP Apps with a single prompt.

FAQ

Q: Do I need a specific host to display MCP Apps? A: Any chat client that implements the MCP Apps extension (Claude, ChatGPT, VS Code, Postman, Goose, etc.) can render the UI. See the "Supported Clients" badge list for details.

Q: Which programming languages are supported for the server? A: The primary SDK is JavaScript/TypeScript (Node.js). Python examples are provided (e.g., qr-server, say-server) that run via uv run.

Q: How do I migrate an existing OpenAI App? A: Use the migrate-oai-app Agent Skill, which converts the OpenAI SDK definitions to the MCP Apps format automatically.

Q: Can I use a custom framework not listed in the starter templates? A: Yes. The core SDK works with any framework that can produce a static HTML/JS bundle and communicate through postMessage.

Q: Where can I find the full specification? A: The stable spec is at specification/2026-01-26/apps.mdx in the repository, with a draft version also available.

Table of Contents

• Build with Agent Skills
• Supported Clients
• Why MCP Apps?
• How It Works
• Getting Started
• Using the SDK
• Examples
• Specification
• Resources
• Contributing

Build with Agent Skills

The fastest way to build an MCP App is to let your AI coding agent do it. This repo ships four Agent Skills — install them once, then just ask:

Skill	What it does	Try it
create-mcp-app	Scaffolds a new MCP App with an interactive UI from scratch	"Create an MCP App"
migrate-oai-app	Converts an existing OpenAI App to use MCP Apps	"Migrate from OpenAI Apps SDK"
add-app-to-server	Adds interactive UI to an existing MCP server's tools	"Add UI to my MCP server"
convert-web-app	Turns an existing web app into a hybrid web + MCP App	"Add MCP App support to my web app"

Install the Skills

Claude Code — install via the plugin marketplace:

/plugin marketplace add modelcontextprotocol/ext-apps
/plugin install mcp-apps@modelcontextprotocol-ext-apps

Other agents — any AI coding agent that supports Agent Skills can use these skills. See the agent skills guide for manual installation instructions.

Once installed, verify by asking your agent "What skills do you have?" — you should see create-mcp-app, migrate-oai-app, add-app-to-server, and convert-web-app in the list. Then just ask it to create or migrate an app and it will guide you through the rest.

Supported Clients

[!NOTE] MCP Apps is an extension to the core MCP specification. Host support varies — see the clients page for the full list.

Why MCP Apps?

MCP tools return text and structured data. That works for many cases, but not when you need an interactive UI, like a chart, form, design canvas or video player.

MCP Apps provide a standardized way to deliver interactive UIs from MCP servers. Your UI renders inline in the conversation, in context, in any compliant host.

How It Works

MCP Apps extend the Model Context Protocol by letting tools declare UI resources:

1. Tool definition — Your tool declares a ui:// resource containing its HTML interface
2. Tool call — The LLM calls the tool on your server
3. Host renders — The host fetches the resource and displays it in a sandboxed iframe
4. Bidirectional communication — The host passes tool data to the UI via notifications, and the UI can call other tools through the host

Getting Started

For a View or host:

npm install -S @modelcontextprotocol/ext-apps \
  @modelcontextprotocol/client@2.0.0-beta.5 \
  @modelcontextprotocol/core@2.0.0-beta.5 \
  zod@^4.2.0

For an MCP server:

npm install -S @modelcontextprotocol/ext-apps \
  @modelcontextprotocol/server@2.0.0-beta.5 \
  @modelcontextprotocol/core@2.0.0-beta.5 \
  zod@^4.2.0

Applications that implement both roles should install both client and server. Keep all installed base MCP SDK packages on the exact same published beta so they share one compatible protocol implementation.

New here? Start with the Quickstart Guide to build your first MCP App.

Using the SDK

The SDK serves three roles: app developers building interactive Views, host developers embedding those Views, and MCP server authors registering tools with UI metadata.

Package	Purpose	Docs
@modelcontextprotocol/ext-apps	Build interactive Views (App class, PostMessageTransport)	API Docs →
@modelcontextprotocol/ext-apps/react	React hooks for Views (useApp, useHostStyles, etc.)	API Docs →
@modelcontextprotocol/ext-apps/app-bridge	Embed and communicate with Views in your chat client	API Docs →
@modelcontextprotocol/ext-apps/server	Register tools and resources on your MCP server	API Docs →

There's no supported host implementation in this repo (beyond the examples/basic-host example).

The MCP-UI client SDK offers a fully-featured MCP Apps framework used by a few hosts. Clients may choose to use it or roll their own implementation.

Examples

The examples/ directory contains demo apps showcasing real-world use cases.

Map	Three.js	ShaderToy
Sheet Music	Wiki Explorer	Cohort Heatmap
Scenario Modeler	Budget Allocator	Customer Segmentation
System Monitor	Transcript	Video Resource
PDF Server	QR Code (Python)	Say Demo

Starter Templates

	The same app built with different frameworks — pick your favorite!React · Vue · Svelte · Preact · Solid · Vanilla JS

Running the Examples

With basic-host

To run all examples locally using basic-host (the reference host implementation included in this repo):

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps
npm install
npm start

Then open http://localhost:8080/.

With MCP Clients

Every Node.js example is published as @modelcontextprotocol/server-<name>. To add one to an MCP client that supports stdio (Claude Desktop, VS Code, etc.), use this pattern:

{
  "mcpServers": {
    "<name>": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-<name>", "--stdio"]
    }
  }
}

For example, to add the map server: @modelcontextprotocol/server-map. The Python examples (qr-server, say-server) use uv run instead — see their READMEs for details.

Local Development

To test local modifications with an MCP client, clone the repo, install, then point your client at a local build:

{
  "mcpServers": {
    "<name>": {
      "command": "bash",
      "args": [
        "-c",
        "cd ~/code/ext-apps/examples/<name>-server && npm run build >&2 && node dist/index.js --stdio"
      ]
    }
  }
}

Specification

Version	Status	Link
2026-01-26	Stable	specification/2026-01-26/apps.mdx
draft	Development	specification/draft/apps.mdx

Resources

• Quickstart Guide
• API Documentation
• Specification (2026-01-26) (Draft)
• SEP-1865 Discussion

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to get started, submit pull requests, and report issues.