> ## Documentation Index > Fetch the complete documentation index at: https://magicpatterns.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP Tools & Workflows > Tools available from the Magic Patterns MCP server and how to use them ## Workflows There are three primary ways to use the Magic Patterns MCP tools. Delegate creative work to Magic Patterns' AI. Send a natural language prompt and let the AI generate or update code. Write code directly into artifacts. Create a working branch, edit files, and publish when done. Build a reusable design system by writing components, styling, and rules directly, then publish versioned releases. ### 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 ``` ### Workflow C — Design-system authoring Author a reusable design system (components, styling, and rules) by writing files directly. **You** write the code here — Magic Patterns does not generate it for you. Load the `design_system_authoring_guide` prompt first for the full file contract. ``` 1. list_design_systems() → find an existing design system ID, or… 2. create_design_system(name) → create a new blank design system 3. get_design_system(designSystemId) → resolve active artifact + file list (always first) 4. read_design_system_files(designSystemId, fileNames) → read existing files before editing 5. write_design_system_files(designSystemId, files, baseArtifactId) → save files (permissive) 6. publish_design_system(designSystemId) → publish an immutable version (strict) ``` *** ## 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. **Design systems — write vs. publish:** `write_design_system_files` is *permissive* — it saves your files and returns `validationErrors` without blocking, so you can build incrementally. `publish_design_system` is *strict* — it refuses while any validation errors remain. Clear every `validationErrors` entry before publishing. Design systems are also collaborative: always call `get_design_system` first and pass its `artifactId` as `baseArtifactId` on writes so concurrent edits are detected (a 409 means re-read and retry). *** ## General Tools Lists the design systems available to the authenticated user. Returns both built-in presets (e.g. Base, Shadcn, MUI) and any custom design systems. This tool takes no parameters. Array of design systems, each with: * `id` — unique design system ID (pass to `create_design`) * `name` — human-readable name * `isReserved` — whether it is a built-in preset * `isActive` — whether this is the user's currently active design system *** ## Design Tools 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. Optional name for the design. Defaults to "Untitled". Optional natural language prompt. If omitted, a blank design is created instantly. Optional image URLs as visual references (only used with prompt). Optional design system ID. Use `list_design_systems` to discover IDs. Optional design system name (e.g. "Shadcn", "MUI"). Resolved case-insensitively. `designSystemId` takes precedence if both provided. Optional editor ID of an existing design to use as a template. The design is forked before any prompt is applied. You can find the editor ID in the design URL (`magicpatterns.com/c/`) or resolve it with `get_editor_id_from_url`. * `editorId` — the editor ID for subsequent operations - `editorUrl` — URL to edit the design - `previewUrl` — URL to preview the design - `activeArtifactId` — the currently active artifact ID - `availableFiles` — array of file paths This tool requires credits when used with a prompt. Resolves a Magic Patterns URL to an editor ID. The Magic Patterns URL. Supported formats: * `magicpatterns.com/c/` * `https://www.magicpatterns.com/c/` * `project-.magicpatterns.app` * `magicpatterns.com/s/?nodeIds=` * `editorId` — use with `get_design_status`, `send_prompt`, `get_artifact`, and other tools 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`. The editor ID from `create_design` or `get_editor_id_from_url`. * `isGenerating` — `true` if AI is still generating - `activeArtifactId` — the current active artifact ID - `availableFiles` — list of file names in the active artifact When `isGenerating=true`, wait at least **60 seconds** before polling again. Generation can take up to 10 minutes. 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. The editor ID of the design to update. A natural language description of what to create or change. * `requestId` — identifier for this generation request 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. 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. The editor ID of the design. Number of recent items to skip (for pagination). Defaults to 0. * `items` — array of chat history items (id, role, app, content summary, timeCreated) * `hasMore` — whether older items exist Lists the artifact version history for a design. Returns the most recent **20** versions. The editor ID of the design. Number of recent versions to skip (for pagination). Defaults to 0. * `versions` — array of versions (artifactId, versionLabel, title, timeCreated) * `hasMore` — whether older versions exist 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 The artifact ID to compile and publish. The editor ID of the design this artifact belongs to. * `artifactId` — the published artifact ID * `compiledFiles` — list of compiled file names *** ## Artifact Tools 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. The editor ID of the design. * `artifactId` — the current active artifact ID * `files` — list of file names 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. The artifact ID to clone from (typically the active artifact). A name for this artifact version (shown in the design timeline). * `artifactId` — the new artifact ID * `files` — list of file names cloned from the source 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. The artifact ID to read files from. Array of file names/paths to read. * `files` — array of `{ name, content }` for each matched file 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. The artifact ID to write files to. Array of files to write. Each entry has: - `fileName` — the file name/path (e.g. `App.tsx`, `utils/helpers.ts`) - `code` — the full file contents to write * `files` — updated list of all file names in the artifact *** ## Design System Tools These tools let an agent author a Magic Patterns **design system** — a reusable, versioned collection of components, styling, and rules — by writing files directly. This is distinct from the design/artifact tools above: here **you** write the code, rather than delegating to Magic Patterns' AI. Load the `design_system_authoring_guide` prompt before writing any files. It documents the full file/folder contract (component trios, named-export rules, `index.css` import order, allowed providers, and more). A design system's writable files follow this structure: * `components//index.tsx` — component source (PascalCase folder, **named exports only**) * `components//.previews.tsx` — preview definitions (required per component) * `components//Context.md` — AI/usage documentation (required per component) * `index.css` — design system styles / Tailwind imports (editable, cannot be deleted) * `tailwind.config.js` — Tailwind configuration (editable, cannot be deleted) * `rules/.md` — design rules (`rules/setup.md` is the special "Setup" rule) Shell / auto-generated files (root `index.tsx`, `library.ts`, `registry.ts`, etc.) are stripped automatically if sent. Resolves a design system's active artifact and lists its files. **Always call this first** — design systems are collaborative, so the active artifact ID can change between calls. Never reuse a cached `artifactId`. The design system ID (`ds-...`). Use `list_design_systems` to discover available design systems. * `designSystemId` — the design system ID * `name` — human-readable name * `artifactId` — the current active artifact (pass as `baseArtifactId` to `write_design_system_files` to detect drift) * `files` — the persisted files (e.g. `components//*`, `index.css`, `tailwind.config.js`, `rules/*`) * `hasUnpublishedChanges` — whether the active artifact differs from the latest published version * `guide` — pointer to the `design_system_authoring_guide` prompt Reads the contents of one or more files from a design system's active artifact. Call `get_design_system` first to discover available file names, and always read files **before** editing them so you preserve current content. The design system ID (`ds-...`). Array of file names/paths to read (as listed by `get_design_system`). * `files` — array of `{ name, content }` for each matched file Creates a new, blank design system owned by you and returns its ID and editor URL. Seeds an empty initial version so you can immediately write files into it. This creates a **blank** design system. Forking from an existing design system is not supported through the MCP. After creating, load the `design_system_authoring_guide` prompt and write files with `write_design_system_files`. The name of the new design system. Optional logo URL. Defaults to a placeholder. * `designSystemId` — the new design system ID * `name` — the design system name * `editorUrl` — URL to edit the design system Creates or overwrites files in a design system. Incoming files are merged onto the existing artifact (existing files are preserved), then compiled and activated immediately. This tool is **permissive**: it saves your files and returns `validationErrors` *without* blocking, so you can build incrementally. Fix all validation errors before calling `publish_design_system`, which is strict. The design system ID (`ds-...`). Array of files to create or overwrite. Each entry has: - `fileName` — the file path (e.g. `components/Button/index.tsx`, `index.css`, `rules/setup.md`) - `content` — the full file contents to write The `artifactId` from `get_design_system`. If the active artifact has since changed, the write is rejected with a **409** so you can re-read and retry. * `artifactId` — the new active artifact ID * `files` — updated list of all file names in the design system * `validationErrors` — non-blocking validation issues to fix before publishing Publishes the design system's active artifact as a new immutable version. This tool is **strict**: it refuses if the active artifact has validation errors. Run `write_design_system_files` and clear all `validationErrors` first. A breaking change (e.g. a removed component or prop) bumps the **major** version; otherwise the **minor** version is incremented. The design system ID (`ds-...`). * `version` — the new version (`{ major, minor }`) * `isBackwardsCompatible` — whether the version is backwards-compatible with the previously published version * `reason` — explanation when the change is breaking ## Video Walkthrough Getting existing code from your codebase into Magic Patterns: