Library and Drive

Library & Drive

The read side (list_creations, browse_feed, download_creation) needs only the read scope; upload_image rides with generate; organising (organise_creation, manage_folder) needs manage. None of these tools spends credit.

Finding things — list_creations

Show me my last 10 videos. Find my creations tagged "cyberpunk". Pick a random image from my Portraits folder.

One tool, one mental model: pick at most one filter mode, then combine it with any of the cross-cutting filters.

Modes (mutually exclusive — combining two is rejected):

Mode	Meaning
folderId	One folder's contents; "root" = ungrouped creations
trashed: true	The trash instead of the active library
activity	A lens: all, history (generations), uploaded, likes, public, trash, sdk, mcp, portfolio
smart	A smart collection: faces, videos, crop, alpha, or favorites (creations inside starred folders)
sharedFolderId	A folder another user shared with this account — read-only collaborator view
groupId	A folder group — creations across every folder filed in it (ids from manage_folder → list-groups)

Cross-cutting filters, valid with any mode:

• search — whole words over descriptions + tags, AND-combined; a trailing * makes a token a prefix (cyber*).
• sort — newest (default), oldest, updated, size-desc/size-asc, type-asc/type-desc.
• hideFiled — skip creations already filed into a folder (on the history/uploaded/likes/sdk/mcp lenses).
• usedRef — only creations built from a given creation (reference slots and lineage, clone families included). "What did I make with this face?"
• ratioFilter — one to three of square, landscape, portrait.
• from / to — a date range, ISO 8601 dates or instants (UTC). A day alone includes that whole day (to: "2026-10-20" keeps the 20th); an unreadable date is refused.
• likeFilter — liked keeps the creations this account liked, unliked the others; works on every mode, shared folders included (always the account's own likes).
• mediaKind — image (GIFs included), video (clips) or audio (MP3 uploads).
• blockNsfw — hide NSFW rows on this call even when the account shows them; the account's own NSFW preference always applies.

Pagination: default 20 rows, max 100. Newest-first pages emit a nextBeforeDate cursor — pass it back to continue; other sorts page with page. Random: random: true returns one uniformly-random creation from the filtered set instead of a page — images and videos only, so not available on the trash nor with mediaKind: "audio".

Rows are deliberately slim — id, prompt/description excerpts, tool, source, dimensions, folder and state flags — and carry nsfwFlagged / nsfwRate so agents can apply their own content safeguards. The full asset is always one download_creation away.

The public feed — browse_feed

What are other creators publishing? Anything inspiring?

Pages through the platform-wide public feed, newest first (default 12 rows, max 24). Rows belong to other accounts: isOwner: false, prompts hidden. Your agent can like them (organise_creation), and that's it — feed rows can't be moved, trashed or downloaded into your drive. NSFW-flagged rows are excluded unless includeNsfw is set, and every row still carries its nsfwFlagged flag.

Organising — organise_creation

File those three into my Portraits folder, and trash the blurry one.

• move — needs a folderId; "root" detaches back to the drive root.
• trash / restore — always reversible, single creation.
• batch-trash / batch-restore — up to 100 ids in one call, same reversible semantics. The result reports how many were processed and how many were skipped (already in the requested state, or not eligible).
• like / unlike — these set the like state rather than toggling it, so a repeat is harmless. Works on your own creations and on public feed rows.
• delete — permanent, including the stored media, and deliberately narrow: one creation per call, no batch form, and it only works on a creation already in trash. Trash first, then delete — and agents are instructed to delete only when the user explicitly asked for permanent removal.

Folders & sidebar groups — manage_folder

Make a "Client X" folder inside a new "Work" group, star it, and use the best render as its cover.

• create — a title, optionally a description and a groupId to create it inside a group.
• rename — title and/or description.
• delete — the folder disappears; its creations detach to the drive root by default, or go to (restorable) trash with trashContents: true. Folder deletion is never a permanent creation delete.
• set-favorite — star/unstar. Starred folders feed the favorites smart collection in list_creations.
• set-poster — pin a creation as the folder cover ("none" clears it).
• Groups are the collapsible sidebar sections that hold folders: create-group, rename-group, delete-group (only detaches its folders — nothing else is deleted), list-groups, and move-to-group on a folder ("none" detaches). list-groups needs only read; everything else here is manage.

list_folders (scope read) pages the folder list — sort: "index" returns them in the user's manual sidebar order.

Uploading — upload_image and upload_audio

Upload ./sketch.png as a reference and put it in my Refs folder.

An MP3 goes through upload_audio instead: it becomes the audio reference of a Gen8 Preview video clip (audioCreationId + audioUse on generate_video), 5 minutes max, Holder tier and up, listed with mediaKind: "audio".

Puts a local image (or raw base64) on your cloud drive so generations can reference it — jpeg/png/webp/gif, or an mp4/m4v video clip (the same container, stored as mp4; accounts allowed to upload videos only). Free, generate scope, max 10 MB on the free tier and up to 100 MB at Founder (a 413 carries the account's actual max). An unreadable file is refused with 400 INVALID_MEDIA, a DRM-protected clip (iTunes / FairPlay, CENC) with 400 PROTECTED_MEDIA. Every upload goes through the platform's moderation pass — NSFW beyond the account's ceiling is rejected, and a flagged-but-accepted upload comes back with nsfwFlagged set.

• Filing: targetFolderId files the upload directly into a folder you can write to; omit it to land at the drive root.
• Lineage: croppedFromCreationId records the upload as a crop edit of a creation you own; erasedFromCreationId records an erase (alpha) edit. Mutually exclusive. The parent's description and moderation verdict are inherited, and the pair shows up as an edit family in lineage-aware listings (usedRef).

Downloading — download_creation

Save that at full resolution to ./renders/.

Two behaviors, one tool:

• With savePath — the full-resolution asset is written to disk and the final path returned; the right extension (.jpg, .mp4, …) is appended automatically.
• Without savePath — a downscaled preview is returned inline so the model can look at the image without pulling megabytes through the context window. Videos have no inline form — pass savePath for those.
• On the hosted server (mcp.2dai.io) — there is no disk of yours to write to, so savePath is refused and the reply carries downloadUrl: the full-resolution file on the API, to GET with the same Authorization: Bearer header you send to the server (public creations need none).

Accepts a creationId (preferred) or a raw cdnId.

The file sandbox

upload_image reads and download_creation writes are confined to the MCP server's working directory — typically your project folder. Anything outside it (including through symlinks, which are resolved before the check) is refused with a clear error. This is deliberate: an agent following a prompt-injected instruction must not be able to exfiltrate arbitrary files from your machine through an upload, nor scribble outside the project on a download.

If you genuinely want whole-disk access, start the server with TWODAI_FILE_ACCESS=any in its env block (TWODAI_ALLOW_ANY_PATH=1 still works) — and understand you are removing that boundary for every agent that can call these tools. TWODAI_FILE_ACCESS=none removes the filesystem altogether: uploads take base64, downloads hand out downloadUrl. That is the hosted server's fixed mode — its disk is our container, not your machine.