feat(server): add hasUiSupport/getUiCapability for experimental+extensions

Support double-tagging for MCP Apps capability negotiation:
- Check both experimental and extensions fields in client capabilities
- Add hasUiSupport() to easily check if client supports MCP Apps
- Add getUiCapability() to retrieve the capability settings
- Update spec to document both capability locations

This enables forward compatibility as MCP transitions from experimental
to the extensions field (SEP-1724).

Claude-Generated-By: Claude Code (cli/claude-opus-4-5=100%)
Claude-Steers: 0
Claude-Permission-Prompts: 0
Claude-Escapes: 0

Author: ochafik

specification/draft/apps.mdx

@@ -1412,11 +1412,43 @@ Note: Tools with `visibility: ["app"]` are hidden from the agent but remain call
 
 ### Client\<\>Server Capability Negotiation
 
-Clients and servers negotiate MCP Apps support through the standard MCP extensions capability mechanism (defined in SEP-1724).
+Clients and servers negotiate MCP Apps support using the extension identifier `io.modelcontextprotocol/ui`.
+
+#### Capability Location
+
+The MCP Apps capability can be advertised in either of two locations within `ClientCapabilities`:
+
+1. **`experimental`** (currently preferred): The `experimental` field is part of the current MCP schema and allows arbitrary extension data. Use this for maximum compatibility.
+
+2. **`extensions`** (future): Once SEP-1724 is accepted and deployed, `extensions` will be the canonical location. Servers SHOULD check both locations for forward compatibility.
 
 #### Client (Host) Capabilities
 
-Clients advertise MCP Apps support in the initialize request using the extension identifier `io.modelcontextprotocol/ui`:
+Clients advertise MCP Apps support in the initialize request:
+
+**Using `experimental` (recommended for current deployments):**
+
+```json
+{
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {
+      "experimental": {
+        "io.modelcontextprotocol/ui": {
+          "mimeTypes": ["text/html;profile=mcp-app"]
+        }
+      }
+    },
+    "clientInfo": {
+      "name": "claude-desktop",
+      "version": "1.0.0"
+    }
+  }
+}
+```
+
+**Using `extensions` (once SEP-1724 is accepted):**
 
 ```json
 {
@@ -1449,13 +1481,12 @@ Future versions may add additional settings:
 
 #### Server Behavior
 
-Servers SHOULD check client (host would-be) capabilities before registering UI-enabled tools:
+Servers SHOULD check both `experimental` and `extensions` before registering UI-enabled tools. The SDK provides the `hasUiSupport` helper for this:
 
 ```typescript
-const hasUISupport =
-  clientCapabilities?.extensions?.["io.modelcontextprotocol/ui"]?.mimeTypes?.includes("text/html;profile=mcp-app");
+import { hasUiSupport } from "@modelcontextprotocol/ext-apps/server";
 
-if (hasUISupport) {
+if (hasUiSupport(clientCapabilities)) {
   // Register tools with UI templates
   server.registerTool("get_weather", {
     description: "Get weather with interactive dashboard",

src/server/index.test.ts

@@ -4,6 +4,9 @@ import {
   registerAppResource,
   RESOURCE_URI_META_KEY,
   RESOURCE_MIME_TYPE,
+  hasUiSupport,
+  getUiCapability,
+  EXTENSION_ID,
 } from "./index";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
@@ -318,3 +321,162 @@ describe("registerAppResource", () => {
     expect(result).toEqual(expectedResult);
   });
 });
+
+describe("hasUiSupport", () => {
+  const MIME_TYPE = "text/html;profile=mcp-app";
+
+  it("should return false for null/undefined capabilities", () => {
+    expect(hasUiSupport(null)).toBe(false);
+    expect(hasUiSupport(undefined)).toBe(false);
+  });
+
+  it("should return false for empty capabilities", () => {
+    expect(hasUiSupport({})).toBe(false);
+  });
+
+  it("should detect support in experimental field", () => {
+    const caps = {
+      experimental: {
+        [EXTENSION_ID]: {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    expect(hasUiSupport(caps)).toBe(true);
+  });
+
+  it("should detect support in extensions field", () => {
+    const caps = {
+      extensions: {
+        [EXTENSION_ID]: {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    expect(hasUiSupport(caps)).toBe(true);
+  });
+
+  it("should detect support when both fields are present", () => {
+    const caps = {
+      experimental: {
+        [EXTENSION_ID]: {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+      extensions: {
+        [EXTENSION_ID]: {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    expect(hasUiSupport(caps)).toBe(true);
+  });
+
+  it("should return false if MIME type is not in the list", () => {
+    const caps = {
+      experimental: {
+        [EXTENSION_ID]: {
+          mimeTypes: ["text/plain"],
+        },
+      },
+    };
+    expect(hasUiSupport(caps)).toBe(false);
+  });
+
+  it("should check for custom MIME type when specified", () => {
+    const caps = {
+      experimental: {
+        [EXTENSION_ID]: {
+          mimeTypes: ["application/x-custom"],
+        },
+      },
+    };
+    expect(hasUiSupport(caps, "application/x-custom")).toBe(true);
+    expect(hasUiSupport(caps, MIME_TYPE)).toBe(false);
+  });
+
+  it("should return false when extension ID is missing", () => {
+    const caps = {
+      experimental: {
+        "some-other-extension": {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    expect(hasUiSupport(caps)).toBe(false);
+  });
+
+  it("should return false when mimeTypes is missing", () => {
+    const caps = {
+      experimental: {
+        [EXTENSION_ID]: {},
+      },
+    };
+    expect(hasUiSupport(caps)).toBe(false);
+  });
+});
+
+describe("getUiCapability", () => {
+  const MIME_TYPE = "text/html;profile=mcp-app";
+
+  it("should return undefined for null/undefined capabilities", () => {
+    expect(getUiCapability(null)).toBeUndefined();
+    expect(getUiCapability(undefined)).toBeUndefined();
+  });
+
+  it("should return undefined for empty capabilities", () => {
+    expect(getUiCapability({})).toBeUndefined();
+  });
+
+  it("should return capability from experimental field", () => {
+    const caps = {
+      experimental: {
+        [EXTENSION_ID]: {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    const result = getUiCapability(caps);
+    expect(result).toEqual({ mimeTypes: [MIME_TYPE] });
+  });
+
+  it("should return capability from extensions field", () => {
+    const caps = {
+      extensions: {
+        [EXTENSION_ID]: {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    const result = getUiCapability(caps);
+    expect(result).toEqual({ mimeTypes: [MIME_TYPE] });
+  });
+
+  it("should prefer extensions over experimental when both are present", () => {
+    const caps = {
+      experimental: {
+        [EXTENSION_ID]: {
+          mimeTypes: ["text/plain"],
+        },
+      },
+      extensions: {
+        [EXTENSION_ID]: {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    const result = getUiCapability(caps);
+    expect(result).toEqual({ mimeTypes: [MIME_TYPE] });
+  });
+
+  it("should return undefined when extension ID is missing", () => {
+    const caps = {
+      experimental: {
+        "some-other-extension": {
+          mimeTypes: [MIME_TYPE],
+        },
+      },
+    };
+    expect(getUiCapability(caps)).toBeUndefined();
+  });
+});

src/server/index.ts

@@ -281,3 +281,142 @@ export function registerAppResource(
     readCallback,
   );
 }
+
+/**
+ * Extension identifier for MCP Apps capability negotiation.
+ *
+ * Used as the key in `experimental` or `extensions` to advertise MCP Apps support.
+ */
+export const EXTENSION_ID = "io.modelcontextprotocol/ui";
+
+/**
+ * MCP Apps capability settings advertised by clients.
+ *
+ * @see {@link hasUiSupport} for checking client support
+ */
+export interface McpUiClientCapability {
+  /**
+   * Array of supported MIME types for UI resources.
+   * Must include `"text/html;profile=mcp-app"` for MCP Apps support.
+   */
+  mimeTypes?: string[];
+}
+
+/**
+ * Check if client capabilities indicate MCP Apps support.
+ *
+ * This helper checks both `experimental` and `extensions` fields for the
+ * MCP Apps capability, providing forward compatibility as the MCP specification
+ * evolves. Currently, `experimental` is preferred (it's part of the existing
+ * MCP schema); once SEP-1724 is accepted, `extensions` will be the canonical
+ * location.
+ *
+ * @param clientCapabilities - The client capabilities from the initialize response
+ * @param mimeType - MIME type to check for (defaults to `"text/html;profile=mcp-app"`)
+ * @returns `true` if the client supports MCP Apps with the specified MIME type
+ *
+ * @example Basic usage in server initialization
+ * ```typescript
+ * import { hasUiSupport, registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+ *
+ * server.oninitialized = ({ clientCapabilities }) => {
+ *   if (hasUiSupport(clientCapabilities)) {
+ *     registerAppTool(server, "weather", {
+ *       description: "Get weather with interactive dashboard",
+ *       _meta: { ui: { resourceUri: "ui://weather/dashboard" } },
+ *     }, weatherHandler);
+ *   } else {
+ *     // Register text-only fallback
+ *     server.registerTool("weather", {
+ *       description: "Get weather as text",
+ *     }, textWeatherHandler);
+ *   }
+ * };
+ * ```
+ *
+ * @example Checking for specific MIME type
+ * ```typescript
+ * if (hasUiSupport(clientCapabilities, "application/x-custom-widget")) {
+ *   // Client supports custom widget MIME type
+ * }
+ * ```
+ */
+export function hasUiSupport(
+  clientCapabilities:
+    | {
+        experimental?: Record<string, unknown>;
+        extensions?: Record<string, unknown>;
+      }
+    | null
+    | undefined,
+  mimeType: string = RESOURCE_MIME_TYPE,
+): boolean {
+  if (!clientCapabilities) {
+    return false;
+  }
+
+  // Check experimental field (current MCP schema)
+  const experimentalCap = clientCapabilities.experimental?.[
+    EXTENSION_ID
+  ] as McpUiClientCapability | undefined;
+  if (experimentalCap?.mimeTypes?.includes(mimeType)) {
+    return true;
+  }
+
+  // Check extensions field (future SEP-1724)
+  const extensionsCap = clientCapabilities.extensions?.[
+    EXTENSION_ID
+  ] as McpUiClientCapability | undefined;
+  if (extensionsCap?.mimeTypes?.includes(mimeType)) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Get MCP Apps capability settings from client capabilities.
+ *
+ * This helper retrieves the capability object from either `experimental` or
+ * `extensions`, preferring `extensions` when both are present (for forward
+ * compatibility with SEP-1724).
+ *
+ * @param clientCapabilities - The client capabilities from the initialize response
+ * @returns The MCP Apps capability settings, or `undefined` if not supported
+ *
+ * @example
+ * ```typescript
+ * import { getUiCapability } from "@modelcontextprotocol/ext-apps/server";
+ *
+ * const uiCap = getUiCapability(clientCapabilities);
+ * if (uiCap?.mimeTypes?.includes("text/html;profile=mcp-app")) {
+ *   // Client supports MCP Apps
+ * }
+ * ```
+ */
+export function getUiCapability(
+  clientCapabilities:
+    | {
+        experimental?: Record<string, unknown>;
+        extensions?: Record<string, unknown>;
+      }
+    | null
+    | undefined,
+): McpUiClientCapability | undefined {
+  if (!clientCapabilities) {
+    return undefined;
+  }
+
+  // Prefer extensions when available (forward compatibility with SEP-1724)
+  const extensionsCap = clientCapabilities.extensions?.[
+    EXTENSION_ID
+  ] as McpUiClientCapability | undefined;
+  if (extensionsCap) {
+    return extensionsCap;
+  }
+
+  // Fall back to experimental (current MCP schema)
+  return clientCapabilities.experimental?.[
+    EXTENSION_ID
+  ] as McpUiClientCapability | undefined;
+}