Skip to main content
MCP Apps SDK 
import { App } from "@modelcontextprotocol/ext-apps";

​
Overview

downloadFile requests the host to download one or more files on behalf of the app. Since MCP Apps run in sandboxed iframes where direct downloads are blocked by browser security policies, this method provides a host-mediated mechanism for file exports. Files can be provided in three ways:
  • Embedded text — inline text content (JSON, CSV, HTML, etc.) with a MIME type
  • Embedded binary — base64-encoded binary data (images, PDFs, etc.)
  • Resource link — a URL that the host fetches and downloads on behalf of the user
The host may deny the download request, in which case isError will be true in the response.

​
Signature

async downloadFile(
  params: { contents: (EmbeddedResource | ResourceLink)[] },
  options?: RequestOptions,
): Promise<{ isError?: boolean }>

​
Parameters

​
params
object
required
The download parameters.
​
contents
(EmbeddedResource | ResourceLink)[]
required
Array of resources to download. Each entry is either an EmbeddedResource containing inline content or a ResourceLink pointing to a fetchable URL.
​
EmbeddedResource
object
An inline resource with content included in the request.
​
type
"resource"
required
Must be "resource".
​
resource
object
required
​
uri
string
required
A URI identifying the file (e.g., "file:///export.json"). The host uses the filename portion for the download name.
​
mimeType
string
MIME type of the content (e.g., "application/json", "image/png").
​
text
string
Text content of the file. Use this for text-based formats. Mutually exclusive with blob.
​
blob
string
Base64-encoded binary content. Use this for binary formats. Mutually exclusive with text.
​
ResourceLink
object
A link to a resource the host should fetch and download.
​
type
"resource_link"
required
Must be "resource_link".
​
uri
string
required
URL the host should fetch to retrieve the file content.
​
name
string
Human-readable name for the download.
​
mimeType
string
Expected MIME type of the resource.
​
options
RequestOptions
Optional request configuration.
​
signal
AbortSignal
An AbortSignal to cancel the request.

​
Returns

​
result
object
​
isError
boolean
true if the host denied or failed to process the download request. When absent or false, the download was initiated.

​
Usage

​
Download embedded text content

Export generated text data such as JSON, CSV, or HTML: 
await app.downloadFile({
  contents: [{
    type: "resource",
    resource: {
      uri: "file:///export.json",
      mimeType: "application/json",
      text: JSON.stringify(data, null, 2),
    },
  }],
});

​
Download embedded binary content

Export binary data such as images or PDFs using base64 encoding: 
await app.downloadFile({
  contents: [{
    type: "resource",
    resource: {
      uri: "file:///image.png",
      mimeType: "image/png",
      blob: base64EncodedPng,
    },
  }],
});
Let the host fetch and download a file from an external URL: 
await app.downloadFile({
  contents: [{
    type: "resource_link",
    uri: "https://api.example.com/reports/q4.pdf",
    name: "Q4 Report",
    mimeType: "application/pdf",
  }],
});

​
Download multiple files at once

await app.downloadFile({
  contents: [
    {
      type: "resource",
      resource: {
        uri: "file:///summary.csv",
        mimeType: "text/csv",
        text: csvContent,
      },
    },
    {
      type: "resource",
      resource: {
        uri: "file:///chart.png",
        mimeType: "image/png",
        blob: chartImageBase64,
      },
    },
  ],
});