Documentation Index

Fetch the complete documentation index at: https://docs.moda.app/llms.txt

Use this file to discover all available pages before exploring further.

​

Moda MCP — tools reference

The Moda MCP server exposes 25+ public tools. This is a compressed reference — the authoritative catalog lives at docs.moda.app/mcp/tools.

​

Session

​

whoami

Call this first on any new conversation. Single-payload identity + active workspace + entitlements. Returns user (name/email), session (org/team/brand_kit ids+names), org_count, team_default_brand_kit, brand_kit_count, plan, and concurrency_cap. No parameters. Use the response to skip downstream lookups when defaults are unambiguous: org_count == 1 → no multi-org disambiguation needed; brand_kit_count == 1 → use that kit without further listing; concurrency_cap → the bulk fan-out window for this plan.

​

set_context

Set the active organization and team for the session. Persists 24 hours across reconnects. Clears any session brand-kit preference (kits are team-scoped).

​

get_context

Show the current session context — active org, team, and (if set) session brand kit. No parameters.

​

set_session_brand_kit

Pin a brand kit for this session without changing the team default. Applies to subsequent start_design_task / remix_design calls that omit brand_kit_id. Pass null/empty to clear.

​

list_organizations

List orgs + teams the user belongs to. No parameters. Use names (not IDs) in user-facing messages.

​

Canvas read + design-to-code

​

get_moda_canvas

Fetch a canvas as semantic pseudo-HTML with CSS properties + design tokens. The primary design-to-code tool.

​

get_moda_canvas_tokens

Return only the design tokens (colors, fonts, variables, radii) as structured JSON. Use when generating theme files without the full layout.

​

list_moda_canvas_pages

List pages in a multi-page canvas with dimensions + node counts. Call this before get_moda_canvas on multi-page designs to plan per-page fetches.

​

list_my_canvases

Paginated list of canvases the user has access to. Ordered by most recently updated.

​

search_canvases

Search canvases by name / content. Use when the user says “find my deck from March” or “my Q1 social ad.”

​

Brand kits

​

find_brand_kits

JSON-only — use this when the agent needs to pick a brand_kit_id for another tool call (e.g. start_design_task). Same data as list_brand_kits but does not render the visual showcase iframe, so it doesn’t take over the screen on tool-call lookups. Reads from session context unless overridden.

​

list_brand_kits

Renders the visual showcase iframe on every call (per the MCP Apps spec, iframe rendering is decided at tool-listing time and can’t be suppressed per-call). Use only when the user has explicitly asked to see or browse their brand kits. For agent-side lookups, prefer find_brand_kits.

​

create_brand_kit

Extract brand data (colors, fonts, logos, tone) from a company website URL. Takes 10–30s. First kit per team becomes the default automatically.

​

update_brand_kit

Partial update. Pass only the fields you want to change. When updating colors or fonts, the entire array is replaced (not merged).

​

set_default_brand_kit

Mark a brand kit as the team’s default — destructive, persists for every member. Only call when the user explicitly asks to change the team default. For session-only changes, use set_session_brand_kit instead (that’s also what the showcase iframe’s “Use for this session” button calls). Idempotent. Single parameter: brand_kit_id.

​

delete_brand_kit

Soft-delete a brand kit. Destructive — only call when the user explicitly names the kit to delete; never as part of a “cleanup” or bulk action the user didn’t request.

​

list_brand_kit_images

List all images attached to a brand kit (logos + references) in newest-first order. Useful before add_brand_kit_image to avoid duplicates.

​

add_brand_kit_image

Attach an uploaded file_id to a brand kit with a role. Roles: "logo" (used downstream in designs), "reference" (style hint to the agent; default if role is omitted), "asset" (includable in designs). Note: this role enum is distinct from the attachment role enum used by start_design_task (source / reference / asset) — both share reference and asset but logo is brand-kit-only.

​

remove_brand_kit_image

Detach an image from a brand kit by its bki_ ID. Underlying file stays in storage; only the kit reference is removed. Destructive — only call on explicit user request.

​

Uploads

​

upload_file

Upload a file from a public URL into Moda’s storage. Returns a stable file_id + proxy URL for use as an attachment. Content-hash deduplication — uploading the same file twice returns the existing record (was_duplicate: true). Supported: PNG, JPEG, WebP, PDF, PPTX.

​

create_upload_url

Step 1 of the two-step local-file upload. Returns an upload_url (on the Moda MCP host — mcp.moda.app, not a Google Cloud Storage URL) plus a storage_key. PUT the file bytes to upload_url out-of-band (e.g. curl -X PUT --data-binary @file.png -H 'Content-Type: image/png' <upload_url>), then call register_uploaded_file. Use this path when the file is on disk and not already at a public URL. Because the PUT targets the same host as the MCP connector, sandboxed clients with a network egress allow-list don’t need an extra rule.

​

register_uploaded_file

Step 2 of the two-step local-file upload. Call after PUTing bytes to the URL from create_upload_url. Returns the same {id, url, ...} shape as upload_file — pass the file_id to add_brand_kit_image or start_design_task attachments.

​

Design tasks

​

start_design_task

Always async. Creates or edits a canvas based on the prompt. Returns a task handle immediately; poll get_task_status. Key parameters (full list in the docs): Slide count for slides decks goes in the prompt text (“a 10-slide deck”). There is no number_of_slides MCP parameter — the REST API exposes one, but the MCP server does not. Return fields: task_id, canvas_id, canvas_url, conversation_id, status, retry_after_seconds.

​

get_task_status

Poll task progress. Returns task_id, canvas_id, canvas_url, conversation_id, status, progress_percent, current_step, is_terminal, can_export, retry_after_seconds, operations_streamed, created_at, started_at, completed_at, error. Statuses: queued, running, completed, failed, cancelled, dead_letter. Stop polling when is_terminal == true. Call export_canvas only when can_export == true.

​

list_tasks

List recent design tasks. Filter by canvas_id, status, limit (max 50). Use this instead of fanning out one get_task_status per task when polling >3 tasks at once.

​

cancel_task

Cancel a running or queued design task. Returns the updated task envelope. No-op on already-terminal tasks. Use when the user changes their mind on an in-flight task or when a bulk batch needs to abort early.

​

remix_design

Duplicate a canvas; optionally start a design task on the copy. Original is never modified.

​

Export

​

export_canvas

Export a canvas as PNG, JPEG, PDF, or PPTX. Pass exactly one of canvas_id or url. Returns {status: "completed", url, format} on success, or a structured {status: "not_ready", reason, retry_after_seconds, ...} when a design task is still active on the canvas. Signed URL expires after 7 days. wait defaults to true (block up to ~20s for completion). For large multi-page PDFs or PPTX renders that may exceed the synchronous budget, the call returns {status: "in_progress", task_id, ...} instead — poll with get_export_status for the final URL.

​

get_export_status

Poll an async export started by export_canvas when it returned status="in_progress". Same shape as get_task_status: drive control flow off is_terminal. While running, retry after retry_after_seconds; on completion, url is set; on failure, error is set. Export task records are kept for ~1 hour.

​

Behavioral gotchas

The silent-fail / surprising-behavior set (format defaults, wait asymmetry, concurrency caps, not_ready semantics, brand-kit auto-apply, attachment roles, etc.) is consolidated in gotchas.md. Read it before any non-trivial flow.

​

Upstream

Canonical catalog with parameter-by-parameter detail and examples: docs.moda.app/mcp/tools.