Address halter73 review comments on MCP Apps extension

Author: Mike Kistler

docs/concepts/apps/apps.md

@@ -126,9 +126,55 @@ UI resources are HTML pages registered with the MCP server using the `ui://` URI
 - **Domain** — Dedicated origin for OAuth flows and CORS
 - **PrefersBorder** — Whether the host should render a visual border
 
+## App-only tools
+
+Tools with `Visibility = [McpUiToolVisibility.App]` are not visible to the LLM — they are intended only for use by the app UI.
+This is useful for tools that serve UI interaction (button handlers, form submissions) without cluttering the model's tool list:
+
+```csharp
+[McpServerTool, Description("Submit the weather form")]
+[McpAppUi(ResourceUri = "ui://weather/view.html", Visibility = [McpUiToolVisibility.App])]
+public static string SubmitWeatherForm(string city) => GetWeatherHtml(city);
+```
+
+## Graceful degradation
+
+Not all clients support MCP Apps. Use `GetUiCapability` to detect support and return text-only content as a fallback:
+
+```csharp
+[McpServerTool, Description("Get weather")]
+[McpAppUi(ResourceUri = "ui://weather/view.html")]
+public static string GetWeather(McpServer server, string location)
+{
+    var uiCapability = McpApps.GetUiCapability(server.ClientCapabilities);
+    if (uiCapability is null)
+    {
+        // Client doesn't support MCP Apps — return plain text
+        return $"Current weather for {location}: 72°F, sunny";
+    }
+
+    // Client supports MCP Apps — the UI resource will be displayed
+    return $"Weather data for {location} loaded into UI";
+}
+```
+
+## Display modes
+
+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.
+
+## Host theming
+
+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.
+
+See the [MCP Apps specification](https://modelcontextprotocol.io/specification/draft/extensions/apps) for the full list of CSS variables.
+
+## Single-file HTML bundling
+
+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/niccolodipi/vite-plugin-singlefile). For simple apps, inline `<script>` and `<style>` tags work directly.
+
 ## Constants
 
-The <xref:ModelContextProtocol.Server.McpApps> class provides constants for protocol values:
+The <xref:ModelContextProtocol.Extensions.Apps.McpApps> class provides constants for protocol values:
 
 | Constant | Value | Usage |
 | - | - | - |

samples/WeatherAppServer/Program.cs

@@ -1,5 +1,6 @@
 using Microsoft.Extensions.DependencyInjection;
 using ModelContextProtocol.AspNetCore;
+using ModelContextProtocol.Extensions.Apps;
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
 using System.Net.Http.Headers;

samples/WeatherAppServer/WeatherResources.cs

@@ -1,3 +1,4 @@
+using ModelContextProtocol.Extensions.Apps;
 using ModelContextProtocol.Server;
 using System.ComponentModel;
 using System.Text.Json;
@@ -9,6 +10,7 @@ public sealed class WeatherResources
     private static readonly string UiDir = Path.Combine(AppContext.BaseDirectory, "ui");
 
     [McpServerResource(UriTemplate = "ui://weather-app/forecast", Name = "weather-forecast-ui", MimeType = McpApps.ResourceMimeType)]
+    [McpMeta("ui", """{"csp":{"connectDomains":["https://api.weather.gov"]},"prefersBorder":true}""")]
     [Description("Interactive weather forecast UI with city picker")]
     public static string GetWeatherForecastUi() => File.ReadAllText(Path.Combine(UiDir, "weather-forecast.html"));
 

samples/WeatherAppServer/WeatherTools.cs

@@ -1,4 +1,5 @@
 using ModelContextProtocol;
+using ModelContextProtocol.Extensions.Apps;
 using ModelContextProtocol.Protocol;
 using ModelContextProtocol.Server;
 using System.ComponentModel;

src/ModelContextProtocol.Extensions.Apps/ModelContextProtocol.Extensions.Apps.csproj

@@ -7,8 +7,8 @@
     <PackageId>ModelContextProtocol.Extensions.Apps</PackageId>
     <Description>MCP Apps extension for the .NET Model Context Protocol (MCP) SDK</Description>
     <PackageReadmeFile>README.md</PackageReadmeFile>
-    <!-- Suppress the experimental MCP Apps warning -->
-    <NoWarn>$(NoWarn);MCPEXP003</NoWarn>
+    <!-- Suppress the experimental MCP warnings for internal usage -->
+    <NoWarn>$(NoWarn);MCPEXP001;MCPEXP003</NoWarn>
     <!-- New package with no published baseline yet -->
     <EnablePackageValidation>false</EnablePackageValidation>
   </PropertyGroup>

src/ModelContextProtocol.Extensions.Apps/Server/McpAppUiAttribute.cs

@@ -1,6 +1,8 @@
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
 using System.Diagnostics.CodeAnalysis;
 
-namespace ModelContextProtocol.Server;
+namespace ModelContextProtocol.Extensions.Apps;
 
 /// <summary>
 /// Specifies MCP Apps UI metadata for a tool method.
@@ -11,10 +13,11 @@ namespace ModelContextProtocol.Server;
 /// UI resource with the tool. When processed by <see cref="McpApps.ApplyAppUiAttributes(McpServerTool)"/>
 /// or <see cref="McpApps.ApplyAppUiAttributes(IEnumerable{McpServerTool})"/>, it populates the
 /// structured <c>_meta.ui</c> object in the tool's metadata.
+/// </para>
 /// <para>
 /// Explicit <c>Meta["ui"]</c> set via <see cref="McpServerToolCreateOptions"/> or a raw
 /// <c>[McpMeta("ui", ...)]</c> attribute takes precedence over this attribute: if the tool
-/// already has a <c>ui</c> key in <see cref="Protocol.Tool.Meta"/>, this attribute is ignored.
+/// already has a <c>ui</c> key in <see cref="Tool.Meta"/>, this attribute is ignored.
 /// </para>
 /// </remarks>
 /// <example>

src/ModelContextProtocol.Extensions.Apps/Server/McpApps.cs

@@ -1,9 +1,10 @@
 using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json;
 using System.Text.Json.Nodes;
 
-namespace ModelContextProtocol.Server;
+namespace ModelContextProtocol.Extensions.Apps;
 
 /// <summary>
 /// Provides constants and helper methods for building MCP Apps-enabled servers.
@@ -85,10 +86,29 @@ private static JsonSerializerOptions CreateSerializerOptions()
             return null;
         }
 
+        // Handle the case where the value was set programmatically (e.g. in tests
+        // or a non-JSON code path) rather than deserialized from the handshake.
+        if (value is McpUiClientCapabilities uiCapabilities)
+        {
+            return uiCapabilities;
+        }
+
         if (value is JsonElement element)
         {
-            return element.ValueKind == JsonValueKind.Null ? null :
-                JsonSerializer.Deserialize(element, McpAppsJsonContext.Default.McpUiClientCapabilities);
+            // Guard against malformed extension values (e.g. a bare string or number)
+            // that would throw JsonException during deserialization. Return null
+            // consistently for any non-object value, matching the other failure modes.
+            if (element.ValueKind is JsonValueKind.Null or JsonValueKind.Undefined)
+            {
+                return null;
+            }
+
+            if (element.ValueKind != JsonValueKind.Object)
+            {
+                return null;
+            }
+
+            return JsonSerializer.Deserialize(element, McpAppsJsonContext.Default.McpUiClientCapabilities);
         }
 
         return null;
@@ -132,6 +152,44 @@ public static McpServerTool SetAppUi(McpServerTool tool, McpUiToolMeta appUi)
         return tool;
     }
 
+    /// <summary>
+    /// Sets the MCP Apps UI metadata on a resource's <see cref="ResourceTemplate.Meta"/> property.
+    /// </summary>
+    /// <param name="resource">The resource to set the UI metadata on.</param>
+    /// <param name="resourceUi">The UI metadata to apply.</param>
+    /// <returns>The same <paramref name="resource"/> instance, for chaining.</returns>
+    /// <remarks>
+    /// <para>
+    /// This method sets the <c>ui</c> key in the resource's <see cref="ResourceTemplate.Meta"/> object.
+    /// If a <c>ui</c> key is already present in <see cref="ResourceTemplate.Meta"/>, it is not overwritten.
+    /// </para>
+    /// </remarks>
+    /// <exception cref="ArgumentNullException"><paramref name="resource"/> or <paramref name="resourceUi"/> is <see langword="null"/>.</exception>
+    public static McpServerResource SetResourceUi(McpServerResource resource, McpUiResourceMeta resourceUi)
+    {
+#if NET
+        ArgumentNullException.ThrowIfNull(resource);
+        ArgumentNullException.ThrowIfNull(resourceUi);
+#else
+        if (resource is null) throw new ArgumentNullException(nameof(resource));
+        if (resourceUi is null) throw new ArgumentNullException(nameof(resourceUi));
+#endif
+
+        var protocolResource = resource.ProtocolResourceTemplate;
+        protocolResource.Meta ??= new JsonObject();
+
+        if (!protocolResource.Meta.ContainsKey("ui"))
+        {
+            var uiNode = JsonSerializer.SerializeToNode(resourceUi, McpAppsJsonContext.Default.McpUiResourceMeta);
+            if (uiNode is not null)
+            {
+                protocolResource.Meta["ui"] = uiNode;
+            }
+        }
+
+        return resource;
+    }
+
     /// <summary>
     /// Processes a collection of tools, applying <see cref="McpAppUiAttribute"/> metadata to any
     /// tool whose underlying method has the attribute.

src/ModelContextProtocol.Extensions.Apps/Server/McpAppsBuilderExtensions.cs

@@ -1,8 +1,10 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Options;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
 using System.Diagnostics.CodeAnalysis;
 
-namespace ModelContextProtocol.Server;
+namespace ModelContextProtocol.Extensions.Apps;
 
 /// <summary>
 /// Extension methods for <see cref="IMcpServerBuilder"/> to enable MCP Apps support.
@@ -49,6 +51,14 @@ private sealed class McpAppsPostConfigureOptions : IPostConfigureOptions<McpServ
     {
         public void PostConfigure(string? name, McpServerOptions options)
         {
+            // Advertise server-side MCP Apps support in capabilities.
+            options.Capabilities ??= new ServerCapabilities();
+            options.Capabilities.Extensions ??= new Dictionary<string, object>();
+            if (!options.Capabilities.Extensions.ContainsKey(McpApps.ExtensionId))
+            {
+                options.Capabilities.Extensions[McpApps.ExtensionId] = new { };
+            }
+
             if (options.ToolCollection is { IsEmpty: false } tools)
             {
                 foreach (var tool in tools)

src/ModelContextProtocol.Extensions.Apps/Server/McpAppsJsonContext.cs

@@ -1,7 +1,7 @@
 using System.Text.Json;
 using System.Text.Json.Serialization;
 
-namespace ModelContextProtocol.Server;
+namespace ModelContextProtocol.Extensions.Apps;
 
 /// <summary>
 /// Provides source-generated JSON serialization metadata for MCP Apps extension types.

src/ModelContextProtocol.Extensions.Apps/Server/McpUiClientCapabilities.cs

@@ -1,7 +1,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
 
-namespace ModelContextProtocol.Server;
+namespace ModelContextProtocol.Extensions.Apps;
 
 /// <summary>
 /// Represents the MCP Apps capabilities advertised by a client.