Skip to main content
FileRef is a reference to a file, an id and a URL to fetch its bytes. Use it in a tool’s inputSchema or outputSchema to pass files in and out.
File params are a ChatGPT feature. Other hosts don’t pass files through tool calls, so a FileRef field is populated only on ChatGPT.

​
Example

summarize-document takes a file in, fetches its bytes from download_url, and returns a summary file back.
server.ts
import { FileRef, McpServer } from "skybridge/server";

const server = new McpServer({ name: "docs", version: "1.0" }).registerTool(
  {
    name: "summarize-document",
    inputSchema: { document: FileRef },
    outputSchema: { summary: FileRef },
    _meta: { "openai/fileParams": ["document"] },
  },
  async ({ document }) => {
    const bytes = await fetch(document.download_url).then((r) => r.blob());
    const summary = await summarize(bytes); // returns a FileRef
    return { structuredContent: { summary } };
  },
);

​
Shape

type FileRef = {
  file_id: string;
  download_url: string;
  mime_type?: string;
  file_name?: string;
};
FieldPurpose
file_idThe host’s identifier for the file.
download_urlA URL to fetch the file’s bytes.
mime_typeThe file’s MIME type, when known.
file_nameThe original file name, when known.
download_url is required in both positions: on input the host fills it, on output your handler produces a URL the host can fetch.

Handle Files

Move files in and out of your app across hosts

useFiles

Upload, pick, and resolve files from the view

registerTool

Declare file params with openai/fileParams