What

Add a new ui/download-file JSON-RPC request that allows MCP App views to request file downloads through the host.

Why

MCP Apps run in sandboxed iframes where direct file downloads are blocked (allow-downloads is not set). Based on developer feedback, many apps need file export capabilities — visualization tools (SVG/PNG export), document editors, data analysis tools, and any app producing downloadable artifacts. ui/download-file provides a host-mediated mechanism for this, consistent with the existing ui/open-link pattern.

Design: MCP Resource Types

Following feedback to reuse existing MCP primitives, the params use standard MCP resource types instead of custom fields:

params: {
  contents: (EmbeddedResource | ResourceLink)[]
}

• EmbeddedResource — Inline content via resource.text (UTF-8) or resource.blob (base64). The host creates a blob and triggers the download directly.
• ResourceLink — A reference URI the host resolves via resources/read on the MCP server. This avoids passing large content through postMessage and lets hosts show resource "bubbles" or use native download mechanisms.

This approach:

• Reuses existing MCP primitives (EmbeddedResource, ResourceLink) instead of inventing new content formats
• Enables hosts to present downloads as resource bubbles (VS Code pattern) rather than just triggering saves
• Supports ResourceLink for cases where the host can fetch directly, avoiding unnecessary data transfer through the iframe

Changes

Spec (specification/draft/apps.mdx)

• Add ui/download-file request to "Requests (View → Host)" section with examples for both EmbeddedResource and ResourceLink
• Add downloadFile capability to HostCapabilities
• Document host behavior: confirmation dialog, filename derivation, base64 decoding, ResourceLink resolution via resources/read

SDK

• spec.types.ts: McpUiDownloadFileRequest uses (EmbeddedResource | ResourceLink)[], McpUiDownloadFileResult, downloadFile in McpUiHostCapabilities, DOWNLOAD_FILE_METHOD constant
• app.ts: App.downloadFile() method with JSDoc examples for embedded text, embedded blob, and resource link
• app-bridge.ts: AppBridge.ondownloadfile setter with JSDoc example showing both resource types
• types.ts: Re-exports, AppRequest/AppResult union additions
• generate-schemas.ts: Added EmbeddedResourceSchema, ResourceLinkSchema to external type list
• generated/: Auto-generated Zod schemas using SDK schema imports

Example

• integration-server: Two side-by-side demo buttons:
  • Embedded — Downloads inline JSON via EmbeddedResource (text content)
  • Link — Downloads a server-hosted resource via ResourceLink (host resolves via resources/read)
• integration-server/server.ts: Registers a sample downloadable resource at resource:///sample-report.txt

Protocol

// EmbeddedResource (inline content)
{
  jsonrpc: "2.0", id: 1,
  method: "ui/download-file",
  params: {
    contents: [{
      type: "resource",
      resource: {
        uri: "file:///export.json",
        mimeType: "application/json",
        text: "{ \"data\": 42 }"
      }
    }]
  }
}

// ResourceLink (host resolves via resources/read)
{
  jsonrpc: "2.0", id: 1,
  method: "ui/download-file",
  params: {
    contents: [{
      type: "resource_link",
      uri: "resource:///report.pdf",
      name: "Q4 Report",
      mimeType: "application/pdf"
    }]
  }
}

// Success: { jsonrpc: "2.0", id: 1, result: {} }
// Error:   { jsonrpc: "2.0", id: 1, error: { code: -32000, message: "Download denied by user" } }

App SDK Usage

// EmbeddedResource (inline)
await app.downloadFile({
  contents: [{
    type: "resource",
    resource: { uri: "file:///export.json", mimeType: "application/json", text: data },
  }],
});

// ResourceLink (host resolves)
await app.downloadFile({
  contents: [{
    type: "resource_link",
    uri: "resource:///report.pdf",
    name: "Q4 Report",
    mimeType: "application/pdf",
  }],
});

Security

• Host SHOULD show confirmation dialog (same pattern as ui/open-link)
• Host SHOULD sanitize filenames to prevent path traversal
• Host MAY impose size limits
• No allow-downloads on iframe — download is always host-mediated
• For ResourceLink, host resolves via MCP resources/read (no direct HTTP fetch from iframe)