Layovelle

Tools Reference

Documentation

Legacy. This section documents the original Layovelle MCP server at mcp.moda.app/mcp, built around start_design_task and get_moda_canvas. It is superseded by Layovelle for Agents — the moda CLI wherever your agent has a shell, and the Layovelle connector for claude.ai and other chat hosts. The connector replaces this server, so the tools below retire with it. These pages stay published for existing integrations; start new ones on Layovelle for Agents.

The Layovelle MCP server provides 20+ tools for working with canvas designs. These tools are called automatically by your AI coding agent when it needs design data or wants to create and manage designs.

Tool	Description	Auth required
`get_moda_bootstrap`	Fetch Layovelle session bootstrap before any canvas work (call first)	Yes
`set_context`	Set your active organization and team	Yes
`get_context`	Show your current session context	Yes
`set_session_brand_kit`	Pin a brand kit for this session	Yes
`get_moda_canvas`	Fetch semantic pseudo-HTML and design tokens	Public links: No
`get_moda_canvas_tokens`	Extract design tokens only	Public links: No
`list_moda_canvas_pages`	List pages with dimensions and node counts	Public links: No
`export_canvas`	Export as PNG, JPEG, PDF, PPTX, MP4, or GIF	Yes
`get_export_status`	Poll an in-progress export	Yes
`list_my_canvases`	Browse your canvases	Yes
`search_canvases`	Search canvases by name	Yes
`list_organizations`	List your orgs and teams	Yes
`find_brand_kits`	JSON-only brand-kit lookup (agent-side, no iframe)	Yes
`list_brand_kits`	List brand kits — renders visual showcase iframe	Yes
`create_brand_kit`	Create brand kit from website URL	Yes
`update_brand_kit`	Update brand kit colors, fonts, etc.	Yes
`set_default_brand_kit`	Mark a brand kit as the team’s default (destructive)	Yes
`list_brand_kit_images`	List logos and reference images for a kit	Yes
`remove_brand_kit_image`	Detach an image from a brand kit	Yes
`upload_file`	Upload a file from URL for attachments	Yes
`start_design_task`	Start an AI design task	Yes
`get_task_status`	Get task status and progress	Yes
`list_tasks`	List recent design tasks	Yes
`remix_design`	Duplicate canvas + optional AI edits	Yes
`list_my_websites`	Browse websites in your team	Yes
`get_website`	Read HTML, title, share state, published URL	Yes
`create_website_from_upload`	Create a website from an HTML upload	Yes
`update_website_from_upload`	Replace HTML and/or title of an existing website	Yes

Session context

When you first connect, Layovelle uses your default organization and team. If you belong to multiple organizations, you can switch with set_context:

Call list_organizations to see your orgs and teams.
Call set_context with the org name (and optionally team name).
All subsequent tool calls use that workspace automatically.

Your context persists for 24 hours across reconnections. Tools like list_brand_kits, create_brand_kit, start_design_task, and remix_design all read from your session context automatically. You can also pass org_id or team_id explicitly to override the session context for a single call.

URL formats

All tools that accept a url parameter support these formats:

Format	Example
Share link	`https://layovelle.com/s/abc123-token`
Private canvas URL	`https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000`
Raw share token	`abc123-token`
Legacy domain	`https://app.moda.so/s/abc123-token`

Private canvas URLs require authentication via the remote server.

set_context

Sets your preferred organization and team for the current session. Once set, all subsequent tools that operate within a workspace (brand kits, design tasks, remixes) will use these defaults automatically.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Description
`org_name`	`string`	Yes	Name of the organization to use (case-insensitive). Use `list_organizations` to see options.
`team_name`	`string`	No	Name of the team within the org (case-insensitive). Defaults to the org’s default team.

Returns

A confirmation string:

Context set to organization 'Acme Corp' and team 'Design Team'. All subsequent operations will use this workspace.

Example usage

# Set org (uses default team)
set_context(org_name="Acme Corp")

# Set org and specific team
set_context(org_name="Acme Corp", team_name="Marketing")

Notes

Call list_organizations first to see available organization and team names
Context persists for 24 hours across reconnections
You can call set_context again at any time to switch workspaces

get_context

Shows your current session context — which organization and team are active for workspace-scoped tools.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

This tool takes no parameters.

Returns

A string describing your current context:

Organization: Acme Corp | Team: Design Team

If no context is set:

No session context set. Call set_context to choose your organization and team.

get_moda_bootstrap

MANDATORY FIRST CALL, every new conversation, before creating, editing, reading, remixing, or exporting any canvas — even if the agent already knows the user’s identity: this returns far more than identity (the Layovelle skill pointer, active user, active workspace, and entitlements that affect tool-call decisions). The response also lets agents skip downstream lookups when defaults are unambiguous.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

This tool takes no parameters.

Returns

{
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Jane Doe",
    "email": "jane@acme.com"
  },
  "session": {
    "org_id": "660e8400-e29b-41d4-a716-446655440000",
    "org_name": "Acme Corp",
    "team_id": "770e8400-e29b-41d4-a716-446655440000",
    "team_name": "Design Team",
    "brand_kit_id": null
  },
  "org_count": 1,
  "team_default_brand_kit": {
    "id": "880e8400-e29b-41d4-a716-446655440000",
    "title": "Acme Corp"
  },
  "brand_kit_count": 1,
  "plan": "paid",
  "concurrency_cap": 10
}

Field	Type	Description
`user.id`	`string`	The Layovelle user UUID.
`user.name`	`string`	Display name.
`user.email`	`string`	Email address.
`session.org_id`	`string \| null`	Active org for this session, or null if unset.
`session.team_id`	`string \| null`	Active team for this session.
`session.brand_kit_id`	`string \| null`	Session-pinned brand kit, if any. Set via the showcase iframe button or `set_session_brand_kit`.
`org_count`	`integer`	Total orgs the user belongs to. If 1, no multi-org disambiguation is needed.
`team_default_brand_kit`	`object \| null`	The team default’s id + title, if a default exists.
`brand_kit_count`	`integer`	Brand kits in the active team. If 1, the agent can use that kit without further listing.
`plan`	`string`	Billing plan: `free`, `free_beta`, `paid`, `ultra`, or `enterprise`.
`concurrency_cap`	`integer`	Max concurrent design tasks for this plan. Use as the upper bound for bulk fan-out.

Notes

Reads from existing session context — no side effects.
A good first call on any new conversation: org_count, brand_kit_count, and concurrency_cap collectively eliminate the need for several downstream tool calls.
The plan value is the same enum returned by the billing service; concurrency_cap is pre-resolved so callers don’t need to maintain their own mapping.

set_session_brand_kit

Pin the brand kit the user chose for the current session without changing the team default. Subsequent calls to start_design_task / remix_design that omit brand_kit_id will resolve to this kit, and it counts as the user’s brand choice for new designs.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

This is what the brand-kit showcase iframe’s Use for this session button calls. For changing the team default (destructive, affects every team member), use set_default_brand_kit instead.

Parameters

Parameter	Type	Required	Description
`brand_kit_id`	`string \| null`	No	Brand kit UUID (or `bk_…` wire form). Pass null/empty to clear the session pin.

Returns

A confirmation string:

Session brand kit set to <uuid>. Subsequent design tasks will apply it unless overridden.

Or when cleared:

Session brand kit cleared. Edits keep each canvas's own kit; a new design needs the user's brand choice again.

Notes

Switching workspaces via set_context clears the session brand kit (kits are team-scoped).
Resolution order for start_design_task / remix_design: explicit brand_kit_id → session preference → (edits and remixes) the canvas’s own kit, then the team default → none (if skip_brand_kit=true). A new design with no choice is gated instead — see start_design_task.
The kit must belong to the active team; trying to pin a kit from a different team raises a tool error.

get_moda_canvas

The primary tool for design-to-code workflows. Fetches a Layovelle canvas and returns semantic pseudo-HTML with CSS properties and design tokens that AI agents can translate to any frontend framework.

Parameters

Parameter	Type	Required	Description
`url`	`string`	Yes	Layovelle share URL (`https://layovelle.com/s/...`), private canvas URL (`https://layovelle.com/canvas/...`), or raw share token
`page_number`	`integer \| null`	No	1-indexed page number. Omit to get all pages.

Returns

A string containing semantic pseudo-HTML with CSS properties, followed by a design tokens summary.

# Layovelle Design Export — Canvas Title # Source: https://layovelle.com/s/abc123 ## Page: Login Screen (1440x900) [page 1]

<section
  background="#f3f4f6"
  height="900px"
  width="1440px"
  display="flex"
  justify-content="center"
  align-items="center"
>
  <Card background="#ffffff" border-radius="16px" width="600px" display="flex" flex-direction="column" gap="20px">
    <Heading font-size="32px" font-weight="700" color="#111827">Welcome back</Heading>
    <Text font-size="14px" color="#6b7280"> Sign in to your account</Text>
    <TextInput border="1px solid #d1d5db" border-radius="8px" height="48px" width="520px" />
    <button background="#2563eb" border-radius="8px" height="48px" width="520px">Sign in</button>
  </Card>
</section>

## Design Tokens - Colors: #111827, #2563eb, #6b7280, #d1d5db, #f3f4f6, #ffffff - Font Inter: weights [400, 700] roles
[body, heading] - Corner radii: 8px, 16px

Semantic tags

The transformer assigns semantic tag names based on visual properties and layer names:

Tag	When used
`Heading`	Text with font-size >= 24px or font-weight >= 600
`Text`	Default text elements
`Button`	Rectangle with text, dark fill, and button-like dimensions
`TextInput`	Rectangle with light fill, thin border, no text
`Image`	Element with an image fill
`Avatar`	Small circular element with an image fill
`Card`	Group with a background rectangle and content
`Row`	Container with `flex-direction: row`
`Column`	Container with `flex-direction: column`
`Divider`	Line element
`Nav`, `Hero`, `Footer`	Matched from layer names

Layer names in Layovelle take priority over visual heuristics. See Naming Layers for best practices.

Example usage

# Fetch all pages
get_moda_canvas(url="https://layovelle.com/s/abc123")

# Fetch a specific page
get_moda_canvas(url="https://layovelle.com/s/abc123", page_number=2)

# Fetch a private canvas (requires authentication)
get_moda_canvas(url="https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000")

Notes

The output is intentionally HTML-like so agents can map it directly to React, Vue, or HTML components
Design tokens are appended as a summary at the end of the output
For multi-page canvases, omitting page_number returns all pages in a single response
Hidden layers are excluded from the output
Rich text extracts the first style span’s properties; mixed-style paragraphs use the first style encountered

get_moda_canvas_tokens

Returns only the design tokens from a canvas — colors, fonts, variables, and corner radii — as structured JSON. Use this when you need to generate theme configuration files without the full semantic layout.

Parameters

Parameter	Type	Required	Description
`url`	`string`	Yes	Layovelle share URL, private canvas URL, or raw share token
`page_number`	`integer \| null`	No	1-indexed page number. Omit for all pages.

Returns

{
  "variables": {
    "primary": "#2563eb",
    "secondary": "#6b7280",
    "background": "#f3f4f6"
  },
  "colors": ["#111827", "#2563eb", "#6b7280", "#d1d5db", "#f3f4f6", "#ffffff"],
  "fonts": [
    {
      "family": "Inter",
      "weights": [400, 700],
      "roles": ["body", "heading"]
    }
  ],
  "radii": ["8px", "16px"],
  "dimensions": {
    "width": 1440,
    "height": 900
  }
}

Field	Type	Description
`variables`	`object`	Named design variables defined in the canvas (colors, numbers, strings)
`colors`	`string[]`	All unique colors used in the canvas
`fonts`	`object[]`	Font families with weights and inferred roles
`radii`	`string[]`	All unique corner radii used
`dimensions`	`object`	Canvas page dimensions (width and height)

Example usage

# Extract tokens for theme generation
get_moda_canvas_tokens(url="https://layovelle.com/s/abc123")

# Extract tokens from a specific page
get_moda_canvas_tokens(url="https://layovelle.com/s/abc123", page_number=1)

Notes

Variables defined in the Layovelle canvas (via the variables panel) appear in the variables field with their default values
Colors are deduplicated and sorted
Font roles (body, heading) are inferred from usage context (font size and weight)

list_moda_canvas_pages

Returns metadata about each page in a canvas, including page names, dimensions, and the number of design elements. Use this to understand the structure of multi-page canvases before fetching specific pages.

Parameters

Parameter	Type	Required	Description
`url`	`string`	Yes	Layovelle share URL, private canvas URL, or raw share token

Returns

{
  "canvas_name": "Marketing Website",
  "total_pages": 3,
  "pages": [
    {
      "page_number": 1,
      "id": "p_a",
      "name": "Hero Section",
      "width": 1440,
      "height": 900,
      "node_count": 12
    },
    {
      "page_number": 2,
      "id": "p_b",
      "name": "Features",
      "width": 1440,
      "height": 1200,
      "node_count": 24
    }
  ],
  "id_note": "IDs like n1/p_a/img1 are session-scoped short refs..."
}

Field	Type	Description
`canvas_name`	`string`	Name of the canvas
`total_pages`	`integer`	Total number of pages
`pages[].page_number`	`integer`	1-indexed page number
`pages[].id`	`string`	The page’s addressable id — omitted only for a page-less canvas
`pages[].name`	`string`	Page name as set in Layovelle
`pages[].width`	`number`	Page width in pixels
`pages[].height`	`number`	Page height in pixels
`pages[].node_count`	`integer`	Number of design elements on the page
`id_note`	`string`	Present only when the ids are short refs; states their lifetime

Notes

Page numbers are 1-indexed
page_number vs id. The tools on this server (get_moda_canvas, get_moda_canvas_tokens, export_canvas) take page_number. pages[].id is for the page-scoped authoring endpoints, and unlike an ordinal it survives a page being deleted or reordered
id is either a durable real page id (page-1786730909610-172273165) or a session-scoped short ref (p_a). When id_note is present they are short refs — re-list to refresh rather than storing one
The node_count includes all visible elements on the page (shapes, text, images, groups)
Hidden elements are excluded from the count

export_canvas

Export a Layovelle canvas as an image or document file. Pass exactly one of canvas_id or url.

Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`string`	No	—	Canvas UUID to export directly. Preferred after `start_design_task` returns a new canvas.
`url`	`string`	No	—	Layovelle share URL, private canvas URL, or raw share token. Use this for share-link or design-to-code workflows.
`format`	`string`	No	`"png"`	Export format: `png`, `jpeg`, `pdf`, `pptx`, `mp4`, or `gif`
`scope`	`string`	No	`"page"`	What the export renders: `page` (one page, addressed by `page_number`), `sequence` (mp4 only — every visible page’s animation stitched into ONE video, in canvas order, transitions included; takes no `page_number`, requires a multi-page animation canvas), or `main_edit` (mp4 only — the canvas’s persisted Main Edit timeline; page-less, fine on a single-page canvas, rejected with `no_animation` when no edit is persisted).
`fps`	`integer \| null`	No	`null`	Animation formats only — capture frame rate: mp4 `24`/`30`/`60` (default 30), gif `10`/`12`/`15`/`24` (default 12). Integer rates only. The frame budget is rate-independent, so a higher fps shortens the longest exportable timeline (150 s of mp4 at 60 fps); over-budget requests are rejected with the live bound.
`page_number`	`integer \| null`	No	`null`	1-indexed page number. Omit to export all pages — PDF/PPTX bundle every page natively, while multi-page PNG/JPEG are returned as a `.zip` of per-page files (`page-1.png`, `page-2.png`, …) since a single image container can’t hold multiple pages. Single-page canvases still return a raw PNG/JPEG. The `format` field in the response reflects what was actually delivered (`zip` in the bundled case). MP4/GIF export exactly one page: required on a multi-page canvas, defaulted to 1 on a single-page one.
`pixel_ratio`	`integer \| null`	No	`null`	Render scale 1–4 for PNG, JPEG, PDF, MP4, and GIF (MP4/GIF default 1). Ignored for PPTX.
`flatten`	`boolean`	No	`true`	PDF only — produce a raster-only PDF with no searchable text layer.
`task_id`	`string \| null`	No	`null`	Optional task identifier to scope the export’s cache key. When provided, the rendered file is cached as a stable snapshot for that task — useful for design-task progress UIs that should keep showing the original task output even after the canvas is edited. When omitted (typical LLM use), the cache busts on any canvas-data change so direct re-exports always reflect the current state.
`wait`	`boolean`	No	`true`	When `true` (default), block up to ~20s for the export to finish before returning an in-progress handle. When `false`, return `status='in_progress'` with a `task_id` immediately — call `get_export_status(task_id)` to retrieve the URL once the background work completes. Cache hits return synchronously regardless.

Format guide

Format	Best for
`png`	Design-to-code workflows — lossless image, ideal for visual reference
`jpeg`	Smaller file size when lossless quality isn’t needed
`pdf`	Multi-page documents, printing, sharing
`pptx`	PowerPoint presentations, slide decks
`mp4`	Video of one page’s animation timeline, with its video-fill audio
`gif`	Animated image of one page’s animation timeline

mp4 and gif render a single page’s animation timeline by default (see scope for the stitched sequence and Main Edit forms). The page must actually have animation — a still page is rejected with a no_animation error. Each format is bounded per file, whichever half binds first: mp4 by 18,000 encoded frames and 600 s (600 s at the default 30 fps, 300 s at 60 fps), gif by 9,000 frames and 300 s (300 s at its 10–24 fps rates). A longer timeline is rejected at submit time with the concrete ceiling. For multi-page PNG/JPEG without page_number, the response carries format: "zip" and the URL serves a .zip of per-page raster files. The requested raster format is preserved inside the archive (page-1.png, page-2.png, …).

Returns

On success:

{
  "status": "completed",
  "url": "https://assets-cdn.moda.app/exports/abc123.png",
  "format": "png"
}

When the canvas has multiple pages and page_number was omitted, a PNG/JPEG export bundles into a zip:

{
  "status": "completed",
  "url": "https://assets-cdn.moda.app/exports/abc123.zip",
  "format": "zip",
  "total_pages": 8
}

When the export hasn’t finished within the synchronous wait budget (large multi-page canvases, cold renders), the call returns an in-progress handle. Call get_export_status(task_id) to fetch the URL once it’s ready — the same task_id keeps returning the in-progress shape until terminal:

{
  "status": "in_progress",
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "canvas_id": "660e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://layovelle.com/canvas/660e8400-e29b-41d4-a716-446655440000",
  "format": "pdf",
  "total_pages": 23,
  "retry_after_seconds": 5
}

If a design task is still active for the target canvas:

{
  "status": "not_ready",
  "reason": "active_design_job",
  "retry_after_seconds": 3,
  "canvas_id": "550e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000",
  "task_id": "990e8400-e29b-41d4-a716-446655440000"
}

canvas_id, canvas_url, and task_id are only included for authenticated private-canvas exports (i.e., when using canvas_id or a private URL). Share-link exports omit these fields to avoid leaking internal identifiers.

Field	Type	Description
`status`	`string`	`"completed"`, `"in_progress"`, or `"not_ready"` (active design job blocks export)
`url`	`string`	Signed URL to the exported file (only when `status='completed'`)
`format`	`string`	The format that was used for the export
`reason`	`string`	Retryable not-ready reason: `active_design_job` or `job_status_unavailable`
`retry_after_seconds`	`integer`	Suggested delay before retrying when `status` is `"not_ready"` or `"in_progress"`
`task_id`	`string`	Export task ID when `status='in_progress'`; pass to `get_export_status` to poll. Also surfaces the active design task ID when `status='not_ready'`.
`canvas_id`	`string`	Canvas UUID for the export target (private exports only)
`canvas_url`	`string`	Direct Layovelle link to the canvas (private exports only)
`total_pages`	`integer`	Total page count for the canvas (echoed for client convenience)

Example usage

Provide exactly one of canvas_id or url per call:

# Export as PNG for design-to-code (default)
export_canvas(url="https://layovelle.com/s/abc123")

# Export directly from a canvas_id returned by start_design_task
export_canvas(canvas_id="550e8400-e29b-41d4-a716-446655440000", format="pdf")

# Export a specific page as JPEG
export_canvas(url="https://layovelle.com/s/abc123", format="jpeg", page_number=2)

# Export all pages as a PDF
export_canvas(url="https://layovelle.com/s/abc123", format="pdf")

# Export as a PowerPoint file
export_canvas(url="https://layovelle.com/s/abc123", format="pptx")

Notes

Pass exactly one of canvas_id or url
For design-generation workflows, prefer canvas_id from start_design_task / get_task_status
Export-before-ready and temporary readiness-check failures are normal retryable MCP states, not tool failures
The signed URL expires after 7 days
In production, the URL is served from the signed assets-cdn.moda.app CDN; raw storage.googleapis.com links are a fallback and not the canonical host
Page exports are cached in Redis for 24 hours per (canvas, page, delivered format, pixel_ratio, flatten) combination. Delivered, not requested: a multi-page PNG or JPEG request is bundled into a .zip, so those two resolve to the same cache slot. With task_id omitted the cache key includes the canvas’s scene version, so any content edit auto-invalidates; a task_id-scoped export is keyed on the task instead and stays valid across edits (see the task_id parameter above). Re-exporting an unchanged page returns in milliseconds.
For document formats (pdf, pptx), all pages are included by default unless page_number is specified
For PNG/JPEG: pass a specific page_number to get a single image; omit it to get every page — single-page canvases return a raw image, multi-page canvases return a .zip of page-1.png/page-2.png/… (format: "zip" in the response)
When a design task auto-exports via export_on_complete, the artifact lives at result.export on the task and is keyed identically to a manual export_canvas call. A follow-up export_canvas for the same canvas with no edits hits the cache instead of re-rendering.
Screenshots are rendered server-side using a headless browser

get_export_status

Poll the status of an asynchronous export started by export_canvas. Use when export_canvas returned status='in_progress' (large multi-page exports that exceed the synchronous wait budget).

Parameters

Parameter	Type	Required	Description
`task_id`	`string`	Yes	Export task ID returned by `export_canvas` when `status='in_progress'` — bare UUID or prefixed wire form.

Returns

While running:

{
  "status": "running",
  "is_terminal": false,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "canvas_id": "660e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://layovelle.com/canvas/660e8400-e29b-41d4-a716-446655440000",
  "format": "pdf",
  "total_pages": 23,
  "retry_after_seconds": 5
}

On completion:

{
  "status": "completed",
  "is_terminal": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "canvas_id": "660e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://layovelle.com/canvas/660e8400-e29b-41d4-a716-446655440000",
  "format": "pdf",
  "url": "https://assets-cdn.moda.app/exports/abc123.pdf",
  "total_pages": 23
}

On failure:

{
  "status": "failed",
  "is_terminal": true,
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": "Failed to export document: ...",
  "format": "pdf"
}

Field	Type	Description
`status`	`string`	`queued`, `running`, `completed`, or `failed`.
`is_terminal`	`boolean`	`true` once the task has reached `completed` or `failed`.
`task_id`	`string`	The export task ID being polled.
`url`	`string`	Signed download URL once `status='completed'`.
`error`	`string`	Failure detail when `status='failed'`.
`retry_after_seconds`	`integer`	Suggested poll cadence while `is_terminal` is `false`.

Notes

Export task records are kept for ~1 hour. After that the task ID is treated as unknown and the call returns a tool error.
Call get_export_status instead of repeatedly calling export_canvas while a known task is running — export_canvas may return the same in-progress handle, but get_export_status is the canonical poll path.

list_my_canvases

Returns a paginated list — or, with a query, a paginated keyword search — of canvases accessible to the authenticated user. Use this to browse available canvases when you don’t have a specific URL, and whenever the user should see or pick one.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Default	Description
`query`	`string`	No	`null`	Keyword to match against canvas names (fuzzy) and content (full-text). Omit to browse by recency; combines with the other filters
`limit`	`integer`	No	`6`	Number of canvases to return (max 100)
`offset`	`integer`	No	`0`	Number of canvases to skip for pagination

Returns

{
  "canvases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Website",
      "url": "https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000",
      "updated_at": "2025-03-15T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Field	Type	Description
`canvases[].id`	`string`	Canvas UUID
`canvases[].name`	`string`	Canvas name
`canvases[].url`	`string`	Direct canvas URL
`canvases[].updated_at`	`string`	Last update timestamp (ISO 8601)
`total`	`integer`	Total number of canvases
`limit`	`integer`	Page size
`offset`	`integer`	Current offset

Notes

Canvases are returned in order of most recently updated; with a query, results are ranked by relevance and then recency
Pairs with the Canvas Gallery interactive app, which renders the results as a thumbnail grid and calls this tool again from its search box and “Show more” button
Prefer this tool over search_canvases whenever the user should see or pick a canvas — pass query to hand them a pre-filtered gallery
The url field can be passed directly to other tools like get_moda_canvas
The maximum limit is 100 per request

search_canvases

Searches your canvases by name or content and returns matching results as plain JSON. Use this when you need to resolve a canvas ID for a follow-up call and don’t have the exact URL.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Default	Description
`query`	`string`	Yes	—	Search query to match against canvas names and content
`limit`	`integer`	No	`20`	Maximum number of results to return (max 100)

Returns

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Website v2",
    "url": "https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000"
  }
]

Field	Type	Description
`[].id`	`string`	Canvas UUID
`[].name`	`string`	Canvas name
`[].url`	`string`	Direct canvas URL

Notes

The search matches against canvas names and content
Results are ranked by relevance
Renders no interactive app — it’s the JSON-only counterpart to list_my_canvases, which takes the same query and renders the Canvas Gallery. Use that one when the user should see the results
The returned url can be passed directly to other tools like get_moda_canvas
The maximum limit is 100 per request

list_organizations

Returns a list of organizations and teams you belong to. Use this to discover available workspaces, then call set_context to choose which one to use.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

This tool takes no parameters.

Returns

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Acme Corp",
    "role": "admin",
    "teams": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440000",
        "name": "Design Team",
        "is_default": true
      },
      {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "name": "Marketing",
        "is_default": false
      }
    ]
  }
]

Field	Type	Description
`[].id`	`string`	Organization UUID
`[].name`	`string`	Organization name
`[].role`	`string`	Your role in the organization (admin or member)
`[].teams`	`array`	Teams you have access to within this org
`[].teams[].id`	`string`	Team UUID
`[].teams[].name`	`string`	Team name
`[].teams[].is_default`	`boolean`	Whether this is the org’s default team

Notes

Use org and team names with set_context to choose your active workspace
IDs are included but typically don’t need to be shown to users — use names in conversation instead
Organizations are sorted alphabetically by name
Only teams you have access to are included

find_brand_kits

JSON-only sibling of list_brand_kits. Same data, same parameters — the difference is presentation. find_brand_kits does not render the visual brand-kit showcase iframe, so it’s appropriate when the agent is just looking up a brand_kit_id to pass to another tool (e.g. start_design_task).

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Per the MCP Apps spec, iframe rendering is decided at tool-listing time from a tool’s _meta.ui.resourceUri. There is no per-call way to suppress rendering. So Layovelle exposes two tools sharing the same backing data:

find_brand_kits — JSON-only. Use for the agent’s own lookups, e.g. resolving a kit the user already named.
list_brand_kits — renders the visual showcase. Use when the user asked to see their kits, or must choose one for a new design.

Parameters

Identical to list_brand_kits: query, org_id, team_id, verbose, limit, offset.

Returns

Identical to list_brand_kits.

list_brand_kits

Returns brand kits for a team. Renders the visual brand-kit showcase iframe on every call (on app-aware hosts like claude.ai and Claude Desktop). Brand kits contain colors, fonts, logos, and brand guidelines that were extracted from company websites. Uses your session context (set via set_context) or defaults to your primary workspace. It is the picker the agent shows when the user must choose a kit for a new design (see start_design_task). For agent-side lookups where the iframe would take over screen space the user didn’t ask for, prefer find_brand_kits — same data, no UI.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Description
`query`	`string`	No	Case-insensitive name filter — matches the kit’s title or its company name (substring). Omit to list every kit on the team.
`org_id`	`string`	No	Organization UUID. Overrides session context for this call.
`team_id`	`string`	No	Team UUID. Overrides session context for this call.
`verbose`	`boolean`	No	Default `true`. Include full kit detail (colors, fonts, logos, brand values). Pass `false` for an id/title-only projection.
`limit`	`integer`	No	Default `10`. Caps the response so teams with many kits don’t overflow the host’s tool-result context window. Use `offset` to paginate.
`offset`	`integer`	No	Default `0`. Pagination offset; check `has_more` in the response to know when to stop.

If neither org_id nor team_id is provided, uses your session context or defaults to your primary workspace.

Returns

{
  "brand_kits": [
    {
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "title": "Acme Corp",
      "is_default": true,
      "created_at": "2025-03-15T10:30:00",
      "updated_at": "2025-03-16T14:20:00",
      "company_name": "Acme Corp",
      "company_url": "https://acme.com",
      "company_description": "Modern design tools for teams",
      "tagline": "Design at scale",
      "brand_values": ["innovation", "simplicity"],
      "brand_aesthetic": ["modern", "minimal"],
      "brand_tone_of_voice": ["professional", "friendly"],
      "default_color_mode": "light",
      "default_theme_canvas_id": "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
      "colors": [
        { "id": "clr_01HT9WK8N3M2J4A5Z6P7Q8R9TV", "color": "#2563eb", "label": "Primary", "mode": "light" },
        { "id": "clr_01HT9WK8N3M2J4A5Z6P7Q8R9TW", "color": "#111827", "label": "Text", "mode": null }
      ],
      "fonts": [{ "family": "Inter", "label": "Body", "weight": 400, "supported": true }],
      "logos": [
        {
          "group_name": "Primary Logo",
          "images": [{ "name": "logo-dark.svg", "url": "https://..." }]
        }
      ]
    }
  ],
  "team_id": "660e8400-e29b-41d4-a716-446655440000",
  "total": 12,
  "offset": 0,
  "limit": 10,
  "has_more": true
}

Field	Type	Description
`[].id`	`string`	Brand kit UUID
`[].title`	`string`	Display name for the brand kit
`[].is_default`	`boolean`	Whether this kit is the team’s default (the fallback for edits of a canvas with no kit)
`[].default_color_mode`	`string`	Preferred color mode when both light and dark palettes are present. Matches `colors[].mode` — typically `"light"` or `"dark"`, or `null` when no mode distinction exists.
`[].default_theme_canvas_id`	`string`	Prefixed `cvs_…` ID of the kit’s saved default slides theme canvas, or `null`. Set/clear it via `update_brand_kit`.
`[].colors`	`array`	Ordered brand color palette (lower index = higher primacy)
`[].colors[].id`	`string`	Unique identifier for this color entry
`[].colors[].color`	`string`	Hex color value (e.g. `"#2563eb"`)
`[].colors[].label`	`string`	Semantic role label (e.g. `"Primary"`, `"Text"`)
`[].colors[].mode`	`string`	Color palette mode: `"light"`, `"dark"`, or `null` when the color isn’t mode-specific
`[].fonts`	`array`	Brand typography entries
`[].logos`	`array`	Logo image groups

When verbose=false, each kit drops the colors, fonts, logos, brand_values, brand_aesthetic, brand_tone_of_voice, company_url, and company_description fields — useful when you only need ids/titles to pick a kit by name. brand_aesthetic is a deprecated keyword array describing the brand’s visual style. The brand’s visual aesthetic is otherwise captured internally and is not exposed through this API.

Notes

Uses your session context to determine the workspace. Call set_context to switch organizations or teams.
Default-kit-first, then created-at descending. Stable across paginated calls when no edits intervene.
The is_default kit does not settle a new design — start_design_task asks for the user’s choice (brand_kit_choice_required), however many kits the team has.
Cache: signed export URLs and signed CDN logo URLs are valid for 24h; a chat refresh that re-renders the showcase iframe within that window hits a Redis cache instead of re-signing.

create_brand_kit

Creates a brand kit by extracting brand information from a company website. Provide a URL or domain and Layovelle will extract colors, fonts, logos, and brand guidelines automatically. Uses your session context (set via set_context) or defaults to your primary workspace.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Description
`url`	`string`	Yes	Website URL or domain (e.g., `stripe.com` or `https://stripe.com`)
`org_id`	`string`	No	Organization UUID. Overrides session context for this call.
`team_id`	`string`	No	Team UUID. Overrides session context for this call.

Returns

Returns the created brand kit in the same format as list_brand_kits entries.

{
  "id": "880e8400-e29b-41d4-a716-446655440000",
  "title": "Stripe",
  "is_default": false,
  "company_name": "Stripe",
  "company_url": "https://stripe.com",
  "company_description": "Financial infrastructure for the internet",
  "default_color_mode": null,
  "colors": [
    { "id": "clr_01HT9WK8N3M2J4A5Z6P7Q8R9TV", "color": "#635bff", "label": "Primary", "mode": null },
    { "id": "clr_01HT9WK8N3M2J4A5Z6P7Q8R9TW", "color": "#0a2540", "label": "Dark", "mode": null }
  ],
  "fonts": [{ "family": "Inter", "label": "Body", "weight": 400, "supported": true }],
  "logos": []
}

Notes

Extraction typically takes 10–30 seconds depending on the website
Uses Firecrawl to scrape the website and extract brand data
If the brand has been extracted before, a cached result is used for faster response
The first brand kit created for a team is automatically set as the default

update_brand_kit

Updates an existing brand kit. Pass only the fields you want to change — all other fields remain unchanged.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Description
`brand_kit_id`	`string`	Yes	ID of the brand kit to update
`title`	`string`	No	Display title for the brand kit
`colors`	`array`	No	Array of `{ color, label?, id?, mode? }` objects (replaces all colors). `color` is required (hex string). `id` is assigned automatically if omitted.
`fonts`	`array`	No	Array of `{ family, label, weight }` objects
`company_name`	`string`	No	Company name
`company_description`	`string`	No	Company description
`tagline`	`string`	No	Brand tagline
`brand_values`	`string[]`	No	List of brand values
`brand_aesthetic`	`string[]`	No	Deprecated list of aesthetic descriptors. The free-text `aesthetic` is derived during brand-kit population and is not settable here.
`brand_tone_of_voice`	`string[]`	No	List of tone descriptors
`default_theme_canvas_id`	`string`	No	Canvas ID (`cvs_…` or bare UUID) of a `template_type='theme'` canvas on the same team to set as the kit’s default theme
`clear_default_theme_canvas_id`	`boolean`	No	Set `true` to clear the saved default theme. Mutually exclusive with `default_theme_canvas_id`

Setting default_theme_canvas_id to a non-theme canvas — or one on a different team — fails with invalid_theme_canvas.

Returns

Returns the updated brand kit in the same format as list_brand_kits entries.

Notes

Pass only the fields you want to change — omitted fields are not modified
When updating colors or fonts, the entire array is replaced (not merged)
You must have access to the team that owns the brand kit

set_default_brand_kit

Marks a brand kit as the team’s default and clears the default flag on the previously-default kit. The default fills in when an edited canvas has no kit of its own; it does not stand in for the user’s choice on a new design.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Destructive — affects every team member. This tool clears the default flag on whichever kit was previously default. Only call it when the user explicitly asks to change their team default brand kit. For session-only changes (no team-wide impact), use set_session_brand_kit instead — that’s what the Brand Kit Showcase iframe’s “Use for this session” button now calls.

Parameters

Parameter	Type	Required	Description
`brand_kit_id`	`string`	Yes	Brand kit UUID — bare UUID or prefixed `bk_` wire form is accepted

Returns

Returns the team’s brand kits in the same shape as list_brand_kits, with the new default first. Use this to rerender any UI that depends on default-kit state without an additional round-trip.

Example usage

# Promote a kit to default after the user explicitly asks
set_default_brand_kit(brand_kit_id="880e8400-e29b-41d4-a716-446655440000")

Notes

Idempotent: setting the already-default kit is a no-op
Only the user’s currently-active team is affected
Pairs with the Brand Kit Showcase interactive app, which calls this tool from its “Set as default” button

list_brand_kit_images

Returns every image attached to a brand kit — both logos and design references — in newest-insertion order. Useful when reconciling an existing brand kit before adding new images, since blindly calling add_brand_kit_image would create duplicates.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Description
`brand_kit_id`	`string`	Yes	Brand kit UUID — bare UUID or prefixed `bk_` wire form is accepted

Returns

{
  "brand_kit_id": "bk_abc123",
  "images": [
    {
      "id": "bki_550e8400e29b41d4a716446655440000",
      "role": "logo",
      "file_id": "file_660e8400e29b41d4a716446655440000",
      "url": "https://assets-cdn.moda.app/brand-kits/.../logo-dark.svg",
      "name": "logo-dark.svg",
      "group_id": "770e8400-e29b-41d4-a716-446655440000",
      "group_name": "Primary Logo"
    },
    {
      "id": "bki_aa0e8400e29b41d4a716446655440000",
      "role": "reference",
      "file_id": "file_bb0e8400e29b41d4a716446655440000",
      "url": "https://assets-cdn.moda.app/brand-kits/.../homepage-hero.png",
      "name": "homepage-hero.png",
      "group_id": "cc0e8400-e29b-41d4-a716-446655440000",
      "group_name": "Website screenshots"
    }
  ]
}

Field	Type	Description
`brand_kit_id`	`string`	Echoed back for round-tripping
`images[].id`	`string`	Image-row ID (prefixed `bki_`) — pass to `remove_brand_kit_image`
`images[].role`	`string`	`"logo"` or `"reference"`
`images[].file_id`	`string`	Underlying file ID (prefixed `file_`)
`images[].url`	`string`	Direct URL to the image (CDN-served)
`images[].name`	`string`	Original filename, if known
`images[].group_id`	`string`	UUID of the containing logo group / reference group
`images[].group_name`	`string`	Display name of the group (e.g., `"Primary Logo"`, `"Photography"`)

Example usage

list_brand_kit_images(brand_kit_id="880e8400-e29b-41d4-a716-446655440000")

Notes

Pairs with the Brand Kit Image Gallery interactive app, which renders the images grouped by role
The image url is served from the signed CDN; treat it as opaque

remove_brand_kit_image

Detaches an image from a brand kit by its bki_ ID. Returns the freshly re-listed images so callers can rerender from authoritative state.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Destructive. Only call this when the user explicitly asks to remove a specific image, or in response to a user action (e.g., the per-card Remove button in the Brand Kit Image Gallery iframe). The underlying file remains in storage; only the brand-kit reference is removed.

Parameters

Parameter	Type	Required	Description
`brand_kit_id`	`string`	Yes	Brand kit UUID — bare UUID or prefixed `bk_` wire form is accepted
`image_id`	`string`	Yes	Brand-kit image-row ID — bare UUID or prefixed `bki_` wire form

Returns

Returns the same payload shape as list_brand_kit_images after the removal completes, so the caller can rerender directly from the response.

Example usage

remove_brand_kit_image(
  brand_kit_id="880e8400-e29b-41d4-a716-446655440000",
  image_id="bki_550e8400e29b41d4a716446655440000",
)

Notes

The underlying file is not deleted from storage — only the brand-kit reference is removed
Pairs with the Brand Kit Image Gallery interactive app, which calls this tool from each card’s Remove button
Not idempotent: calling twice with the same image_id raises a not-found error on the second call

upload_file

Uploads a file from a URL to Layovelle’s storage. Returns a stable proxy URL that can be used as an attachment in start_design_task. Supports images, PDFs, Office documents (PowerPoint, Word, and Excel spreadsheets), CSV, plain-text/Markdown, and web-playable video (MP4, WebM, MOV).

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Description
`source_url`	`string`	Yes	Public URL of the file to download and store
`filename`	`string`	No	Filename to use. Inferred from URL if omitted.
`org_id`	`string`	No	Organization UUID. Overrides session context for this call.
`team_id`	`string`	No	Team UUID. Overrides session context for this call.

Returns

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://api.moda.app/api/v2/images/ref/550e8400-e29b-41d4-a716-446655440000?h=abc123",
  "filename": "design-reference.png",
  "mime_type": "image/png",
  "size_bytes": 245760,
  "was_duplicate": false,
  "message": "File uploaded successfully. Use the 'url' field as an attachment URL in start_design_task."
}

Field	Type	Description
`id`	`string`	Unique file identifier (UUID)
`url`	`string`	Stable proxy URL for the uploaded file
`filename`	`string`	Filename of the uploaded file
`mime_type`	`string`	MIME type of the file
`size_bytes`	`integer`	File size in bytes
`was_duplicate`	`boolean`	True if an identical file already existed
`message`	`string`	Human-readable confirmation message

Example usage

# Upload an image for use as a design reference
upload_file(source_url="https://example.com/mockup.png")

# Upload with a custom filename
upload_file(source_url="https://example.com/file.pdf", filename="brand-guidelines.pdf")

Notes

The returned url can be passed directly as an attachment URL in start_design_task
Files are deduplicated by content hash — uploading the same file twice returns the existing record
Supported types include images (PNG, JPEG, WebP, etc.), PDFs, Office documents (PowerPoint .pptx/.ppt, Word .docx/.doc, Excel .xlsx/.xls), CSV, plain text/Markdown, and web-playable video (MP4, WebM, MOV)

start_design_task

Starts an AI design task using Layovelle’s design agent. The agent creates or edits a canvas based on your prompt. Provide a canvas_id to edit an existing canvas, or omit it to create a new one. By default this tool returns immediately in milliseconds with a task handle ({task_id, canvas_id, canvas_url, status: 'queued'}). On hosts that support interactive apps (claude.ai web, Claude Desktop), the paired Design Task Progress iframe shows live progress and rendered pages, so you don’t need to block on completion. On non-interactive hosts, poll get_task_status(task_id) to track progress and detect completion. Pass wait=True to opt back into synchronous behavior — useful only for non-interactive consumers that need a single blocking call. Uses your session context (set via set_context) or defaults to your primary workspace.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Default	Description
`prompt`	`string`	Yes	—	Design instructions for the AI agent
`canvas_id`	`string`	No	—	Canvas to edit. Omit to create a new canvas. Ignored when resuming a conversation.
`canvas_name`	`string`	No	—	Name for the new canvas (only used when `canvas_id` is omitted)
`brand_kit_id`	`string`	No	—	Brand kit to apply. For a new design, pass the kit the user chose (or `skip_brand_kit=true`) — omitting it is refused with `brand_kit_choice_required`, whatever the kit count. Edits keep the canvas’s own kit.
`org_id`	`string`	No	—	Organization UUID. Overrides session context for this call.
`team_id`	`string`	No	—	Team UUID. Overrides session context for this call.
`conversation_id`	`string`	No	—	UUID of a previous conversation to resume. The agent will have full context of all prior interactions. Returned in every response — pass it back to continue.
`attachments`	`array`	No	—	List of reference files. Each item is either a URL-shape object `{url, name?, type?}` (type ∈ `"image"` / `"pdf"` / `"pptx"` / `"url"`) or a file-id-shape object `{file_id, role, label?}` where `file_id` is returned by `upload_file` and `role` ∈ `"source"` (extract content) / `"reference"` (emulate style) / `"asset"` (use directly in outputs) / `"import"` (PPTX-only — load the deck onto the canvas as editable slides, then design against it; any other file type is rejected — and because the deck sets its own page size, an `import` is rejected alongside any format field other than `format_category="slides"`). Prefer the file-id form for uploaded files — it surfaces role metadata to the agent.
`reference_canvas_ids`	`string[]`	No	—	List of canvas UUIDs to use as design inspiration. The agent can see these designs and reference their style, layout, or content.
`format_category`	`string`	No	—	Format category — recommended for new designs. One of `"slides"` (presentations), `"social"` (social posts), `"carousel"` (multi-slide social), `"pdf"` (documents/reports), `"diagram"` (flowcharts/diagrams), `"ui"` (UI mockups), `"animation"` (motion graphics), `"prints"` (posters/flyers/cards), `"web-ads"` (display ads), or `"other"`. Without it, a fresh canvas resolves to `"other"` at 1080×1080 — not the format you intended.
`format_width`	`integer`	No	—	Canvas width in pixels. Common: 1920x1080 (slides), 1080x1080 (social square), 1080x1920 (social story). Rejected alongside an `import` attachment — the deck sets its own page size.
`format_height`	`integer`	No	—	Canvas height in pixels. Rejected alongside an `import` attachment — the deck sets its own page size.
`model_tier`	`string`	No	—	AI model tier: `"pro"` (best for complex tasks), `"pro-fast"` (Pro quality with faster output and higher credit usage), `"standard"`, or `"lite"` (fastest). Defaults to automatic selection.
`wait`	`boolean`	No	`false`	When `false` (default), return immediately with a task handle so callers can render the live-progress iframe or poll `get_task_status`. When `true`, block until the agent finishes and return the complete design — only needed for synchronous, non-interactive consumers.
`export_on_complete`	`object`	No	—	Auto-export preferences applied when the task finishes — the rendered file is attached to `result.export` and the cache is warmed so a follow-up `export_canvas` for the same canvas hits it instantly. Shape: `{enabled?: boolean = true, format?: "png" \| "jpeg" \| "pdf" \| "pptx", pixel_ratio?: 1..4}`. Omit to use the canvas category default (`slides`→PPTX, `pdf`→PDF, others→PNG); an `animation` canvas defaults to video, which the auto-export pipeline does not render — request a still format here to get an auto-export of one. Pass `{enabled: false}` to skip the auto-export. Multi-page PNG/JPEG bundles into a `.zip` of per-page files; `result.export.format` is `"zip"` in that case.

Returns

{
  "task_id": "990e8400-e29b-41d4-a716-446655440000",
  "canvas_id": "550e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000",
  "conversation_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "theme_canvas_id": null,
  "status": "queued",
  "message": "Design task started. Use get_task_status to check progress.",
  "retry_after_seconds": 3
}

theme_canvas_id reports the brand kit’s slides theme that was auto-applied to the new canvas — the canvas whose page layouts the agent themes from. It’s populated only when you create a fresh slides deck (format_category="slides", no canvas_id) with a brand kit that has a saved default theme; it’s null for non-slides designs, edits of existing canvases, and brand kits without a saved theme. Once get_task_status reports status: "completed", the same envelope additionally carries result.export with the auto-exported artifact:

{
  "result": {
    "canvas_id": "550e8400-e29b-41d4-a716-446655440000",
    "canvas_url": "https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000",
    "export": {
      "url": "https://assets-cdn.moda.app/exports/abc123.pptx",
      "format": "pptx",
      "status": "completed",
      "page_count": 8
    }
  }
}

Field	Type	Description
`result.export.url`	`string`	Signed download URL for the rendered file (expires after 7 days).
`result.export.format`	`string`	Delivered format — `png`, `jpeg`, `pdf`, `pptx`, or `zip` (multi-page PNG/JPEG bundle).
`result.export.status`	`string`	`completed` when the file is ready; `failed` if the auto-export couldn’t render (the design task still succeeded).
`result.export.page_count`	`integer`	Total pages in the canvas — useful for sizing UIs ahead of downloading.

Example usage

# Create a new design (returns a conversation_id)
start_design_task(prompt="Create a modern SaaS landing page with a hero section, features grid, and pricing table")

# Resume the conversation to make changes (agent remembers previous context)
start_design_task(prompt="Change the color scheme to use blues and grays", conversation_id="bb0e8400...")

# Edit an existing canvas
start_design_task(prompt="Add a footer section", canvas_id="550e8400...")

# Create slides with specific dimensions
start_design_task(prompt="Create a pitch deck", format_category="slides", format_width=1920, format_height=1080)

# Create a PDF document (report, resume, etc.)
start_design_task(prompt="Create a project report", format_category="pdf")

# Provide reference images as attachments — file-id form (recommended)
# Upload first, then reference the returned file_id with a role:
uploaded = upload_file(source_url="https://example.com/reference.png")
start_design_task(
  prompt="Recreate this design in our brand style",
  attachments=[{"file_id": uploaded["id"], "role": "reference", "label": "brand-style ref"}],
  brand_kit_id="880e8400..."
)

# Or the legacy URL form — still accepted for hosted public URLs:
start_design_task(
  prompt="Recreate this design in our brand style",
  attachments=[{"url": "https://example.com/reference.png", "type": "image"}],
  brand_kit_id="880e8400..."
)

# Mix shapes in one call — a source brief plus a reference image:
start_design_task(
  prompt="Build a pitch deck from the brief; match the reference style",
  attachments=[
    {"file_id": "file_01HT9W…", "role": "source", "label": "Q2 strategy brief"},
    {"file_id": "file_01HT9X…", "role": "reference"},
  ],
)

# Use existing canvases as design inspiration
start_design_task(
  prompt="Create a similar landing page",
  reference_canvas_ids=["550e8400...", "660e8400..."]
)

# Canonical MCP flow: start -> poll -> read result.export (no second render)
task = start_design_task(prompt="Create a sales deck", format_category="slides")
status = get_task_status(task_id=task["task_id"])
while not status["can_export"] and not status["is_terminal"]:
  # Wait status["retry_after_seconds"] seconds, then poll again.
  status = get_task_status(task_id=task["task_id"])

# When the task auto-exports successfully, the rendered file rides in
# status["result"]["export"] — read it directly instead of calling
# export_canvas (the cache would hit, but result.export saves a round trip).
if status["can_export"]:
  export_info = status["result"]["export"]
  print(export_info["url"], export_info["format"])  # e.g. ".../abc.pptx", "pptx"

# Opt out of the auto-export when you don't need it:
start_design_task(prompt="Iterate on the layout", canvas_id="550e8400...", export_on_complete={"enabled": False})

# Or override the format/scale (e.g. PDF instead of the slides category default):
start_design_task(prompt="Build a deck", format_category="slides", export_on_complete={"format": "pdf", "pixel_ratio": 3})

Notes

The default wait=False returns a task handle in milliseconds. Pass wait=True only when you specifically want a single blocking call.
On iframe-aware hosts (claude.ai web, Claude Desktop), the paired Design Task Progress app polls and renders pages on its own — see Interactive Apps.
Use retry_after_seconds as the default delay before the first get_task_status(task_id) call
Keep polling until can_export == true or is_terminal == true
can_export describes the canvas, not the outcome: it becomes true for any terminal task whose canvas has renderable pages, even if the task itself failed
A new design (no canvas_id, conversation_id, or template_canvas_id) needs a brand choice — brand_kit_id, skip_brand_kit=true, or a session pin. Without one it is refused with brand_kit_choice_required — whatever the kit count, even with a team default — listing the kits so the agent can ask the user: one of them, a new kit, or none. Edits keep the canvas’s own kit
If no canvas_id is provided, a new canvas is created with the name from canvas_name or “Untitled”
Every response includes a conversation_id. Pass it back in subsequent calls so the agent has context of all previous interactions.
When resuming a conversation, the canvas_id parameter is ignored — the agent automatically operates on the conversation’s canvas
Use upload_file to upload local files first, then pass the returned file_id in an attachments item with a role (source / reference / asset / import). import is PPTX-only — it loads the deck onto the canvas as editable slides. The older URL form is still accepted but drops role metadata.
Reference canvas IDs let the agent see and draw inspiration from existing designs without modifying them
Always pass format_category when creating new designs — without it, a fresh canvas is created as a generic "other" canvas at 1080×1080 with no format skill, so a deck/post/document gets a generic layout
The auto-export attached to result.export is keyed identically to a follow-up export_canvas(canvas_id=...), so calling export_canvas afterward with default args hits the cache instead of re-rendering. Pin export_on_complete.format and export_on_complete.pixel_ratio when you need a non-default artifact — the cache match depends on the exact (format, pixel_ratio) pair.

get_task_status

Returns the status and progress of a specific design task. Use this to check on tasks started with start_design_task or remix_design.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Description
`task_id`	`string`	Yes	ID of the task to check

Returns

{
  "task_id": "990e8400-e29b-41d4-a716-446655440000",
  "canvas_id": "550e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000",
  "conversation_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "theme_canvas_id": null,
  "status": "running",
  "prompt": "Create a modern SaaS landing page...",
  "progress_percent": 45,
  "current_step": "Generating hero section",
  "is_terminal": false,
  "can_export": false,
  "retry_after_seconds": 3,
  "operations_streamed": 12,
  "created_at": "2025-03-15T10:30:00",
  "started_at": "2025-03-15T10:30:02",
  "completed_at": null,
  "error": null
}

Field	Type	Description
`task_id`	`string`	Task UUID
`canvas_id`	`string`	Canvas being edited
`canvas_url`	`string`	Direct link to the canvas
`conversation_id`	`string`	Conversation UUID. Pass to `start_design_task` to resume the conversation.
`theme_canvas_id`	`string`	Brand-kit slides theme attached to the canvas, or `null` when unthemed.
`status`	`string`	`queued`, `running`, `cancelling`, `completed`, `failed`, `cancelled`, `dead_letter`, `canvas_deleted`, or `insufficient_credits`
`prompt`	`string`	The original prompt, in full
`progress_percent`	`integer`	Estimated progress (0-100), if available
`current_step`	`string`	Description of what the agent is currently doing
`is_terminal`	`boolean`	`true` when the task is finished and polling can stop
`can_export`	`boolean`	`true` when the task is terminal and the canvas has exportable content, so `export_canvas` can be called — set even for failed or dead-lettered tasks
`retry_after_seconds`	`integer`	Suggested delay before polling again when the task is still in progress
`operations_streamed`	`integer`	Number of canvas operations applied so far
`created_at`	`string`	Job creation timestamp (ISO 8601)
`started_at`	`string`	When the agent started working (ISO 8601)
`completed_at`	`string`	When the task finished (ISO 8601), or `null`
`error`	`string`	Error message if the task failed, or `null`

Notes

Use this after start_design_task to poll for progress
Poll again after retry_after_seconds while is_terminal == false
On status="completed", the response carries a result.export block ({url, format, status, page_count}) with the auto-exported design — read it directly instead of calling export_canvas for the same canvas. If the auto-export was disabled via export_on_complete: {enabled: false}, or skipped because the resolved format is a video (an animation canvas with no explicit export_on_complete.format), result.export is absent.
Failed or cancelled tasks are terminal and still set can_export when the canvas has renderable pages — if can_export is true, export the design rather than regenerating it
The prompt field carries the user’s original prompt in full (the task-progress iframe surfaces it verbatim)

list_tasks

Returns a list of recent design tasks. Use this to see what design tasks have been run recently, optionally filtered by canvas or status.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`string`	No	—	Filter tasks to a specific canvas
`status`	`string`	No	—	Filter by status (`queued`, `running`, `cancelling`, `completed`, `failed`, `cancelled`, `dead_letter`, `canvas_deleted`, `insufficient_credits`)
`limit`	`integer`	No	`10`	Number of tasks to return (max 50)

Returns

{
  "tasks": [
    {
      "task_id": "990e8400-e29b-41d4-a716-446655440000",
      "canvas_id": "550e8400-e29b-41d4-a716-446655440000",
      "canvas_url": "https://layovelle.com/canvas/550e8400-e29b-41d4-a716-446655440000",
      "conversation_id": "bb0e8400-e29b-41d4-a716-446655440000",
      "theme_canvas_id": null,
      "status": "completed",
      "prompt": "Create a modern SaaS landing page...",
      "progress_percent": 100,
      "current_step": null,
      "operations_streamed": 42,
      "created_at": "2025-03-15T10:30:00",
      "started_at": "2025-03-15T10:30:02",
      "completed_at": "2025-03-15T10:32:15",
      "error": null
    }
  ]
}

Notes

Tasks are returned in order of most recently created
The maximum limit is 50 per request
Only tasks for canvases you have access to are returned

remix_design

Duplicates an existing canvas and optionally starts a design task on the copy. Use this to create variations of existing designs without modifying the original. When a prompt is provided, the call blocks by default (wait=true, unlike start_design_task) until the agent finishes and returns the completed remix — pass wait=false to get a task handle immediately and poll get_task_status the same way as start_design_task. Uses your session context (set via set_context) or defaults to your primary workspace.

This tool requires authentication via the remote MCP server at mcp.moda.app. It is not available when using the local stdio server.

Parameters

Parameter	Type	Required	Default	Description
`canvas_id`	`string`	Yes	—	Canvas to duplicate
`prompt`	`string`	No	—	Design instructions to apply to the copy. Omit for a plain duplicate.
`new_name`	`string`	No	—	Name for the new canvas. Defaults to `"Remix of <original name>"`.
`wait`	`boolean`	No	`true`	When `true` (default) and a `prompt` is supplied, block until the agent finishes and return the completed remix. Pass `false` to get a task handle immediately.
`brand_kit_id`	`string`	No	—	Brand kit to apply (only used when `prompt` is provided)
`org_id`	`string`	No	—	Organization UUID. Overrides session context for this call.
`team_id`	`string`	No	—	Team UUID. Overrides session context for this call.

Returns

Without a prompt (plain duplicate):

{
  "canvas_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://layovelle.com/canvas/aa0e8400-e29b-41d4-a716-446655440000",
  "canvas_name": "Remix of Marketing Website",
  "source_canvas_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Canvas duplicated successfully."
}

With a prompt and wait=false (duplicate + backgrounded design task):

{
  "canvas_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://layovelle.com/canvas/aa0e8400-e29b-41d4-a716-446655440000",
  "canvas_name": "Remix of Marketing Website",
  "source_canvas_id": "550e8400-e29b-41d4-a716-446655440000",
  "task_id": "990e8400-e29b-41d4-a716-446655440000",
  "task_status": "queued",
  "message": "Design task started. Use get_task_status to check progress.",
  "retry_after_seconds": 3
}

Example usage

# Plain duplicate
remix_design(canvas_id="550e8400...")

# Duplicate and restyle
remix_design(canvas_id="550e8400...", prompt="Change the color scheme to dark mode")

# Duplicate with new branding
remix_design(canvas_id="550e8400...", prompt="Apply our new brand", brand_kit_id="880e8400...")

Notes

The original canvas is never modified — all changes are applied to the copy
When a prompt is provided, a design task is started on the duplicate; with the default wait=true the call blocks until the task finishes — pass wait=false to return immediately with a task handle
Poll get_task_status(task_id) until can_export == true or the task reaches a terminal failure state, same as start_design_task

Websites

Layovelle websites are HTML projects you can draft and manage, then publish from the Layovelle editor to a public *.layovelle.com URL. These MCP tools let your agent draft, inspect, and update websites in Layovelle — available to every authenticated MCP user. Publishing the resulting draft is opt-in: create_website_from_upload and update_website_from_upload both accept a publish flag that defaults to false. Publishing runs through Layovelle’s server-side publish gate (content screening plus publish-rate, live-site, and new-account quotas); when the gate blocks a publish the draft is still saved and the response comes back with published_url: null. The user can publish from the editor once any blocking gate condition clears — the editor runs through the same gate. HTML payloads are uploaded out-of-band (presigned URL → PUT bytes → call the tool with the returned storage_key) so large HTML documents — especially ones with inlined base64 images — don’t have to pass through MCP tool args. Inline data: images are extracted to Layovelle Files automatically so the published artifact stays small.

Every website tool requires authentication via the remote MCP server at mcp.moda.app. The local stdio server does not expose them.

list_my_websites

Lists the websites visible to the caller in the active team, newest-updated first. Scoped to the team in your session context — call set_context first if you belong to multiple teams.

Parameters

Parameter	Type	Required	Description
`limit`	`integer`	No	Page size (default 20, clamped to 100 server-side).
`offset`	`integer`	No	Pagination offset, 0-indexed.

Returns

{
  "websites": [
    {
      "id": "bb0e8400-e29b-41d4-a716-446655440000",
      "title": "Launch Announcement",
      "url": "https://launch-announcement.layovelle.com",
      "share_state": "public",
      "comments_enabled": true,
      "recent_comments_count": 3,
      "updated_at": "2026-05-26T17:42:11Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0,
  "has_more": false
}

url is null for unpublished drafts.

get_website

Fetches the full agent-facing projection of one website — the source HTML for the home page, title, share state, comments toggle, editor URL, and (if published) the live *.layovelle.com URL. Use this before calling update_website_from_upload so the agent has the current source as a base.

Parameters

Parameter	Type	Required	Description
`website_id`	`string`	Yes	ID of the website to fetch.

Returns

{
  "website_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "title": "Launch Announcement",
  "html": "<!doctype html><html>…</html>",
  "editor_url": "https://layovelle.com/website/bb0e8400-e29b-41d4-a716-446655440000?source=agent",
  "published_url": "https://launch-announcement.layovelle.com",
  "url": "https://launch-announcement.layovelle.com",
  "share_state": "public",
  "comments_enabled": true,
  "recent_comments_summary": []
}

published_url and url are both null for unpublished drafts. url is a deprecated alias kept for backward compatibility — prefer published_url in new code.

create_website_from_upload

Creates a new Layovelle website from an HTML file. The HTML is uploaded out-of-band first so large documents (especially ones with inlined base64 images) don’t have to pass through MCP args. Required upload sequence:

create_upload_url(filename="site.html", mime_type="text/html") → returns {upload_url, storage_key}.
PUT the HTML bytes to upload_url with header Content-Type: text/html.
Call create_website_from_upload(storage_key=…) with the storage_key from step 1.

Server-side, Layovelle extracts every inline data:image/… URI to a CDN-hosted Layovelle File, rewrites the HTML to reference the proxy URL, then creates the website row. Sites default to category='html-document', share_state='unlisted', and comments_enabled=true.

Parameters

Parameter	Type	Required	Description
`storage_key`	`string`	Yes	The `storage_key` from `create_upload_url`, after you PUT the HTML bytes to its `upload_url`. Not the `upload_url` itself, not a filename.
`title`	`string`	No	Display title. Omit to let Layovelle auto-generate a title from the page content.
`publish`	`boolean`	No	When `true`, also publish to a slugified `*.layovelle.com` URL. Defaults to `false` (draft only). Subject to the server-side publish gate (content screening and publish quotas); if the gate blocks the publish the draft is still saved and `published_url` comes back `null`.
`category`	`string`	No	Website category. Defaults to `html-document` for uploaded HTML documents. Valid values are `html-document`, `landing-page`, `email`, and `other`.

Returns

{
  "website_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "editor_url": "https://layovelle.com/website/bb0e8400-e29b-41d4-a716-446655440000?source=agent",
  "published_url": "https://launch-announcement.layovelle.com",
  "share_state": "unlisted",
  "comments_enabled": true,
  "extracted_image_count": 4,
  "skipped_inline_asset_count": 0
}

editor_url is always present — give this link to the user. The ?source=agent marker is a presentation hint the app consumes when the link opens; pass the URL through unchanged.
published_url is the live *.layovelle.com URL when publish=true succeeded; null for drafts. Do not fabricate a *.layovelle.com URL from the website_id.

update_website_from_upload

Replace the HTML and/or title of an existing website. The website_id is preserved, existing comments stay anchored via a reconciliation pass over the new DOM, and inline data: images in the uploaded HTML are extracted to Layovelle Files (same pipeline as create_website_from_upload). Same upload sequence as create_website_from_upload — omit storage_key to keep the current HTML and only rename via title.

Parameters

Parameter	Type	Required	Description
`website_id`	`string`	Yes	The website’s ID.
`storage_key`	`string`	No	`storage_key` from `create_upload_url` after you PUT the new HTML bytes. Omit to keep the current HTML and only change the title.
`title`	`string`	No	New display title. Omit to keep the current title.
`publish`	`boolean`	No	When `true`, republish so the live URL reflects the new content. Defaults to `false` (draft update). Subject to the same server-side publish gate as `create_website_from_upload`.

Supply at least one of storage_key or title — a call with neither is rejected.

Returns

{
  "website_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "editor_url": "https://layovelle.com/website/bb0e8400-e29b-41d4-a716-446655440000?source=agent",
  "published_url": "https://launch-announcement.layovelle.com",
  "updated_at": "2026-05-26T17:42:11Z",
  "extracted_image_count": 4,
  "skipped_inline_asset_count": 0
}

published_url is null when publish=false — the live URL keeps serving the previously-published version until the user republishes from the editor.

Tools Reference

​Session context

​URL formats

​set_context

​Parameters

​Returns

​Example usage

​Notes

​get_context

​Parameters

​Returns

​get_moda_bootstrap

​Parameters

​Returns

​Notes

​set_session_brand_kit

​Parameters

​Returns

​Notes

​get_moda_canvas

​Parameters

​Returns

​Semantic tags

​Example usage

​Notes

​get_moda_canvas_tokens

​Parameters

​Returns

​Example usage

​Notes

​list_moda_canvas_pages

​Parameters

​Returns

​Notes

​export_canvas

​Parameters

​Format guide

​Returns

​Example usage

​Notes

​get_export_status

​Parameters

​Returns

​Notes

​list_my_canvases

​Parameters

​Returns

​Notes

​search_canvases

​Parameters

​Returns

​Notes

​list_organizations

​Parameters

​Returns

​Notes

​find_brand_kits

​Parameters

​Returns

​list_brand_kits

​Parameters

​Returns

​Notes

​create_brand_kit

​Parameters

​Returns

​Notes

​update_brand_kit

​Parameters

​Returns

​Notes

​set_default_brand_kit

​Parameters

​Returns

​Example usage

​Notes

​list_brand_kit_images

​Parameters

​Returns

​Example usage

Session context

URL formats

set_context

Parameters

Returns

Example usage

Notes

get_context

Parameters

Returns

get_moda_bootstrap

Parameters

Returns

Notes

set_session_brand_kit

Parameters

Returns

Notes

get_moda_canvas

Parameters

Returns

Semantic tags

Example usage

Notes

get_moda_canvas_tokens

Parameters

Returns

Example usage

Notes

list_moda_canvas_pages

Parameters

Returns

Notes

export_canvas

Parameters

Format guide

Returns

Example usage

Notes

get_export_status

Parameters

Returns

Notes

list_my_canvases

Parameters

Returns

Notes

search_canvases

Parameters

Returns

Notes

list_organizations

Parameters

Returns

Notes

find_brand_kits

Parameters

Returns

list_brand_kits

Parameters

Returns

Notes

create_brand_kit

Parameters

Returns

Notes

update_brand_kit

Parameters

Returns

Notes

set_default_brand_kit

Parameters

Returns

Example usage

Notes

list_brand_kit_images

Parameters

Returns

Example usage

Notes