MCP Apps

Project Overview#

MCP Apps is an extension protocol for Model Context Protocol (MCP), defining a standard protocol that allows AI models to return interactive HTML UIs through MCP servers, not just text or Markdown. It includes formal protocol specifications, TypeScript SDK, and a rich example library.

Core Value: Solves the limited interaction capabilities of traditional AI chat interfaces. Users can directly manipulate charts, fill forms, drag design canvases, or play videos within the conversation flow, and feed these interaction data back to the model, achieving a "conversational operation" closed loop.

Extension Identifier: io.modelcontextprotocol/ui

Core Features#

UI Resource Mechanism#

• Resource Identification: Uses ui:// URI scheme to declare UI resources on MCP Server
• Dedicated MIME Type: text/html;profile=mcp-app to distinguish regular web pages from MCP apps
• Tool-UI Binding: Associates specific UI resources via _meta.ui.resourceUri field
• Visibility Control: visibility: ["model", "app"] or ["app"] (front-end only, avoiding model context pollution)

Communication & Lifecycle#

• Communication Mechanism: MCP JSON-RPC 2.0 messaging via window.postMessage
• Lifecycle Messages:
  • ui/initialize / ui/notifications/initialized
  • ui/notifications/tool-input / tool-result / tool-cancelled
  • ui/notifications/size-changed
  • ui/resource-teardown

Display & Styling#

• Display Modes: inline (embedded in conversation), fullscreen, pip (picture-in-picture)
• Theme Injection: CSS variables via HostContext.styles.variables (background, text, border, font, shadow, radius, etc.)
• Light/Dark theme auto-adaptation and custom font injection
• HostContext传递: theme / styles / containerDimensions / locale / timeZone / safeAreaInsets

Security & Sandbox#

• Strong Sandbox Isolation: Forced execution in <iframe> with allow-scripts and allow-same-origin
• CSP Configuration: Declarable connectDomains / resourceDomains / frameDomains / baseUriDomains whitelists
• Default Strict CSP, Host must not allow undeclared domains
• Web Host Proxy Mode: Dual Iframe (Sandbox Proxy) architecture ensuring origin isolation between Host and App

SDK Modules#

• @modelcontextprotocol/ext-apps: Core SDK with App class and PostMessageTransport
• @modelcontextprotocol/ext-apps/react: React hooks (useApp, useHostStyles, etc.)
• @modelcontextprotocol/ext-apps/app-bridge: Bridge library for embedding and communicating Views in chat clients
• @modelcontextprotocol/ext-apps/server: Server-side library for registering tools and resources

Quick Start#

Install SDK#

npm install -S @modelcontextprotocol/ext-apps

Run Examples Locally#

git clone https://github.com/modelcontextprotocol/ext-apps.git
cd ext-apps
npm install
npm start
# Visit http://localhost:8080/ to see all examples

Integrate with MCP Client (e.g., Claude Desktop)#

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

Agent Skills (Build Tools)#

• create-mcp-app: Quickly create new applications
• migrate-oai-app: Migrate OpenAI applications
• add-app-to-server: Add applications to existing MCP Server
• convert-web-app: Convert regular web applications to MCP Apps

Example Ecosystem#

Visualization: Map (Leaflet), Three.js, ShaderToy, Cohort Heatmap Tools/Editors: Sheet Music, Wiki Explorer, Scenario Modeler, Budget Allocator, Customer Segmentation Media: Video Resource, PDF Server, System Monitor, Transcript, QR Code (Python) Multi-framework Examples: React, Vue, Svelte, Preact, Solid, Vanilla JS

Architecture Components#

• Host: AI conversation client (e.g., Claude Desktop, VS Code plugin, or Web page)
• MCP Server: Provides tool logic and UI resources (HTML/JS/CSS)
• UI View (App): Frontend application running in Iframe sandbox, acting as MCP Client