MCP Tools Reference
Complete reference for every LiveFolio MCP tool — parameters, return values, and usage examples.
The MCP surface is grouped by goal — a "project" IS a folio. Conventions: "no args = read" (the manage_* tools, claim_handle, get_purchases); destructive tools require confirmed: true (the exact boolean); purchases and seller onboarding work by URL relay — you hand the user a URL, then poll.
Availability: tools and sections marked (cloud) exist only on LiveFolio Cloud — a self-hosted instance does not expose them. Those marked (OSS only) exist only locally. Everything unmarked works in both. The full local list is at Self-Hosted Tools.
Folios
list_projects
List all folios in your workspace.
Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
include_archived | boolean | No | Include archived folios. Default false — archived folios are hidden. |
Returns: { projects: [{ project_id, title, description, status, archived, file_count, version_count, open_comments, updated_at, share_url, edit_url, studio_url }], total }
edit_url opens the folio in the editor (/app/{id}); share_url is the recipient-facing link. studio_url is a deprecated alias of edit_url.
get_project
Retrieve full details of a specific folio.
Parameters:
| Param | Type | Required |
|---|---|---|
project_id | string | Yes |
Returns: current_files, version_history, open_comments, chats, design_preferences, project_mode, visibility (status, isPrivate, hasAccessKey), analytics (views/time/device), and URLs.
create_project
Publish a new folio.
Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Folio title |
initial_html | string | Yes | Full HTML content |
description | string | No | Optional description |
project_mode | string | No | "deck", "document", "spreadsheet", "dashboard", "infography" |
design_preferences | object | No | Theme, palette, typography, custom colors, libraries |
reference_files | array | No | Reference documents for the workspace context |
project_id | string | No | Workspace folder to add the folio to |
thumbnail_url | string | No | Cover image URL |
Binary files: Include images as base64 Data URLs (data:image/png;base64,...). They're automatically decoded.
Publishing, pricing, and Explore listing are configured after creation with manage_sharing, manage_paid_access, and manage_listing.
Returns: { success, project_id, share_url, edit_url, studio_url }
Share share_url with your user. edit_url (aliased as the deprecated studio_url) is the owner-facing editor link at /app/{id}.
update_project
Edit files (merged — only send what changed; each file change creates a version) or title/description/thumbnail (no version bump).
Parameters:
| Param | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | Project ID |
updated_files | object | No | Map of filename → content |
change_message | string | No | Commit message for the new version |
title / description / thumbnail_url | string | No | Metadata changes (no new version) |
delete_project
PERMANENTLY DELETE a folio — this cannot be undone.
| Param | Type | Required | Description |
|---|---|---|---|
project_id | string | Yes | Project ID |
confirmed | boolean | Yes | Must be exactly true |
archive_folio
Hide a folio from every public surface without deleting it: it is unpublished, unlisted from Explore, and no longer resolves on share links, your profile, or its workspace page. Only you keep access — archived folios appear in the Archived section of the sidebar.
Nothing is deleted and archived folios still count toward storage quota. Idempotent — archiving an already-archived folio succeeds and keeps the original timestamp.
| Param | Type | Required |
|---|---|---|
project_id | string | Yes |
Returns: { success, project_id, status: "draft", archived: true, archived_at, note }
unarchive_folio
Restore an archived folio. It comes back as a draft and stays unlisted — nothing ever republishes automatically. Call manage_sharing with status: "published" afterwards when the owner wants it live again.
| Param | Type | Required |
|---|---|---|
project_id | string | Yes |
Returns: { success, project_id, status: "draft", archived: false, archived_at: null, note }
duplicate_project (cloud)
Copy a folio into your account. Paid folios require an active purchase grant and the seller's allowCopy setting. The copy lands as a draft titled "... (copy)".
| Param | Type | Required |
|---|---|---|
project_id | string | Yes |
Design & Feedback
get_curated_brief
Returns: { title, description, brief (markdown), openComments[] } compiled from open feedback pins. Requires project_id.
get_active_design_system
Returns: { usesTailwind, fonts[], themeAnalysis (markdown), projectMode, theme, palette, typography }. Requires project_id.
add_comment
Add a review comment or canvas pin (pins carry x/y percent coordinates and an optional selector).
| Param | Type | Required |
|---|---|---|
project_id | string | Yes |
text | string | Yes |
type | "pin" | "comment" | No (default pin) |
x, y | number | Pin only |
selector, elementHtml | string | Pin only |
version_id, filename | string | No (defaults: latest / index.html) |
moderate_comment
Moderate a comment/pin: resolve (mark handled), reopen, or delete (permanent).
| Param | Type | Required |
|---|---|---|
action | "resolve" | "reopen" | "delete" | Yes |
project_id | string | Yes |
comment_id | string | Yes |
add_reaction
Increment one aggregate emoji count: 👍 ❤️ 💡 🔥. Counts are aggregate — removal is not supported.
| Param | Type | Required |
|---|---|---|
project_id | string | Yes |
emoji | enum (4 emojis) | Yes |
Sharing & Monetization
manage_sharing
Read or change visibility: status (draft = owner-only, published = public), isPrivate, accessKey, allowComments, presentationModeOnly. No version bump. No fields beyond project_id = read current settings.
manage_paid_access (cloud)
Read or change the paid-access gate. No paid_access field = read. paid_access: null = clear the gate. Config shape: { enabled, priceType (one_time|rental|subscription), amountCents (min 100), currency (usd|eur|gbp), rentalDays?, interval?, previewMode (none|timed|first_page), previewSeconds?, allowCopy?, allowDownload? }. ASK the user for price details before setting a gate.
manage_listing (cloud)
Read or change the Explore marketplace listing: listed, category (10 shelves), tags (max 8), creation, license { kind, allowModify, allowResale, requireAttribution, maxProjects }. No fields beyond project_id = read current listing plus listing eligibility and the exact human steps required.
Listing requires the workspace Owner's Seller Terms acceptance and a one-time per-folio rights affirmation — human consent steps an agent can never perform. The read mode reports what's missing; the write mode returns clear blocking errors.
Marketplace (cloud)
search_marketplace (cloud)
Browse the public Explore index. Filters: category (10 shelves), tag, query (title/description), offset, limit (default 48). Returns published, moderation-clean listings with canonical @username share links, prices, and licenses.
buy_project (cloud)
Start a purchase for a paid folio (workspace gates resolve automatically). Returns a checkout_url — relay it to the user and ask them to complete payment in their browser, then poll get_purchases with the session_id. Errors map to human-readable reasons (NO_GATE_CONFIGURED, CREATOR_NOT_CONNECTED, …).
get_purchases (cloud)
With session_id: poll whether that checkout's grant was provisioned (webhooks can lag the redirect — poll again). Without: the full purchase history.
manage_seller_account (cloud)
action: "status" — Stripe Connect state + sales summary (gross/fees/net, count). action: "onboard" — creates/reuses the Stripe Express account and returns an onboarding URL to relay. Arriving at the return page does not mean onboarding is complete (a webhook flips the status to active).
Workspace (cloud)
list_workspaces (cloud)
The workspace folders that organize folios: { project_id, name, slug, description, is_public, archived, folio_count }.
| Param | Type | Required | Description |
|---|---|---|---|
include_archived | boolean | No | Include archived workspaces. Default false — archived workspaces are hidden. |
manage_workspace (cloud)
| action | Params | Notes |
|---|---|---|
create | name (req), description?, is_public? | New folder |
update | project_id + name?/description?/is_public? | Rename / visibility |
delete | project_id + confirmed: true | Folios inside are detached, not deleted |
add_folio | project_id + folio_id | Move a folio into the folder |
archive | project_id | Hides the folder and unpublishes/unlists every folio inside it. Nothing is deleted; archived folios still count toward storage |
unarchive | project_id | Restores the folder and its folios as drafts — nothing republishes automatically |
Moving or creating a folio inside an archived workspace is rejected — unarchive the workspace first.
manage_member (cloud)
No action = list members (with roles and emails). invite (email, role — direct-add if the account exists, otherwise an email invitation; Team-plan seats enforced). update_role (member_id, role). remove (member_id). Owner/Admin only; the Owner is immutable; Admins cannot modify fellow Admins.
Profile & Social (cloud)
manage_profile (cloud)
No action = read (profile, follow counts, seller-terms state). action: "update" accepts full_name, bio, website, avatar_url, is_public, accent_color (#RRGGBB), featured_folio_id (must be your own), username (claims the handle).
claim_handle (cloud)
With username: claims the @handle (invalid / reserved / taken errors are explicit). Without: returns 3 available suggestions seeded from the account name.
follow_profile (cloud)
Toggle follow/unfollow a creator by @username. Returns { following, follower_count }. Cannot follow yourself.
get_public_profile (cloud)
Read a creator's public profile and catalog by @username: bio/avatar/website, follower and following counts, their published public folios (with canonical share links, prices, and Explore-listing status), and their public workspaces. Private or suspended profiles return a clear not-found. This is how agents discover a creator's catalog without browsing the web.
| Param | Type | Required |
|---|---|---|
username | string | Yes (omit the @) |
Self-Hosted Tools (OSS only)
OSS instances expose only the Folios + Design & Feedback groups plus manage_sharing, and these three tunnel tools — no marketplace, purchases, workspaces, members, profiles, or handles.
get_sharing_status
- Purpose: Global public tunnel status (active state, current live public URL, custom tunnel URL config) and optionally a folio's
publicTunnelEnabledpermission. - Arguments:
project_id(optional).
toggle_sharing_tunnel
- Purpose: Start or stop the global background public sharing tunnel (Cloudflare/untun).
- Arguments:
action(required) —"start"or"stop".
set_folio_public_access
- Purpose: Enable or disable public web access for a specific folio over the active public tunnel.
- Arguments:
project_id(required),enabled(required, boolean).