useDownloadFile

sunpeak API

Overview

Returns a function to download files through the host. Since MCP Apps run in sandboxed iframes where direct downloads are blocked, this provides a host-mediated mechanism for file exports. Supports embedded text content, embedded binary (base64) content, and resource links that the host fetches on behalf of the app.

Wraps downloadFile

MCP Apps SDK reference

Import

import { useDownloadFile } from 'sunpeak';

Signature

function useDownloadFile(): (params: DownloadFileParams) => Promise<DownloadFileResult | undefined>

DownloadFileParams

contents

(EmbeddedResource | ResourceLink)[]

required

Resource contents to download — embedded (inline data) or linked (host fetches).

Returns

downloadFile

(params: DownloadFileParams) => Promise<DownloadFileResult | undefined>

Function to request a file download through the host.

DownloadFileResult

isError

boolean

Whether the download failed (e.g. user cancelled or host denied).

Usage

Embedded text content

import { useDownloadFile } from 'sunpeak';

function ExportButton({ data }: { data: unknown }) {
  const downloadFile = useDownloadFile();

  return (
    <button onClick={() => downloadFile({
      contents: [{
        type: 'resource',
        resource: {
          uri: 'file:///export.json',
          mimeType: 'application/json',
          text: JSON.stringify(data, null, 2),
        },
      }],
    })}>
      Export JSON
    </button>
  );
}

Resource link (host fetches)

const downloadFile = useDownloadFile();

await downloadFile({
  contents: [{
    type: 'resource_link',
    uri: 'https://api.example.com/reports/q4.pdf',
    name: 'Q4 Report',
    mimeType: 'application/pdf',
  }],
});

useHostContextReactive access to the host context.

​Overview

Wraps downloadFile

​Import

​Signature

​DownloadFileParams

​Returns

​DownloadFileResult

​Usage

​Embedded text content

​Resource link (host fetches)