File Management

File Management

Reference for the files, assets, and folders MCP tools.

Three Tools

Note: Files cannot be uploaded directly from local disk via MCP. Use the import action to import from URLs.

Files Tool

Import Files from URL

Tool: files
Input: {
  "action": "import",
  "data": [{
    "url": "https://example.com/photo.jpg",
    "file": {
      "title": "Product Hero Image",
      "description": "Main product photo for landing page",
      "folder": "folder-uuid-here"
    }
  }]
}

Batch Import

Tool: files
Input: {
  "action": "import",
  "data": [
    {
      "url": "https://example.com/image1.jpg",
      "file": { "title": "Image 1", "folder": "folder-uuid" }
    },
    {
      "url": "https://example.com/image2.jpg",
      "file": { "title": "Image 2", "folder": "folder-uuid" }
    }
  ]
}

List Files

Tool: files
Input: {
  "action": "read",
  "query": {
    "fields": ["id", "title", "filename_download", "type", "filesize", "width", "height", "folder"],
    "filter": { "type": { "_starts_with": "image/" } },
    "sort": ["-uploaded_on"],
    "limit": 25
  }
}

Filter by Folder

Tool: files
Input: {
  "action": "read",
  "query": {
    "fields": ["id", "title", "type", "filesize"],
    "filter": { "folder": { "_eq": "folder-uuid" } },
    "limit": 50
  }
}

Update File Metadata

Tool: files
Input: {
  "action": "update",
  "keys": ["file-uuid"],
  "data": [{
    "title": "Updated Title",
    "description": "Better description for SEO",
    "focal_point_x": 0.5,
    "focal_point_y": 0.3
  }]
}

Delete Files

Tool: files
Input: {
  "action": "delete",
  "keys": ["file-uuid-1", "file-uuid-2"]
}

File Metadata Fields

Assets Tool

Retrieve file content as base64 for AI analysis:

Tool: assets
Input: { "id": "file-uuid" }

Returns:

{ "data": "base64-encoded-content", "mimeType": "image/jpeg" }

Supports images and audio files. Use for:

• Image analysis with vision models
• Reading document content
• Audio file processing

Folders Tool

Create Folder

Tool: folders
Input: {
  "action": "create",
  "data": [{
    "name": "Product Images",
    "parent": null
  }]
}

Create Nested Folder

Tool: folders
Input: {
  "action": "create",
  "data": [{
    "name": "Thumbnails",
    "parent": "parent-folder-uuid"
  }]
}

List Folders

Tool: folders
Input: {
  "action": "read",
  "query": {
    "fields": ["id", "name", "parent"],
    "sort": ["name"]
  }
}

Update Folder

Tool: folders
Input: {
  "action": "update",
  "keys": ["folder-uuid"],
  "data": [{ "name": "Renamed Folder" }]
}

Delete Folder

Tool: folders
Input: {
  "action": "delete",
  "keys": ["folder-uuid"]
}

Note: Folders are virtual (database only) — they don't correspond to filesystem directories in storage.

Common Workflows

Organize Files into Folders

1. Create folder structure:

Tool: folders
Input: {
  "action": "create",
  "data": [
    { "name": "Blog" },
    { "name": "Products" },
    { "name": "Team" }
  ]
}

2. Move files to folders:

Tool: files
Input: {
  "action": "update",
  "keys": ["file-uuid-1", "file-uuid-2"],
  "data": [{ "folder": "blog-folder-uuid" }]
}

Import and Catalog Images

1. Create target folder
2. Import files from URLs with metadata:

Tool: files
Input: {
  "action": "import",
  "data": [
    {
      "url": "https://cdn.example.com/hero.jpg",
      "file": {
        "title": "Homepage Hero",
        "folder": "folder-uuid"
      }
    }
  ]
}

Rename and Tag Files in Bulk

1. List files to rename:

Tool: files
Input: {
  "action": "read",
  "query": {
    "filter": { "title": { "_null": true } },
    "fields": ["id", "filename_download", "type"],
    "limit": 50
  }
}

2. Update each file with descriptive metadata

Analyze an Image

1. Get file UUID from files list
2. Retrieve content:

Tool: assets
Input: { "id": "file-uuid" }

3. The returned base64 data can be processed by vision models

Best Practices

• Use folders to organize files — don't leave everything in the root
• Set descriptive titles on import — don't rely on original filenames
• Tags are string | null in the MCP tool schema — pass a comma-separated string like "hero,product", never an array
• Filter by MIME type when listing: { "type": { "_starts_with": "image/" } }
• Set focal points for images used in cropped contexts
• Import files with metadata in a single call rather than importing then updating