MCP tools: Files & artifacts
A task has two separate stores:
- Cloud Drive — files someone attaches or files away (the input). Read them with
list_files/read_file, pass them on with a file link. File them withattach_file_to_list_item. - Artifacts — results an AI produces and publishes (the output): named, versioned bundles in the task's "Artifacts" box. They are not in
list_files; read them withlist_artifacts/read_artifact.
See also Files & Documents in the guide.
list_files
Cloud Drive files of a task or list. read · follower
| Parameter | Type | Default | Description |
|---|---|---|---|
itemId | string | – | UUID or SID of a task: its files box, files directly on the item and file sub-items |
listId | string | – | UUID or SID of a list: files anywhere in the list |
limit | number | 50 | Max. number |
Pass exactly one of itemId and listId. Each file comes with, among others, file_id, name, mime, size, readable_as_text, location and item_id (the file item). file_id goes to read_file, item_id to share_file_link. Files in external storage (Unified.to) come from search_files instead.
read_file
Content of a Cloud Drive file. read · follower
| Parameter | Type | Default | Description |
|---|---|---|---|
fileId | string (required) | – | file_id from list_files or from a file entry in an item's refs |
max_bytes | number | 2 MB | Size cap; hard maximum 25 MB. Larger files are not transferred, only their size comes back |
encoding | enum auto | text | base64 | auto | auto = text for text files, base64 otherwise |
Text files (md, txt, json, csv, code …) come back as text, other binary files base64-encoded. Images (PNG, JPEG, WebP, GIF up to 4 MB) come back as an MCP image block a model can look at directly.
share_file_link
Create a link to one file or a whole folder in the Cloud Drive, e.g. to paste into a chat. write · user
| Parameter | Type | Default | Description |
|---|---|---|---|
item | string (required) | – | The file or folder item (UUID, SID or its link) — not the task. item_id from list_files or attach_file_to_list_item |
revoke | boolean | false | true = revoke the link instead of creating it |
expires_in_days | integer 1–3650 | – | Limit the link to this many days; without it the link does not expire |
All members of the organization can open the link, even without access to the project — guests cannot. If an active link exists, it is returned. You can only share files you can read yourself; if the project has turned file links off, the call fails. Response: url, active, created, opened_count.
get_file_link
Open a shared file link (https://<host>/<org>/f/<id>). read · follower
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | – | The file link |
sid | string | – | Alternative to url: just the id after /f/ |
include_content | boolean | false | Also return the content of text files |
max_chars | integer 500–200000 | 40000 | Cap for the text; longer files are cut with a note |
folder | string | – | Folder links only: SID of a subfolder from entries |
The response carries name, type, size, date and shared_by. Images, PDFs, videos and other binary files come back as a download_url (valid for 15 minutes). A folder link returns kind: "folder" with its entries. Expired, revoked or foreign links return an error with the reason.
publish_artifact
Attach a result to a task as an artifact, visible to the whole team.
write · user| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID of the task |
name | string (required) | Display name. Publishing again under the same name on the same task = new version |
entry | string (required) | Relative path of the entry file, e.g. index.html — must be one of the paths in files |
files | object[] (required) | Per file: path (relative, e.g. assets/style.css), either content_text or content_base64, optional mime |
kind | enum doc | page | app | data | Kind; inferred from the extension of entry if omitted |
label | string | Short label for the version, ideally what changed |
conversation_id | string | UUID of the AI conversation the version came out of |
An artifact is a named bundle of one or more files with an entry point, at most 50 files and 25 MB. If the bundle is byte-identical to the current version, no new version is created (unchanged: true). The response includes artifact_id, slug, version, created.
For files that are merely filed away (inputs, uploads, references), attach_file_to_list_item is the right tool.
list_artifacts
The artifacts of a task. read · follower
| Parameter | Type | Description |
|---|---|---|
itemId | string (required) | UUID or SID of the task |
Per artifact: ID, name, kind, current version, entry file, the files of the current version and the version history.
read_artifact
Read the content of an artifact. read · follower
| Parameter | Type | Default | Description |
|---|---|---|---|
itemId | string (required) | – | UUID or SID of the task |
artifact | string | – | Name, slug or artifact_id from list_artifacts; may be omitted if the task has exactly one artifact |
path | string | entry file | File inside the bundle |
version | integer | current | Read an older version |
max_bytes | number | 2 MB | Size cap; hard maximum 25 MB |
encoding | enum auto | text | base64 | auto | as for read_file |
Text files come back as text, images as an image block, other binary files base64-encoded.