1# File Handling in Widgets
2 
3Upload and download files from within widgets using the `useFiles` hook.
4 
5> **ChatGPT Apps SDK only.** The MCP Apps spec (SEP-1865) has [deferred file handling](https://github.com/modelcontextprotocol/ext-apps/issues/201). MCP Apps clients (Claude, Goose, VS Code) do not support file operations. Always check `isSupported` before calling `upload` or `getDownloadUrl`.
6 
7---
8 
9## `useFiles` Hook
10 
11```tsx
12import { useFiles } from "mcp-use/react";
13 
14const { upload, getDownloadUrl, isSupported } = useFiles();
15```
16 
17| Property | Type | Description |
18|----------|------|-------------|
19| `isSupported` | `boolean` | `true` only in ChatGPT Apps SDK. Always check before calling upload/getDownloadUrl. |
20| `upload` | `(file: File, options?) => Promise<FileMetadata>` | Upload a file. Model-visible by default. |
21| `getDownloadUrl` | `(file: FileMetadata) => Promise<{ downloadUrl: string }>` | Get a temporary download URL (~5 min). |
22 
23`FileMetadata` type: `{ fileId: string }`
24 
25---
26 
27## Basic Pattern
28 
29Always guard with `isSupported`. Render a fallback for MCP Apps clients:
30 
31```tsx
32import { useFiles, useWidget, McpUseProvider } from "mcp-use/react";
33import { useState } from "react";
34 
35export default function FileWidget() {
36  const { isPending } = useWidget();
37  const { upload, getDownloadUrl, isSupported } = useFiles();
38  const [fileId, setFileId] = useState<string | null>(null);
39  const [downloadUrl, setDownloadUrl] = useState<string | null>(null);
40 
41  if (isPending) return <McpUseProvider autoSize><div>Loading...</div></McpUseProvider>;
42 
43  // Renders in MCP Apps clients (Claude, Goose, etc.)
44  if (!isSupported) {
45    return (
46      <McpUseProvider autoSize>
47        <p>File operations require ChatGPT Apps SDK.</p>
48      </McpUseProvider>
49    );
50  }
51 
52  async function handleUpload(e: React.ChangeEvent<HTMLInputElement>) {
53    const file = e.target.files?.[0];
54    if (!file) return;
55    const { fileId } = await upload(file);
56    setFileId(fileId);
57  }
58 
59  async function handleGetLink() {
60    if (!fileId) return;
61    const { downloadUrl } = await getDownloadUrl({ fileId });
62    setDownloadUrl(downloadUrl);
63  }
64 
65  return (
66    <McpUseProvider autoSize>
67      <input type="file" onChange={handleUpload} />
68      {fileId && <button onClick={handleGetLink}>Get download link</button>}
69      {downloadUrl && <a href={downloadUrl} target="_blank">Download</a>}
70    </McpUseProvider>
71  );
72}
73```
74 
75---
76 
77## Model Visibility
78 
79By default, uploaded files are tracked in widget state under `imageIds` so ChatGPT includes them in the model's conversation context.
80 
81```tsx
82// Model-visible (default) — ChatGPT includes the file in context
83const { fileId } = await upload(file);
84 
85// Private — file is uploaded but model won't see it
86const { fileId } = await upload(file, { modelVisible: false });
87```
88 
89Use `modelVisible: false` when the file is for widget-internal use only (e.g. a reference image the widget processes, a config file the user uploads privately).
90 
91When `modelVisible: true` (default), the new `fileId` is appended to `imageIds` in widget state, preserving any existing IDs and other state fields.
92 
93---
94 
95## Storing fileId for Later
96 
97Download URLs are **temporary** (~5 minutes). Store the `fileId`, not the URL:
98 
99```tsx
100const { state, setState } = useWidget<{ uploadedFileId: string | null }>();
101 
102async function handleUpload(file: File) {
103  const { fileId } = await upload(file);
104  // Persist fileId in widget state so model can reference the upload
105  await setState({ uploadedFileId: fileId });
106}
107 
108async function handleDownload() {
109  if (!state?.uploadedFileId) return;
110  // Call getDownloadUrl fresh each time — don't cache the URL
111  const { downloadUrl } = await getDownloadUrl({ fileId: state.uploadedFileId });
112  window.open(downloadUrl, "_blank");
113}
114```
115 
116---
117 
118## Error Handling
119 
120Both `upload` and `getDownloadUrl` throw if called when `isSupported` is `false`. They also throw on host-level errors (network failure, policy violation):
121 
122```tsx
123try {
124  const { fileId } = await upload(file);
125  setFileId(fileId);
126} catch (err) {
127  console.error("Upload failed:", err);
128  setError(err instanceof Error ? err.message : "Upload failed");
129}
130```
131 
132---
133 
134## Key Rules
135 
136- **Always check `isSupported` first** — render a fallback UI for non-ChatGPT hosts
137- **Never cache download URLs** — they expire; call `getDownloadUrl` each time you need one
138- **Store `fileId` in widget state** if the user may need to re-download later
139- **Use `{ modelVisible: false }`** for files the model should not see
140- `upload` + `getDownloadUrl` are only available in ChatGPT Apps SDK — MCP Apps support is deferred
141 
142---
143 
144## Reference
145 
146- Full API reference: https://docs.mcp-use.com/typescript/server/widget-components/usefiles
147- Example server: `examples/server/ui/files/`
148