MCP Apps downloadFile - Download Files from Apps

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

object

required

The download parameters.

(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.

object

An inline resource with content included in the request.

"resource"

required

Must be "resource".

object

required

string

required

A URI identifying the file (e.g., "file:///export.json"). The host uses the filename portion for the download name.

string

MIME type of the content (e.g., "application/json", "image/png").

string

Text content of the file. Use this for text-based formats. Mutually exclusive with blob.

string

Base64-encoded binary content. Use this for binary formats. Mutually exclusive with text.

object

A link to a resource the host should fetch and download.

"resource_link"

required

Must be "resource_link".

string

required

URL the host should fetch to retrieve the file content.

string

Human-readable name for the download.

string

Expected MIME type of the resource.

RequestOptions

Optional request configuration.

AbortSignal

An AbortSignal to cancel the request.

Returns

object

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,
    },
  }],
});

Download via resource link

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,
      },
    },
  ],
});

Requests overview — all available View-to-host request methods
useDownloadFile — sunpeak React convenience hook
Core Types — EmbeddedResource and ResourceLink type definitions

Overview

App

MCP

React

Server

Styling

Types

MCP Apps downloadFile - Download Files from Apps

Overview

Signature

Parameters

Returns

Usage

Download embedded text content

Download embedded binary content

Download via resource link

Download multiple files at once

​Overview

​Signature

​Parameters

​Returns

​Usage

​Download embedded text content

​Download embedded binary content

​Download via resource link

​Download multiple files at once

​Related

Overview

Signature

Parameters

Returns

Usage

Download embedded text content

Download embedded binary content

Download via resource link

Download multiple files at once

Related