File Tools

The Bizzy MCP server provides 8 tools for managing files and folders in organization storage. These tools are organized into two categories: files and folders.

Files

Tools for uploading, downloading, listing, searching, and deleting files. File content is exchanged as base64-encoded strings to support the MCP protocol.

uploadFile

Upload a file to organization storage with base64-encoded content. Permission: files:write Parameters:

Name	Type	Required	Description
`filename`	string	Yes	Name of the file (1-255 characters)
`content`	string	Yes	Base64-encoded file content (max 10MB file size)
`contentType`	string	Yes	MIME type of the file (e.g., `application/pdf`, `image/png`)
`folderId`	string (UUID) \| null	No	Optional folder ID to place the file in
`description`	string	No	Optional description of the file (max 5000 characters)
`tags`	string[]	No	Optional tags for the file (max 10)

Returns: Object with success boolean and a file object containing id, filename, size, contentType, and folderId.

downloadFile

Download a file from organization storage as base64-encoded content. Permission: files:read Parameters:

Name	Type	Required	Description
`fileId`	string (UUID)	Yes	The ID of the file to download

Returns: Object with a file metadata object (id, filename, contentType, size) and a content string containing base64-encoded file bytes.

Downloads are gated by each file’s agentAccessEnabled flag. Files with agent access disabled return an error.

listFiles

List files in organization storage with optional folder filtering and pagination. Permission: files:read Parameters:

Name	Type	Required	Default	Description
`folderId`	string (UUID) \| null	No	-	Filter by folder ID (`null` for root level, omit for all files)
`limit`	number	No	10	Number of files to return (1-100)
`offset`	number	No	0	Pagination offset
`sortOrder`	string	No	”desc”	Sort order by creation date (`asc` or `desc`)

Returns:

{
  "files": [...],
  "count": 23,
  "limit": 10,
  "offset": 0
}

searchFiles

Find files by name or content. searchFiles runs a hybrid full-text search that combines two signals and fuses them so a file matching on both ranks highest:

Metadata — filename, description, and tags.
Content — the text of the file’s indexed pages (for files Bizzy has finished indexing).

Returns ranked file records (not passages). Use searchFiles to locate files; use askFiles to answer a question from their contents. Permission: files:read Parameters:

Name	Type	Required	Default	Description
`query`	string	Yes	-	Search query matched against filename, description, tags, and file content (1-255 characters)
`limit`	number	No	10	Number of results to return (1-100)
`offset`	number	No	0	Pagination offset
`folderIds`	string[]	No	-	Optional list of folder UUIDs to restrict the search to. When provided, only files inside the listed folders match — files at the root level (no folder) are excluded

Returns:

{
  "files": [...],
  "count": 5,
  "query": "invoice",
  "limit": 10,
  "offset": 0
}

Results are limited to files with agent access enabled. A file excluded from content indexing still appears when its name matches — exclusion only removes it from content matching, not from search.count reflects the deduplicated union of metadata and content candidates within a bounded window (up to 500 matches per side), not an exhaustive tally. For large result sets, page through with limit and offset.

askFiles

New Answer a natural-language question using passages retrieved from the organization’s indexed files. Returns ranked citations — each backed by a source file, page number (when available), and an excerpt — rather than whole file records. Use this when a question may be answered by uploaded documents, and always cite the returned files when synthesizing an answer. Permission: files:read Parameters:

Name	Type	Required	Default	Description
`query`	string	Yes	-	Natural-language question to answer from file contents (1-1000 chars)
`limit`	number	No	10	Maximum number of citations to return (1-50)
`folderIds`	string[]	No	-	Optional list of folder UUIDs to restrict retrieval to. When provided, only files inside the listed folders match — files at the root level (no folder) are excluded

Returns: Object with the echoed query and a citations array. Each citation contains fileId, filename, pageNumber (nullable), snippet, score, and chunkIndex.

{
    "query": "What is the roofing warranty term?",
    "citations": [
        {
            "fileId": "f4c1…",
            "filename": "warranty.pdf",
            "pageNumber": 3,
            "snippet": "Roofing warranty covers material defects for 25 years…",
            "score": 0.0328,
            "chunkIndex": 7
        }
    ]
}

Only files with agent access enabled and a completed indexing status are searched. Newly uploaded files become answerable once indexing finishes.

deleteFile

Delete a file from organization storage (soft delete). Permission: files:delete Parameters:

Name	Type	Required	Description
`fileId`	string (UUID)	Yes	The ID of the file to delete

Returns: Object with success boolean, the deleted file object, and a message string.

Folders

Tools for organizing files into a folder hierarchy. Folders can be nested up to 5 levels deep.

createFolder

Create a new folder in organization storage with optional parent folder (max 5 levels deep). Permission: folders:write Parameters:

Name	Type	Required	Description
`name`	string	Yes	Name of the folder (1-255 characters)
`parentFolderId`	string (UUID) \| null	No	Optional parent folder ID (`null` for root level)

Returns: The created folder object.

listFolders

List folders in organization storage with optional parent folder filtering and pagination. Permission: folders:read Parameters:

Name	Type	Required	Default	Description
`parentFolderId`	string (UUID) \| null	No	-	Filter by parent folder ID (`null` for root level, omit for all folders)
`limit`	number	No	10	Number of folders to return (1-100)
`offset`	number	No	0	Pagination offset
`sortOrder`	string	No	”desc”	Sort order by creation date (`asc` or `desc`)

Returns:

{
  "folders": [...],
  "count": 6,
  "limit": 10,
  "offset": 0
}

Getting Started

Agent resources

Files

uploadFile

downloadFile

listFiles

searchFiles

askFiles

deleteFile

Folders

createFolder

listFolders

Next Steps

Contact Tools

Authentication

​Files

​uploadFile

​downloadFile

​listFiles

​searchFiles

​askFiles

​deleteFile

​Folders

​createFolder

​listFolders

​Next Steps

Contact Tools

Authentication

Files

uploadFile

downloadFile

listFiles

searchFiles

askFiles

deleteFile

Folders

createFolder

listFolders

Next Steps