|
| 1 | +--- |
| 2 | +title: MCP Apps |
| 3 | +author: mikekistler |
| 4 | +description: How to use the MCP Apps extension to deliver interactive UIs from MCP servers. |
| 5 | +uid: apps |
| 6 | +--- |
| 7 | + |
| 8 | +# MCP Apps |
| 9 | + |
| 10 | +[MCP Apps] is an extension to the Model Context Protocol that enables MCP servers to deliver interactive user interfaces — dashboards, forms, visualizations, and more — directly inside conversational AI clients. |
| 11 | + |
| 12 | +[MCP Apps]: https://modelcontextprotocol.io/extensions/apps/overview |
| 13 | + |
| 14 | +> [!IMPORTANT] |
| 15 | +> MCP Apps support is experimental. All types are marked with `[Experimental("MCPEXP003")]` and require suppressing that diagnostic to use. |
| 16 | +
|
| 17 | +## Installation |
| 18 | + |
| 19 | +MCP Apps is provided in the `ModelContextProtocol.Extensions.Apps` package, which layers on top of the core SDK: |
| 20 | + |
| 21 | +```shell |
| 22 | +dotnet add package ModelContextProtocol.Extensions.Apps |
| 23 | +``` |
| 24 | + |
| 25 | +## Overview |
| 26 | + |
| 27 | +The MCP Apps extension introduces the concept of **UI resources** — HTML pages served by the MCP server that a client can display alongside the conversation. Tools can be associated with a UI resource so the client knows which interface to show when a tool is called. |
| 28 | + |
| 29 | +The key concepts are: |
| 30 | + |
| 31 | +- **UI capability negotiation** — Client and server declare support via `extensions["io.modelcontextprotocol/ui"]` |
| 32 | +- **UI resources** — HTML content served with the MIME type `text/html;profile=mcp-app` |
| 33 | +- **Tool UI metadata** — Tools declare their associated UI resource in `_meta.ui` |
| 34 | + |
| 35 | +## Associating tools with UI resources |
| 36 | + |
| 37 | +### Using the builder extension (recommended) |
| 38 | + |
| 39 | +The simplest approach is to apply `[McpAppUi]` attributes to your tool methods and call `WithMcpApps()` on the server builder: |
| 40 | + |
| 41 | +```csharp |
| 42 | +[McpServerToolType] |
| 43 | +public class WeatherTools |
| 44 | +{ |
| 45 | + [McpServerTool, Description("Get current weather for a location")] |
| 46 | + [McpAppUi(ResourceUri = "ui://weather/view.html")] |
| 47 | + public static string GetWeather(string location) => $"Weather for {location}"; |
| 48 | + |
| 49 | + [McpServerTool, Description("Get forecast (model-only tool)")] |
| 50 | + [McpAppUi(ResourceUri = "ui://weather/forecast.html", Visibility = [McpUiToolVisibility.Model])] |
| 51 | + public static string GetForecast(string location) => $"Forecast for {location}"; |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +```csharp |
| 56 | +builder.Services.AddMcpServer() |
| 57 | + .WithTools<WeatherTools>() |
| 58 | + .WithMcpApps(); |
| 59 | +``` |
| 60 | + |
| 61 | +The `WithMcpApps()` call registers a post-configuration step that processes all registered tools and applies `[McpAppUi]` attribute metadata to their `_meta.ui` field automatically. |
| 62 | + |
| 63 | +### Using the attribute with manual processing |
| 64 | + |
| 65 | +If you create tools manually (without `WithMcpApps()`), you can still use the attribute and process tools explicitly: |
| 66 | + |
| 67 | +```csharp |
| 68 | +var tools = new[] |
| 69 | +{ |
| 70 | + McpServerTool.Create(typeof(WeatherTools).GetMethod(nameof(WeatherTools.GetWeather))!), |
| 71 | + McpServerTool.Create(typeof(WeatherTools).GetMethod(nameof(WeatherTools.GetForecast))!), |
| 72 | +}; |
| 73 | + |
| 74 | +McpApps.ApplyAppUiAttributes(tools); |
| 75 | +``` |
| 76 | + |
| 77 | +### Using the programmatic API |
| 78 | + |
| 79 | +For full control, use `McpApps.SetAppUi` to set UI metadata directly: |
| 80 | + |
| 81 | +```csharp |
| 82 | +var tool = McpServerTool.Create((string location) => $"Weather for {location}"); |
| 83 | + |
| 84 | +McpApps.SetAppUi(tool, new McpUiToolMeta |
| 85 | +{ |
| 86 | + ResourceUri = "ui://weather/view.html", |
| 87 | + Visibility = [McpUiToolVisibility.Model, McpUiToolVisibility.App], |
| 88 | +}); |
| 89 | +``` |
| 90 | + |
| 91 | +## Checking client capabilities |
| 92 | + |
| 93 | +During a session, you can check whether the connected client supports MCP Apps: |
| 94 | + |
| 95 | +```csharp |
| 96 | +[McpServerTool, Description("Get weather")] |
| 97 | +[McpAppUi(ResourceUri = "ui://weather/view.html")] |
| 98 | +public static string GetWeather(McpServer server, string location) |
| 99 | +{ |
| 100 | + var uiCapability = McpApps.GetUiCapability(server.ClientCapabilities); |
| 101 | + if (uiCapability is not null) |
| 102 | + { |
| 103 | + // Client supports MCP Apps — the UI will be displayed |
| 104 | + } |
| 105 | + |
| 106 | + return $"Weather for {location}"; |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +## Tool visibility |
| 111 | + |
| 112 | +The `Visibility` property controls which principals can invoke the tool: |
| 113 | + |
| 114 | +| Value | Meaning | |
| 115 | +| - | - | |
| 116 | +| `McpUiToolVisibility.Model` | Only the LLM can call this tool | |
| 117 | +| `McpUiToolVisibility.App` | Only the app UI can call this tool | |
| 118 | +| Both (or null/empty) | Both the model and app can call the tool (default) | |
| 119 | + |
| 120 | +## UI resources |
| 121 | + |
| 122 | +UI resources are HTML pages registered with the MCP server using the `ui://` URI scheme and the `text/html;profile=mcp-app` MIME type. The `McpUiResourceMeta` type provides metadata for these resources, including: |
| 123 | + |
| 124 | +- **CSP (Content Security Policy)** — Controls allowed origins for network requests and resource loads |
| 125 | +- **Permissions** — Sandbox permissions (scripts, forms, popups, etc.) |
| 126 | +- **Domain** — Dedicated origin for OAuth flows and CORS |
| 127 | +- **PrefersBorder** — Whether the host should render a visual border |
| 128 | + |
| 129 | +## App-only tools |
| 130 | + |
| 131 | +Tools with `Visibility = [McpUiToolVisibility.App]` are not visible to the LLM — they are intended only for use by the app UI. |
| 132 | +This is useful for tools that serve UI interaction (button handlers, form submissions) without cluttering the model's tool list: |
| 133 | + |
| 134 | +```csharp |
| 135 | +[McpServerTool, Description("Submit the weather form")] |
| 136 | +[McpAppUi(ResourceUri = "ui://weather/view.html", Visibility = [McpUiToolVisibility.App])] |
| 137 | +public static string SubmitWeatherForm(string city) => GetWeatherHtml(city); |
| 138 | +``` |
| 139 | + |
| 140 | +## Graceful degradation |
| 141 | + |
| 142 | +Not all clients support MCP Apps. Use `GetUiCapability` to detect support and return text-only content as a fallback: |
| 143 | + |
| 144 | +```csharp |
| 145 | +[McpServerTool, Description("Get weather")] |
| 146 | +[McpAppUi(ResourceUri = "ui://weather/view.html")] |
| 147 | +public static string GetWeather(McpServer server, string location) |
| 148 | +{ |
| 149 | + var uiCapability = McpApps.GetUiCapability(server.ClientCapabilities); |
| 150 | + if (uiCapability is null) |
| 151 | + { |
| 152 | + // Client doesn't support MCP Apps — return plain text |
| 153 | + return $"Current weather for {location}: 72°F, sunny"; |
| 154 | + } |
| 155 | + |
| 156 | + // Client supports MCP Apps — the UI resource will be displayed |
| 157 | + return $"Weather data for {location} loaded into UI"; |
| 158 | +} |
| 159 | +``` |
| 160 | + |
| 161 | +## Display modes |
| 162 | + |
| 163 | +The MCP Apps spec defines display modes (`inline`, `fullscreen`, `pip`) that control how the host renders the UI. Display mode is negotiated between the client and server during capability exchange and is not set per-tool — it depends on the host implementation. |
| 164 | + |
| 165 | +## Host theming |
| 166 | + |
| 167 | +Hosts pass standardized CSS custom properties (e.g., `--color-background-primary`, `--color-text-primary`) to app iframes. Your HTML can reference these variables to automatically match the host's theme without any server-side configuration. |
| 168 | + |
| 169 | +See the [MCP Apps specification](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx) for the full list of CSS variables. |
| 170 | + |
| 171 | +## Single-file HTML bundling |
| 172 | + |
| 173 | +The default Content Security Policy restricts external script and style loads. For production apps, bundle all JavaScript and CSS into a single HTML file using tools like [vite-plugin-singlefile](https://github.com/richardtallent/vite-plugin-singlefile). For simple apps, inline `<script>` and `<style>` tags work directly. |
| 174 | + |
| 175 | +## Constants |
| 176 | + |
| 177 | +The <xref:ModelContextProtocol.Extensions.Apps.McpApps> class provides constants for protocol values: |
| 178 | + |
| 179 | +| Constant | Value | Usage | |
| 180 | +| - | - | - | |
| 181 | +| `McpApps.HtmlMimeType` | `text/html;profile=mcp-app` | MIME type for UI resources | |
| 182 | +| `McpApps.ExtensionId` | `io.modelcontextprotocol/ui` | Key in `extensions` capability dictionary | |
| 183 | + |
| 184 | +## Serialization |
| 185 | + |
| 186 | +MCP Apps types use source-generated JSON serialization for Native AOT compatibility. Use `McpApps.SerializerOptions` when serializing extension types: |
| 187 | + |
| 188 | +```csharp |
| 189 | +var json = JsonSerializer.Serialize(toolMeta, McpApps.SerializerOptions); |
| 190 | +var deserialized = JsonSerializer.Deserialize<McpUiToolMeta>(json, McpApps.SerializerOptions); |
| 191 | +``` |
0 commit comments