Skip to content
Fractal frac

FileRef

If your tool accepts user-provided files, declare file parameters with _meta["openai/fileParams"]. The value is a list of top-level input schema fields that ChatGPT will treat as files. Nested file fields are not supported.

To return downloadable files from a tool, include a file reference in structuredContent, usually under a field such as file_uri.

import { FileRef, McpServer } from "@usefractal/frac/server";
import { z } from "zod";


const server = new McpServer({ name: "my-app", version: "0.0.1" })
  .registerTool(
    {
      name: "process-file",
      inputSchema: {
        file: FileRef,
      },
      outputSchema: {
        file_uri: FileRef,
      },
      _meta: {
        // Tell ChatGPT where to reference files
        "openai/fileParams": ["file"],
      },
    },
    async ({ file }) => {
      const res = await fetch(file.download_url);
      // ...do something with the file content


      return {
        // Tell ChatGPT where to find files
        structuredContent: { file_uri: processedFile },
        content: [],
        isError: false,
      };
    },
  );

Shape

Section titled “Shape”
type FileRef = {
  file_id: string;
  download_url: string; // URL the tool handler or view component can fetch directly
  mime_type?: string;
  file_name?: string;
}

download_url is required in both input and output positions. On input, the host fills it. On output, your tool handler is responsible for producing a URL the host can fetch.

See also

Section titled “See also”