Skip to main content

​
Workflows

There are two primary ways to use the Magic Patterns MCP tools.

Prompt-based

Delegate creative work to Magic Patterns’ AI. Send a natural language prompt and let the AI generate or update code.

Code-first

Write code directly into artifacts. Create a working branch, edit files, and publish when done.

​
Workflow A — Prompt-based

Starting from scratch: 
1. create_design(prompt, ...)         → kicks off AI generation
2. get_design_status(editorId)        → poll every 60s until isGenerating=false
With an existing design: 
1. get_editor_id_from_url(url)        → resolve a Magic Patterns URL to an editorId
2. get_design_status(editorId)        → check current state before acting
3. send_prompt(editorId, prompt)      → send prompt (returns immediately)
4. get_design_status(editorId)        → poll every 60s until isGenerating=false

​
Workflow B — Code-first

1. create_design()                    → no prompt, creates blank design instantly
2. get_design_status(editorId)        → confirm active artifact is ready
3. create_new_artifact(artifactId, name)  → create a working branch
4. read_artifact_files(artifactId, fileNames) → read existing scaffolding
5. write_artifact_files(artifactId, files) → write one or more files at once
6. publish_artifact(artifactId, editorId)  → compile + activate

​
Important Guidance

Collaborative editing: Magic Patterns is a collaborative editor — the user can make changes in the UI at any time. Always call get_design_status before starting new work to get the latest active artifact. Never assume state from a previous call is still current.
Polling: AI generation typically takes 2–10 minutes. Poll get_design_status no more frequently than every 60 seconds. Slow generation is normal — do not treat it as an error.

​
General Tools

​
list_design_systems
Tool
Lists the design systems available to the authenticated user. Returns both built-in presets (e.g. Base, Shadcn, MUI) and any custom design systems.

​
Design Tools

​
create_design
Tool
Creates a new Magic Patterns design. This is the starting point for both workflows.
  • With prompt: Kicks off AI generation (long-running, 2–10 minutes). Poll get_design_status every 60s.
  • Without prompt: Creates a blank design with scaffold files (App.tsx, index.tsx, index.css, tailwind.config.js). Returns immediately.
  • With templateId: Forks an existing design first, then optionally applies the prompt to the fork.
This tool requires credits when used with a prompt.
​
get_editor_id_from_url
Tool
Resolves a Magic Patterns URL to an editor ID.
​
get_design_status
Tool
Gets the current status of a design: whether AI generation is active, the active artifact ID, and available files.Always call this before starting new work on an existing design — the user may have changed state since you last checked. Also used to poll for completion after create_design (with prompt) or send_prompt.
When isGenerating=true, wait at least 60 seconds before polling again. Generation can take up to 10 minutes.
​
send_prompt
Tool
Sends a natural language prompt to the Magic Patterns AI for an existing design. Returns immediately with a request ID. The generation runs in the background.
Check get_design_status first to ensure isGenerating=false before sending a prompt.
Generation typically takes 2–10 minutes. Poll get_design_status every 60 seconds until isGenerating=false. This tool requires credits.
​
read_recent_message_history
Tool
Reads the recent chat item history for a design. Returns the last 10 items (user prompts, AI responses, artifact versions, edits). Use skip to paginate backwards.Code contents are omitted to keep the response concise — use read_artifact_files to read full file contents.
​
list_version_history
Tool
Lists the artifact version history for a design. Returns the most recent 20 versions.
​
publish_artifact
Tool
Compiles an artifact’s source files and sets it as the active artifact for the design. This is the final step in the code-first workflow.
  1. Compiles all source files (bundling for preview)
  2. Sets the artifact as active (appears in editor and preview)
  3. Adds a version entry to the design timeline

​
Artifact Tools

​
get_artifact
Tool
Gets the active artifact for a design, including its ID and list of files.Always call this (or get_design_status) to get the latest active artifact — do not rely on a previously cached artifact ID.
​
create_new_artifact
Tool
Creates a new artifact by cloning an existing one. The new artifact becomes the active artifact.
Call this before making file changes with write_artifact_files so the user can revert to the previous artifact if needed. Always call get_design_status or get_artifact first to get the current active artifact ID.
​
read_artifact_files
Tool
Reads the contents of one or more files from an artifact.
Always read files before making changes with write_artifact_files so you understand the current state.
​
write_artifact_files
Tool
Creates or overwrites one or more files in an artifact. If a file exists, it is replaced. If it doesn’t exist, it is created.
This only saves source files — it does not compile or publish. Call publish_artifact after finishing all file changes.

​
Video Walkthrough

Getting existing code from your codebase into Magic Patterns: