Clarify spec and SDK: accept UIResourceMeta in both resources/list and resources/read (#410)

* Clarify spec and SDK: accept UIResourceMeta in both resources/list and resources/read

The spec defines UIResource with _meta.ui, implicitly as an extension of the Resource type (resources/list), but examples and practice place _meta.ui on TextResourceContents (resources/read). The registerAppResource helper accepts _meta.ui in its config (which ends up in resources/list), but examples only return said _meta.ui from resources/read — and current hosts might be just ignoring it.

This change:
- Adds a 'Metadata Location' subsection to the draft spec explicitly stating that _meta.ui is valid on both the resource listing entry AND the content item, with content-item taking precedence.
- Updates the spec example to show _meta on the resource declaration (resources/list).
- Updates the CSP construction example to reference both locations.
- Clarifies McpUiAppResourceConfig JSDoc: _meta here appears in resources/list and serves as a listing-level fallback for when content items omit _meta.ui.
- Fixes the map-server example comment that incorrectly stated _meta must only be on the content item.

* Add McpUiReadResourceResult type for UI metadata in resources/read

* basic-host: support UIResourceMeta fallback from resources/list

---------

Co-authored-by: Claude <noreply@anthropic.com>

examples/basic-host/src/implementation.ts

@@ -2,7 +2,7 @@ import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNo
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
 import { getTheme, onThemeChange } from "./theme";
 import { HOST_STYLE_VARIABLES } from "./host-styles";
 
@@ -22,6 +22,7 @@ export interface ServerInfo {
   name: string;
   client: Client;
   tools: Map<string, Tool>;
+  resources: Map<string, Resource>;
   appHtmlCache: Map<string, string>;
 }
 
@@ -36,7 +37,12 @@ export async function connectToServer(serverUrl: URL): Promise<ServerInfo> {
   const tools = new Map(toolsList.tools.map((tool) => [tool.name, tool]));
   log.info("Server tools:", Array.from(tools.keys()));
 
-  return { name, client, tools, appHtmlCache: new Map() };
+  // Fetch resources for listing-level _meta.ui (fallback for content-level)
+  const resourcesList = await client.listResources();
+  const resources = new Map(resourcesList.resources.map((r) => [r.uri, r]));
+  log.info("Server resources:", Array.from(resources.keys()));
+
+  return { name, client, tools, resources, appHtmlCache: new Map() };
 }
 
 async function connectWithFallback(serverUrl: URL): Promise<Client> {
@@ -128,14 +134,23 @@ async function getUiResource(serverInfo: ServerInfo, uri: string): Promise<UiRes
 
   const html = "blob" in content ? atob(content.blob) : content.text;
 
-  // Extract CSP and permissions metadata from resource content._meta.ui (or content.meta for Python SDK)
+  // Extract CSP and permissions metadata, preferring content-level (resources/read)
+  // and falling back to listing-level (resources/list) per the spec
   log.info("Resource content keys:", Object.keys(content));
   log.info("Resource content._meta:", (content as any)._meta);
 
-  // Try both _meta (spec) and meta (Python SDK quirk)
+  // Try both _meta (spec) and meta (Python SDK quirk) for content-level
   const contentMeta = (content as any)._meta || (content as any).meta;
-  const csp = contentMeta?.ui?.csp;
-  const permissions = contentMeta?.ui?.permissions;
+
+  // Get listing-level metadata as fallback
+  const listingResource = serverInfo.resources.get(uri);
+  const listingMeta = (listingResource as any)?._meta;
+  log.info("Resource listing._meta:", listingMeta);
+
+  // Content-level takes precedence, fall back to listing-level
+  const uiMeta = contentMeta?.ui ?? listingMeta?.ui;
+  const csp = uiMeta?.csp;
+  const permissions = uiMeta?.permissions;
 
   return { html, csp, permissions };
 }

examples/map-server/server.ts

@@ -128,7 +128,7 @@ export function createServer(): McpServer {
       );
       return {
         contents: [
-          // _meta must be on the content item, not the resource metadata
+          // CSP metadata on the content item takes precedence over listing-level _meta
           {
             uri: RESOURCE_URI,
             mimeType: RESOURCE_MIME_TYPE,

specification/draft/apps.mdx

@@ -260,6 +260,17 @@ The resource content is returned via `resources/read`:
 }
 ```
 
+#### Metadata Location
+
+`UIResourceMeta` (CSP, permissions, domain, prefersBorder) may be provided on either or both:
+
+- **`resources/list`:** On the resource entry's `_meta.ui` field. Useful as a static default that hosts can review at connection time.
+- **`resources/read`:** On each content item's `_meta.ui` field. Useful for per-response overrides or dynamic metadata that is only known at read time.
+
+When `_meta.ui` is present on **both**, the content-item value takes precedence. Hosts MUST check both locations, preferring the content item and falling back to the listing entry.
+
+> **Server guidance:** Prefer placing `_meta.ui` on the content item in `resources/read`, especially when metadata is dynamic or varies per-response. Use the listing-level `_meta.ui` (via `registerAppResource` config) when metadata is static and you want hosts to be able to review security configuration at connection time without fetching the resource.
+
 #### Content Requirements:
 
 - URI MUST start with `ui://` scheme
@@ -287,15 +298,24 @@ The resource content is returned via `resources/read`:
 Example:
 
 ```json
-// Resource declaration
+// Resource declaration (resources/list) — static defaults for host review
 {
   "uri": "ui://weather-server/dashboard-template",
   "name": "weather_dashboard",
   "description": "Interactive weather dashboard view",
-  "mimeType": "text/html;profile=mcp-app"
+  "mimeType": "text/html;profile=mcp-app",
+  "_meta": {
+    "ui": {
+      "csp": {
+        "connectDomains": ["https://api.openweathermap.org"],
+        "resourceDomains": ["https://cdn.jsdelivr.net"]
+      },
+      "prefersBorder": true
+    }
+  }
 }
 
-// Resource content with metadata
+// Resource content (resources/read) — takes precedence when present
 {
   "contents": [{
     "uri": "ui://weather-server/dashboard-template",
@@ -1725,8 +1745,10 @@ Hosts MUST enforce Content Security Policies based on resource metadata.
 **CSP Construction from Metadata:**
 
 ```typescript
-const csp = resource._meta?.ui?.csp; // `resource` is extracted from the `contents` of the `resources/read` result
-const permissions = resource._meta?.ui?.permissions;
+// Prefer content-level _meta.ui (resources/read), fall back to listing-level (resources/list)
+const uiMeta = resource._meta?.ui ?? listingResource._meta?.ui;
+const csp = uiMeta?.csp;
+const permissions = uiMeta?.permissions;
 
 const cspValue = `
   default-src 'none';

src/server/index.ts

@@ -45,7 +45,7 @@ import type {
   RegisteredTool,
   ResourceMetadata,
   ToolCallback,
-  ReadResourceCallback,
+  ReadResourceCallback as _ReadResourceCallback,
   RegisteredResource,
 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type {
@@ -54,12 +54,13 @@ import type {
 } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import type {
   ClientCapabilities,
+  ReadResourceResult,
   ToolAnnotations,
 } from "@modelcontextprotocol/sdk/types.js";
 
 // Re-exports for convenience
 export { RESOURCE_URI_META_KEY, RESOURCE_MIME_TYPE };
-export type { ResourceMetadata, ToolCallback, ReadResourceCallback };
+export type { ResourceMetadata, ToolCallback };
 
 /**
  * Base tool configuration matching the standard MCP server tool options.
@@ -111,12 +112,19 @@ export interface McpUiAppToolConfig extends ToolConfig {
  * Extends the base MCP SDK `ResourceMetadata` with optional UI metadata
  * for configuring security policies and rendering preferences.
  *
+ * The `_meta.ui` field here is included in the `resources/list` response and serves as
+ * a static default for hosts to review at connection time. When the `resources/read`
+ * content item also includes `_meta.ui`, the content-item value takes precedence.
+ *
  * @see {@link registerAppResource `registerAppResource`} for usage
  */
 export interface McpUiAppResourceConfig extends ResourceMetadata {
   /**
    * Optional UI metadata for the resource.
-   * Used to configure security policies (CSP) and rendering preferences.
+   *
+   * This appears on the resource entry in `resources/list` and acts as a listing-level
+   * fallback. Individual content items returned by `resources/read` may include their
+   * own `_meta.ui` which takes precedence over this value.
    */
   _meta?: {
     /**
@@ -236,6 +244,18 @@ export function registerAppTool<
   return server.registerTool(name, { ...config, _meta: normalizedMeta }, cb);
 }
 
+export type McpUiReadResourceResult = ReadResourceResult & {
+  _meta?: {
+    ui?: McpUiResourceMeta;
+    [key: string]: unknown;
+  };
+};
+export type McpUiReadResourceCallback = (
+  uri: URL,
+  extra: Parameters<_ReadResourceCallback>[1],
+) => McpUiReadResourceResult | Promise<McpUiReadResourceResult>;
+export type ReadResourceCallback = McpUiReadResourceCallback;
+
 /**
  * Register an app resource with the MCP server.
  *
@@ -354,7 +374,7 @@ export function registerAppResource(
   name: string,
   uri: string,
   config: McpUiAppResourceConfig,
-  readCallback: ReadResourceCallback,
+  readCallback: McpUiReadResourceCallback,
 ): RegisteredResource {
   return server.registerResource(
     name,