Skip to content

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 with attach_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 with list_artifacts/read_artifact.

See also Files & Documents in the guide.

list_files ​

Cloud Drive files of a task or list. read · follower

ParameterTypeDefaultDescription
itemIdstring–UUID or SID of a task: its files box, files directly on the item and file sub-items
listIdstring–UUID or SID of a list: files anywhere in the list
limitnumber50Max. 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

ParameterTypeDefaultDescription
fileIdstring (required)–file_id from list_files or from a file entry in an item's refs
max_bytesnumber2 MBSize cap; hard maximum 25 MB. Larger files are not transferred, only their size comes back
encodingenum auto | text | base64autoauto = 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.

Create a link to one file or a whole folder in the Cloud Drive, e.g. to paste into a chat. write · user

ParameterTypeDefaultDescription
itemstring (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
revokebooleanfalsetrue = revoke the link instead of creating it
expires_in_daysinteger 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.

Open a shared file link (https://<host>/<org>/f/<id>). read · follower

ParameterTypeDefaultDescription
urlstring–The file link
sidstring–Alternative to url: just the id after /f/
include_contentbooleanfalseAlso return the content of text files
max_charsinteger 500–20000040000Cap for the text; longer files are cut with a note
folderstring–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
ParameterTypeDescription
itemIdstring (required)UUID or SID of the task
namestring (required)Display name. Publishing again under the same name on the same task = new version
entrystring (required)Relative path of the entry file, e.g. index.html — must be one of the paths in files
filesobject[] (required)Per file: path (relative, e.g. assets/style.css), either content_text or content_base64, optional mime
kindenum doc | page | app | dataKind; inferred from the extension of entry if omitted
labelstringShort label for the version, ideally what changed
conversation_idstringUUID 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

ParameterTypeDescription
itemIdstring (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

ParameterTypeDefaultDescription
itemIdstring (required)–UUID or SID of the task
artifactstring–Name, slug or artifact_id from list_artifacts; may be omitted if the task has exactly one artifact
pathstringentry fileFile inside the bundle
versionintegercurrentRead an older version
max_bytesnumber2 MBSize cap; hard maximum 25 MB
encodingenum auto | text | base64autoas for read_file

Text files come back as text, images as an image block, other binary files base64-encoded.