repository·main·Indexed 25 days ago
https://github.com/modelcontextprotocol/ext-appsAn extension to the Model Context Protocol that enables MCP servers to deliver interactive user interfaces, such as charts, forms, and dashboards, that render inline within compliant chat clients. The SDK provides an App class and React hooks for communication between the UI and the host, including methods like callServerTool, sendMessage, sendLog, and openLink. The repository includes reference implementations for hosts and servers using Preact, React, Solid, and Svelte.
MCP Apps is an extension to the Model Context Protocol (MCP) that allows servers to deliver interactive user interfaces (UIs) to hosts. It provides a standardized pattern for declaring UI resources using the ui:// URI scheme and associating them with tools via metadata. This enables rich, visual, and interactive experiences that go beyond plain text or structured data, while maintaining MCP's core principles of security and auditability.
Key features include:
ui:// URI scheme.text/html;profile=mcp-app.The Basic Vue MCP App demonstrates how to link an MCP server tool to a rich Vue 3 user interface.
server.ts) registers a tool (e.g., get-time) and includes metadata that links the tool to a specific UI HTML resource (e.g., ui://get-time/mcp-app.html).src/App.vue) uses the MCP App SDK's App class to communicate back to the host and call server tools.The App class provides the following methods for the UI to interact with the environment:
callServerTool: Invokes a tool on the MCP server.sendMessage: Sends a message to the host.sendLog: Sends a log message.openLink: Opens a URL.This example uses Vite with vite-plugin-singlefile to bundle the entire Vue application into a single HTML file. This ensures the entire UI can be served as a single MCP resource. For apps requiring external resources, you must define _meta.ui.csp.resourceDomains in the UI resource metadata.
MCP Apps (extension ID: io.modelcontextprotocol/ui) allows MCP servers to deliver interactive user interfaces to hosts. It enables servers to provide HTML-based UIs that communicate with the host via standard MCP JSON-RPC.
Key components include:
ui:// URI scheme.Note: MCP Apps is an optional extension and must be negotiated between client and server via capability negotiation.
MCP Apps enforces security through two primary mechanisms:
postMessage.MCP Apps communicate with hosts using the standard MCP JSON-RPC base protocol over postMessage. This decision ensures compatibility with existing MCP infrastructure, including:
Developers can use the standard @modelcontextprotocol/sdk to implement these communications, avoiding the need for a custom message format.
MCP Apps extend the Model Context Protocol by allowing tools to declare interactive UI resources. The lifecycle follows these steps:
ui:// resource containing its HTML interface.ui:// resource and renders it within a sandboxed iframe.To ensure visual cohesion across different host environments, MCP Apps use a standardized set of CSS custom properties (variables). UI views should apply styles using var(--name) with appropriate fallbacks.
Theming Guidelines:
MCP Views can be displayed in three modes: inline (default), fullscreen, or pip (picture-in-picture).
For View Developers:
ui/initialize request using appCapabilities.availableDisplayModes.HostContext.availableDisplayModes to ensure the host supports it.For Host Developers:
ui/request-display-mode, return the actual resulting mode in the response.ui/notifications/host-context-changed to inform the view when the displayMode changes.// Example: View declares support for inline and fullscreen during initialization
{
method: "ui/initialize",
params: {
appCapabilities: {
availableDisplayModes: ["inline", "fullscreen"]
}
}
}An MCP App is a combination of two linked components that allow an LLM to trigger an interactive UI:
The Linkage: The tool's metadata must include a reference to the resource's URI using the _meta.ui.resourceUri key.
Lifecycle Flow: Host calls tool $\rightarrow$ Host renders resource UI $\rightarrow$ Server returns result $\rightarrow$ UI receives result.
The Host provides environment and styling information in the hostContext field of the McpUiInitializeResult. Views should use this to adapt their appearance and behavior.
Key context fields:
theme: Current preference ("light" or "dark").styles: Contains variables (CSS custom properties) and css (e.g., @font-face rules) for the View to inject.displayMode: How the View is currently rendered ("inline", "fullscreen", or "pip").containerDimensions: Sizing constraints for the iframe.locale & timeZone: User preferences for localization.platform: The host platform ("web", "desktop", or "mobile").// Host responds with McpUiInitializeResult
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2026-01-26",
"hostCapabilities": { /* ... */ },
"hostInfo": { "name": "claude-desktop", "version": "1.0.0" },
"hostContext": {
"theme": "dark",
"styles": {
"variables": {
"--color-background-primary": "light-dark(#ffffff, #171717)",
"--color-text-primary": "light-dark(#171717, #fafafa)",
"--font-sans": "Anthropic Sans, sans-serif"
},
"css": {
"fonts": "@font-face { font-family: \"Custom Font Name\"; src: url(\"https://...\"); }"
}
},
"displayMode": "inline",
"containerDimensions": { "width": 400, "maxHeight": 600 }
}
}
}MCP Apps uses a three-entity architecture to deliver interactive UIs securely:
ui:// URI scheme.postMessage to call tools or interact with the chat.This model allows for Progressive Enhancement: if a Host does not support MCP Apps, tools still function as standard text/structured data tools. The UI is an optional enhancement.