ModaDocs

Tools Reference

Complete reference for all Moda MCP tools — parameters, return types, and usage examples.

The Moda MCP server provides seventeen 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.

ToolDescriptionAuth required
set_contextSet your active organization and teamYes
get_contextShow your current session contextYes
get_moda_designFetch semantic pseudo-HTML and design tokensPublic links: No
get_moda_design_tokensExtract design tokens onlyPublic links: No
list_moda_pagesList pages with dimensions and node countsPublic links: No
export_designExport as PNG, JPEG, PDF, or PPTXPublic links: No
list_my_canvasesBrowse your canvasesYes
search_canvasesSearch canvases by nameYes
list_organizationsList your orgs and teamsYes
list_brand_kitsList brand kits for a teamYes
create_brand_kitCreate brand kit from website URLYes
update_brand_kitUpdate brand kit colors, fonts, etc.Yes
upload_fileUpload a file from URL for attachmentsYes
start_design_taskStart an AI design taskYes
get_job_statusGet job status and progressYes
list_jobsList recent design jobsYes
remix_designDuplicate canvas + optional AI editsYes

Session context

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

  1. Call list_organizations to see your orgs and teams.
  2. Call set_context with the org name (and optionally team name).
  3. 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:

FormatExample
Share linkhttps://moda.app/s/abc123-token
Private canvas URLhttps://moda.app/canvas/550e8400-e29b-41d4-a716-446655440000
Raw share tokenabc123-token
Legacy domainhttps://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

ParameterTypeRequiredDescription
org_namestringYesName of the organization to use (case-insensitive). Use list_organizations to see options.
team_namestringNoName 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_design

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

Parameters

ParameterTypeRequiredDescription
urlstringYesModa share URL (https://moda.app/s/...), private canvas URL (https://moda.app/canvas/...), or raw share token
page_numberinteger | nullNo1-indexed page number. Omit to get all pages.

Returns

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

# Moda Design Export — Canvas Title # Source: https://moda.app/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:

TagWhen used
HeadingText with font-size >= 24px or font-weight >= 600
TextDefault text elements
ButtonRectangle with text, dark fill, and button-like dimensions
TextInputRectangle with light fill, thin border, no text
ImageElement with an image fill
AvatarSmall circular element with an image fill
CardGroup with a background rectangle and content
RowContainer with flex-direction: row
ColumnContainer with flex-direction: column
DividerLine element
Nav, Hero, FooterMatched from layer names

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

Example usage

# Fetch all pages
get_moda_design(url="https://moda.app/s/abc123")

# Fetch a specific page
get_moda_design(url="https://moda.app/s/abc123", page_number=2)

# Fetch a private canvas (requires authentication)
get_moda_design(url="https://moda.app/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_design_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

ParameterTypeRequiredDescription
urlstringYesModa share URL, private canvas URL, or raw share token
page_numberinteger | nullNo1-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
  }
}
FieldTypeDescription
variablesobjectNamed design variables defined in the canvas (colors, numbers, strings)
colorsstring[]All unique colors used in the canvas
fontsobject[]Font families with weights and inferred roles
radiistring[]All unique corner radii used
dimensionsobjectCanvas page dimensions (width and height)

Example usage

# Extract tokens for theme generation
get_moda_design_tokens(url="https://moda.app/s/abc123")

# Extract tokens from a specific page
get_moda_design_tokens(url="https://moda.app/s/abc123", page_number=1)

Notes

  • Variables defined in the Moda 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_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

ParameterTypeRequiredDescription
urlstringYesModa share URL, private canvas URL, or raw share token

Returns

{
  "canvas_name": "Marketing Website",
  "total_pages": 3,
  "pages": [
    {
      "page_number": 1,
      "name": "Hero Section",
      "width": 1440,
      "height": 900,
      "node_count": 12
    },
    {
      "page_number": 2,
      "name": "Features",
      "width": 1440,
      "height": 1200,
      "node_count": 24
    }
  ]
}
FieldTypeDescription
canvas_namestringName of the canvas
total_pagesintegerTotal number of pages
pages[].page_numberinteger1-indexed page number
pages[].namestringPage name as set in Moda
pages[].widthnumberPage width in pixels
pages[].heightnumberPage height in pixels
pages[].node_countintegerNumber of design elements on the page

Notes

  • Page numbers are 1-indexed
  • The node_count includes all visible elements on the page (shapes, text, images, groups)
  • Hidden elements are excluded from the count

export_design

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

Parameters

ParameterTypeRequiredDefaultDescription
canvas_idstringNo—Canvas UUID to export directly. Preferred after start_design_task returns a new canvas.
urlstringNo—Moda share URL, private canvas URL, or raw share token. Use this for share-link or design-to-code workflows.
formatstringNo"png"Export format: png, jpeg, pdf, or pptx
page_numberinteger | nullNonull1-indexed page number. For image formats, defaults to page 1. For documents, exports all pages.

Format guide

FormatBest for
pngDesign-to-code workflows — lossless image, ideal for visual reference
jpegSmaller file size when lossless quality isn't needed
pdfMulti-page documents, printing, sharing
pptxPowerPoint presentations, slide decks

Returns

On success:

{
  "status": "completed",
  "url": "https://storage.googleapis.com/bucket/exports/abc123.png",
  "format": "png"
}

If a design job 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://moda.app/canvas/550e8400-e29b-41d4-a716-446655440000",
  "job_id": "990e8400-e29b-41d4-a716-446655440000"
}

canvas_id, canvas_url, and job_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.

FieldTypeDescription
statusstring"completed" on success, or "not_ready" for retryable export attempts
urlstringSigned URL to the exported file (success only)
formatstringThe format that was used for the export (success only)
reasonstringRetryable not-ready reason: active_design_job or job_status_unavailable
retry_after_secondsintegerSuggested delay before retrying when status is "not_ready"
canvas_idstringCanvas UUID for the export target (private exports only)
canvas_urlstringDirect Moda link to the canvas (private exports only)
job_idstringActive design job ID (private exports only)

Example usage

Provide exactly one of canvas_id or url per call:

# Export as PNG for design-to-code (default)
export_design(url="https://moda.app/s/abc123")

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

# Export a specific page as JPEG
export_design(url="https://moda.app/s/abc123", format="jpeg", page_number=2)

# Export all pages as a PDF
export_design(url="https://moda.app/s/abc123", format="pdf")

# Export as a PowerPoint file
export_design(url="https://moda.app/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_job_status
  • Export-before-ready and temporary readiness-check failures are normal retryable MCP states, not tool failures
  • The signed URL expires after 7 days
  • For image formats (png, jpeg), only a single page is exported (defaults to page 1)
  • For document formats (pdf, pptx), all pages are included by default unless page_number is specified
  • Screenshots are rendered server-side using a headless browser

list_my_canvases

Returns a paginated list of canvases accessible to the authenticated user. Use this to browse available canvases when you don't have a specific 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

ParameterTypeRequiredDefaultDescription
limitintegerNo20Number of canvases to return (max 100)
offsetintegerNo0Number of canvases to skip for pagination

Returns

{
  "canvases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Marketing Website",
      "url": "https://moda.app/canvas/550e8400-e29b-41d4-a716-446655440000",
      "updated_at": "2025-03-15T10:30:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}
FieldTypeDescription
canvases[].idstringCanvas UUID
canvases[].namestringCanvas name
canvases[].urlstringDirect canvas URL
canvases[].updated_atstringLast update timestamp (ISO 8601)
totalintegerTotal number of canvases
limitintegerPage size
offsetintegerCurrent offset

Notes

  • Canvases are returned in order of most recently updated
  • The url field can be passed directly to other tools like get_moda_design
  • The maximum limit is 100 per request

search_canvases

Searches your canvases by name or content and returns matching results. Use this when you know what you're looking for but 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

ParameterTypeRequiredDefaultDescription
querystringYes—Search query to match against canvas names and content
limitintegerNo20Maximum number of results to return (max 100)

Returns

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Marketing Website v2",
    "url": "https://moda.app/canvas/550e8400-e29b-41d4-a716-446655440000"
  }
]
FieldTypeDescription
[].idstringCanvas UUID
[].namestringCanvas name
[].urlstringDirect canvas URL

Notes

  • The search matches against canvas names and content
  • Results are ranked by relevance
  • The returned url can be passed directly to other tools like get_moda_design
  • 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
      }
    ]
  }
]
FieldTypeDescription
[].idstringOrganization UUID
[].namestringOrganization name
[].rolestringYour role in the organization (admin or member)
[].teamsarrayTeams you have access to within this org
[].teams[].idstringTeam UUID
[].teams[].namestringTeam name
[].teams[].is_defaultbooleanWhether 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

list_brand_kits

Returns brand kits for a team. 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.

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

Parameters

ParameterTypeRequiredDescription
org_idstringNoOrganization UUID. Overrides session context for this call.
team_idstringNoTeam UUID. Overrides session context for this call.

If neither 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"],
      "colors": [
        { "color": "#2563eb", "label": "Primary" },
        { "color": "#111827", "label": "Text" }
      ],
      "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"
}

Notes

  • Uses your session context to determine the workspace. Call set_context to switch organizations or teams.
  • Brand kits are sorted by creation date (most recent first)
  • The is_default brand kit is automatically used by start_design_task when no brand_kit_id is specified

create_brand_kit

Creates a brand kit by extracting brand information from a company website. Provide a URL or domain and Moda 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

ParameterTypeRequiredDescription
urlstringYesWebsite URL or domain (e.g., stripe.com or https://stripe.com)
org_idstringNoOrganization UUID. Overrides session context for this call.
team_idstringNoTeam 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",
  "colors": [
    { "color": "#635bff", "label": "Primary" },
    { "color": "#0a2540", "label": "Dark" }
  ],
  "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

ParameterTypeRequiredDescription
brand_kit_idstringYesID of the brand kit to update
titlestringNoDisplay title for the brand kit
colorsarrayNoArray of { color, label } objects (replaces all colors)
fontsarrayNoArray of { family, label, weight } objects
company_namestringNoCompany name
company_descriptionstringNoCompany description
taglinestringNoBrand tagline
brand_valuesstring[]NoList of brand values
brand_aestheticstring[]NoList of aesthetic descriptors
brand_tone_of_voicestring[]NoList of tone descriptors

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

upload_file

Uploads a file from a URL to Moda's storage. Returns a stable proxy URL that can be used as an attachment in start_design_task. Supports images, PDFs, and PPTX files.

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

Parameters

ParameterTypeRequiredDescription
source_urlstringYesPublic URL of the file to download and store
filenamestringNoFilename to use. Inferred from URL if omitted.
org_idstringNoOrganization UUID. Overrides session context for this call.
team_idstringNoTeam 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."
}
FieldTypeDescription
idstringUnique file identifier (UUID)
urlstringStable proxy URL for the uploaded file
filenamestringFilename of the uploaded file
mime_typestringMIME type of the file
size_bytesintegerFile size in bytes
was_duplicatebooleanTrue if an identical file already existed
messagestringHuman-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, and PPTX files

start_design_task

Starts an AI design task using Moda'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. In MCP this tool is always asynchronous: it returns quickly with a job handle, then you poll get_job_status. 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

ParameterTypeRequiredDefaultDescription
promptstringYes—Design instructions for the AI agent
canvas_idstringNo—Canvas to edit. Omit to create a new canvas. Ignored when resuming a conversation.
canvas_namestringNo—Name for the new canvas (only used when canvas_id is omitted)
brand_kit_idstringNo—Brand kit to apply. Defaults to the team's default brand kit.
org_idstringNo—Organization UUID. Overrides session context for this call.
team_idstringNo—Team UUID. Overrides session context for this call.
conversation_idstringNo—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.
attachmentsarrayNo—List of reference files. Each item is an object with url (required), name (optional), and type ("image", "pdf", "pptx", or "url").
reference_canvas_idsstring[]No—List of canvas UUIDs to use as design inspiration. The agent can see these designs and reference their style, layout, or content.
format_categorystringNo—Format category — recommended for new designs. "slides" for presentations, "pdf" for documents/reports, "social" for social media posts, "diagram" for flowcharts/diagrams, "ui" for UI mockups, or "other". Without this, the agent may default to an incorrect format.
format_widthintegerNo—Canvas width in pixels. Common: 1920x1080 (slides), 1080x1080 (social square), 1080x1920 (social story).
format_heightintegerNo—Canvas height in pixels.
model_tierstringNo—AI model tier: "pro_max" (most capable), "pro", "standard", or "lite" (fastest). Defaults to automatic selection.

Returns

{
  "job_id": "990e8400-e29b-41d4-a716-446655440000",
  "canvas_id": "550e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://moda.app/canvas/550e8400-e29b-41d4-a716-446655440000",
  "conversation_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Design task started. Use get_job_status to check progress.",
  "retry_after_seconds": 3
}

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
start_design_task(
  prompt="Recreate this design in our brand style",
  attachments=[{"url": "https://example.com/reference.png", "type": "image"}],
  brand_kit_id="880e8400..."
)

# 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 -> export
job = start_design_task(prompt="Create a sales deck", format_category="slides")
status = get_job_status(job_id=job["job_id"])
while not status["can_export"] and not status["is_terminal"]:
  # Wait status["retry_after_seconds"] seconds, then poll again.
  status = get_job_status(job_id=job["job_id"])

if status["can_export"]:
  export_design(canvas_id=job["canvas_id"], format="pptx")

Notes

  • This tool is always async in MCP. It returns a job handle immediately.
  • Use retry_after_seconds as the default delay before the first get_job_status(job_id) call
  • Keep polling until can_export == true or is_terminal == true
  • can_export becomes true only after successful completion with exportable canvas data
  • If no brand_kit_id is provided, the team's default brand kit is used automatically
  • 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 URL in the attachments array
  • 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, the agent may default to slides regardless of what the user asked for

get_job_status

Returns the status and progress of a specific design job. Use this to check on jobs 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

ParameterTypeRequiredDescription
job_idstringYesID of the job to check

Returns

{
  "job_id": "990e8400-e29b-41d4-a716-446655440000",
  "canvas_id": "550e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://moda.app/canvas/550e8400-e29b-41d4-a716-446655440000",
  "conversation_id": "bb0e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "task": "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
}
FieldTypeDescription
job_idstringJob UUID
canvas_idstringCanvas being edited
canvas_urlstringDirect link to the canvas
conversation_idstringConversation UUID. Pass to start_design_task to resume the conversation.
statusstringqueued, running, completed, failed, or cancelled
taskstringThe original prompt (truncated to 200 characters)
progress_percentintegerEstimated progress (0-100), if available
current_stepstringDescription of what the agent is currently doing
is_terminalbooleantrue when the job is finished and polling can stop
can_exportbooleantrue when the job completed successfully and export_design can be called
retry_after_secondsintegerSuggested delay before polling again when the job is still in progress
operations_streamedintegerNumber of canvas operations applied so far
created_atstringJob creation timestamp (ISO 8601)
started_atstringWhen the agent started working (ISO 8601)
completed_atstringWhen the job finished (ISO 8601), or null
errorstringError message if the job failed, or null

Notes

  • Use this after start_design_task to poll for progress
  • Poll again after retry_after_seconds while is_terminal == false
  • Call export_design(canvas_id=..., format=...) once can_export == true
  • Failed or cancelled jobs are terminal, but they do not set can_export
  • The task field is truncated to 200 characters for readability

list_jobs

Returns a list of recent design jobs. 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

ParameterTypeRequiredDefaultDescription
canvas_idstringNo—Filter jobs to a specific canvas
statusstringNo—Filter by status (queued, running, completed, failed)
limitintegerNo10Number of jobs to return (max 50)

Returns

{
  "jobs": [
    {
      "job_id": "990e8400-e29b-41d4-a716-446655440000",
      "canvas_id": "550e8400-e29b-41d4-a716-446655440000",
      "canvas_url": "https://moda.app/canvas/550e8400-e29b-41d4-a716-446655440000",
      "conversation_id": "bb0e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "task": "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

  • Jobs are returned in order of most recently created
  • The maximum limit is 50 per request
  • Only jobs 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 tool returns a job handle immediately — poll get_job_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

ParameterTypeRequiredDefaultDescription
canvas_idstringYes—Canvas to duplicate
promptstringNo—Design instructions to apply to the copy. Omit for a plain duplicate.
new_namestringNo—Name for the new canvas. Defaults to "<original name> (Remix)".
brand_kit_idstringNo—Brand kit to apply (only used when prompt is provided)
org_idstringNo—Organization UUID. Overrides session context for this call.
team_idstringNo—Team UUID. Overrides session context for this call.

Returns

Without a prompt (plain duplicate):

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

With a prompt (duplicate + design task):

{
  "canvas_id": "aa0e8400-e29b-41d4-a716-446655440000",
  "canvas_url": "https://moda.app/canvas/aa0e8400-e29b-41d4-a716-446655440000",
  "canvas_name": "Marketing Website (Remix)",
  "source_canvas_id": "550e8400-e29b-41d4-a716-446655440000",
  "job_id": "990e8400-e29b-41d4-a716-446655440000",
  "job_status": "queued",
  "message": "Design task started. Use get_job_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 and the tool returns immediately with a job handle
  • Poll get_job_status(job_id) until can_export == true or the job reaches a terminal failure state, same as start_design_task

Authentication

How the Moda MCP server authenticates users via OAuth 2.1 and Clerk.

Naming Layers

How to name layers in Moda for better semantic output from the MCP server.

On this page

Session contextURL formatsset_contextParametersReturnsExample usageNotesget_contextParametersReturnsget_moda_designParametersReturnsSemantic tagsExample usageNotesget_moda_design_tokensParametersReturnsExample usageNoteslist_moda_pagesParametersReturnsNotesexport_designParametersFormat guideReturnsExample usageNoteslist_my_canvasesParametersReturnsNotessearch_canvasesParametersReturnsNoteslist_organizationsParametersReturnsNoteslist_brand_kitsParametersReturnsNotescreate_brand_kitParametersReturnsNotesupdate_brand_kitParametersReturnsNotesupload_fileParametersReturnsExample usageNotesstart_design_taskParametersReturnsExample usageNotesget_job_statusParametersReturnsNoteslist_jobsParametersReturnsNotesremix_designParametersReturnsExample usageNotes