feat: add ui/download-file method for host-mediated file downloads by antonpk1 · Pull Request #475 · modelcontextprotocol/ext-apps

antonpk1 · 2026-02-19T21:29:48Z

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)awaitapp.downloadFile({contents: [{type: "resource",resource: {uri: "file:///export.json",mimeType: "application/json",text: data},}],});// ResourceLink (host resolves)awaitapp.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)

Add a new ui/download-file JSON-RPC request that allows MCP App views to request file downloads through the host. Since MCP Apps run in sandboxed iframes where direct downloads are blocked (allow-downloads not set), this provides a host-mediated mechanism for file exports. Spec changes (draft): - Add ui/download-file request to Requests (View → Host) section - Add downloadFile capability to HostCapabilities - Document host behavior requirements (confirmation dialog, filename sanitization, base64 decoding, size limits) SDK changes: - Add McpUiDownloadFileRequest/Result interfaces to spec.types.ts - Add downloadFile() method to App class - Add ondownloadfile setter to AppBridge class - Add DOWNLOAD_FILE_METHOD constant - Generate Zod schemas Example: - Add download demo to integration-server (exports JSON with server time) - Capability check: only shows download button when host advertises downloadFile capability Based on developer feedback requesting file export capabilities for visualization tools, document editors, and data analysis apps.

antonpk1 · 2026-02-19T22:30:58Z

cc curious what do you guys think about it? @idosal @liady

ochafik · 2026-02-20T00:11:37Z

cc/ @connor4312 @nickcoai for input too :-)

connor4312 · 2026-02-20T02:56:03Z

This is kind of neat

I think in VS Code I would not implement this as a direct download but instead have it create a "resource" bubble similar to resources that come from tool calls. Users could view or save that as they wish. That may inform bikeshedding on method naming :)
postMessage can transfer arraybuffers. The API for doing so is kind of 'weird' especially when we're trying to say we speak JSON-RPC, but that could be a consideration if we start thinking about performance with larger file downloads.
💡 I wonder if we want to make params be an object like { contents: (MCP.ResourceLink | MCP.EmbeddedResource)[]; }. If the resource is embedded, great (params is aready a pseudo-embedded resource.) If it's a link, then the host can retrieve it on the app's behalf. In the case of a link to an https or file scheme, the hosts can use existing semantics to have the user agent/device fetch/copy them directly, avoiding the need to retrieve and then pass data through the host entirely.

Replace custom {filename, content, mimeType, encoding} params with standard MCP resource types: EmbeddedResource for inline content and ResourceLink for host-resolved references. New params shape: params: { contents: (EmbeddedResource | ResourceLink)[] } This reuses existing MCP primitives instead of inventing new ones, and enables hosts to show resource 'bubbles' or resolve ResourceLink URIs via resources/read on the MCP server.

antonpk1 · 2026-02-20T12:02:45Z

thank you @connor4312
using resources here is really good idea, updated the PR :)

connor4312

lgtm I think :)

connor4312 · 2026-02-20T16:09:02Z

+* For `EmbeddedResource` with `blob`, host MUST decode the content from base64 before creating the file.
+* For `ResourceLink`, host MAY fetch the resource on behalf of the app or open the URI directly.
+* Host MAY reject the download based on security policy, file size limits, or user preferences.
+* Host SHOULD sanitize filenames to prevent path traversal.


I think this is no longer relevant in the resources world

Good call — removed the two bullets that were just restating standard EmbeddedResource/ResourceLink behavior. Kept the download-specific ones (confirmation dialog, filename derivation, security policy, path sanitization). Updated in f07bdfb.

Remove bullets that restate standard EmbeddedResource/ResourceLink behavior already defined in the MCP resource spec. Keep download-specific host behavior (confirmation dialog, filename derivation, security policy, path sanitization).

ochafik

Thanks @antonpk1 !

ochafik · 2026-02-24T15:26:52Z

can you add a test to app-bridge.test.ts that exercices the two ends?

ochafik

Thanks!

idosal · 2026-02-24T18:31:02Z

+
+The `contents` array uses standard MCP resource types (`EmbeddedResource` and `ResourceLink`), avoiding custom content formats. For `EmbeddedResource`, content is inline via `text` (UTF-8) or `blob` (base64). For `ResourceLink`, the host can retrieve the content directly from the URI.
+
+Host behavior:


@antonpk1 should we provide some guidance on payload size? postMessage can be fairly constrained (depending on both browser and device).

idosal · 2026-02-24T18:32:44Z

Cool @antonpk1 ! Sorry, missed this. I'm a little late to the party, but I think we might run into issues with postMessage for large files. Perhaps we need some guidance.

Changes since 1.1.1: - feat: add ui/download-file method for host-mediated file downloads (#475) - pdf-server: robust path validation + folder/file root support (#497) - ci: auto-fix prettier formatting in pre-commit hook and CI (#498)

* chore: bump ext-apps to 1.1.2 Changes since 1.1.1: - feat: add ui/download-file method for host-mediated file downloads (#475) - pdf-server: robust path validation + folder/file root support (#497) - ci: auto-fix prettier formatting in pre-commit hook and CI (#498) * fix: sync local SDK build into node_modules for examples npm workspaces hoists example dependencies to the root node_modules, but installs the published registry copy of @modelcontextprotocol/ext-apps instead of linking to the local source. This causes type-check failures when examples use features not yet published to npm. Add scripts/link-self.mjs which copies the freshly-built dist/ and package.json into the hoisted node_modules copy after each SDK build, ensuring examples always type-check against the latest local types. See: npm/feedback#774 * Revert "fix: sync local SDK build into node_modules for examples" This reverts commit e3387e8.

antonpk1 marked this pull request as ready for review February 19, 2026 22:30

antonpk1 requested a review from ochafik February 19, 2026 22:30

antonpk1 requested a review from idosal February 19, 2026 22:31

connor4312 reviewed Feb 20, 2026
View reviewed changes

ochafik previously approved these changes Feb 24, 2026
View reviewed changes

Comment threadsrc/app-bridge.ts
ochafikFeb 24, 2026
Copy link
Copy Markdown
Contributor
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can you add a test to app-bridge.test.ts that exercices the two ends?

test: add App → AppBridge integration test for downloadFile
9340bd8

antonpk1 dismissed ochafik’s stale review via 9340bd8February 24, 2026 16:58

ochafik approved these changes Feb 24, 2026
View reviewed changes

antonpk1 merged commit e4a9766 into mainFeb 24, 2026
9 of 18 checks passed

idosal reviewed Feb 24, 2026
View reviewed changes

ochafik mentioned this pull request Feb 24, 2026
chore: bump ext-apps to 1.1.2 #503
Merged

connor4312 mentioned this pull request Mar 3, 2026
MCP Apps: support download call microsoft/vscode#298836
Closed

Navigation Menu

Uh oh!

feat: add ui/download-file method for host-mediated file downloads - #475

feat: add ui/download-file method for host-mediated file downloads#475
antonpk1 merged 4 commits into
mainfrom
feat/download-file

antonpk1 commented Feb 19, 2026•
edited
Loading

Uh oh!

antonpk1 commented Feb 19, 2026

Uh oh!

ochafik commented Feb 20, 2026

Uh oh!

connor4312 commented Feb 20, 2026•
edited
Loading

Uh oh!

antonpk1 commented Feb 20, 2026

Uh oh!

connor4312 left a comment

Uh oh!

connor4312Feb 20, 2026

Uh oh!

antonpk1Feb 23, 2026

Uh oh!

ochafik left a comment

Uh oh!

ochafikFeb 24, 2026

Uh oh!

ochafik left a comment

Uh oh!

Uh oh!

idosalFeb 24, 2026

Uh oh!

idosal commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		The `contents` array uses standard MCP resource types (`EmbeddedResource` and `ResourceLink`), avoiding custom content formats. For `EmbeddedResource`, content is inline via `text` (UTF-8) or `blob` (base64). For `ResourceLink`, the host can retrieve the content directly from the URI.

		Host behavior:

Uh oh!

Conversation

antonpk1 commented Feb 19, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Design: MCP Resource Types

Changes

Spec (specification/draft/apps.mdx)

SDK

Example

Protocol

App SDK Usage

Security

Uh oh!

antonpk1 commented Feb 19, 2026

Uh oh!

ochafik commented Feb 20, 2026

Uh oh!

connor4312 commented Feb 20, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

antonpk1 commented Feb 20, 2026

Uh oh!

connor4312 left a comment

Choose a reason for hiding this comment

Uh oh!

connor4312Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

antonpk1Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

ochafikFeb 24, 2026

Choose a reason for hiding this comment

Uh oh!

ochafik left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

idosalFeb 24, 2026

Choose a reason for hiding this comment

Uh oh!

idosal commented Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

antonpk1 commented Feb 19, 2026•
edited
Loading

Spec (`specification/draft/apps.mdx`)

connor4312 commented Feb 20, 2026•
edited
Loading