fs_upload
fs_upload = files. fs_write = text and small inline content. Uploads an image, PDF, video, zip, font, large artifact, or attachment without carrying binary bytes or base64 in tool arguments.
Client capability matrix:
Native-file connector clients:
filecarries a temporary authorized file reference that this tool streams through the upload relay.Clients with raw HTTP access: an omitted
filemints a one-timeupload_urlthat accepts raw bytes with the returned Content-Type. This two-step transport keeps base64 out of tool arguments. One request carries at most 100 MB; a bigger file goes up in parts through the returnedmultipart_url(start, send each part, then complete — the reply spells out the steps). Withsize_bytes, a file over 90 MB comes back already started, withparts_url,part_size,part_countandcomplete_url; a size over the plan's per-file limit is refused with PAYLOAD_TOO_LARGE before any byte moves.Other shell-less MCP clients: standard MCP arguments have no protocol-level file input, so upload availability depends on compatible host file references or raw HTTP access.
The connector reference and upload URL are temporary transports, not the durable artifact. After storage, the saved bytes are addressed by path; fs_signed_url provides a private human download and public:true with fs_public_url provides a permanent public URL. The PUT response and native call both return { path, size_bytes, content_type, version }.
file must be a connector-provided file reference. A local path string, URL string, base64 string, or text value is rejected rather than being mistaken for bytes. content_type overrides connector metadata; otherwise MIME is inferred from connector metadata and the filename/path. Files are private unless public:true is supplied.
Native connector call:
{ "project_id": "my-saas", "path": "/uploads/alice/avatar.png", "file": "<attached connector file>", "public": true }Raw-PUT fallback:
{ "project_id": "my-saas", "path": "/uploads/archive.zip", "content_type": "application/zip" }Large file (over 90 MB), uploaded in parts:
{ "project_id": "my-saas", "path": "/uploads/video.mp4", "content_type": "video/mp4", "size_bytes": 125829120 }Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project_id": "<project_id>",
"path": "<path>"
},
"name": "fs_upload"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Native connector file reference shaped as {download_url, file_id, mime_type?, file_name?}. Path strings, base64, and inline bytes are rejected. An omitted value requests the raw-PUT upload_url fallback. | |
| path | Yes | Destination storage path with leading slash, e.g. "/uploads/avatar.png". | |
| public | No | Serve this file at a public /storage URL. Default false (private). | |
| project_id | Yes | Project ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them). | |
| size_bytes | No | Raw-PUT fallback only: the whole file size in bytes, when known. Over 90 MB, the upload starts in parts and the reply carries parts_url, part_size, part_count and complete_url; over the plan limit, it is refused with PAYLOAD_TOO_LARGE before any byte moves. | |
| content_type | No | Optional MIME override, e.g. "image/png". Otherwise inferred from connector metadata and filename/path. |