> ## Documentation Index > Fetch the complete documentation index at: https://www.magicpatterns.com/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 four primary ways to use the Magic Patterns MCP tools. > [card] Prompt-based > > Delegate creative work to Magic Patterns' AI. Send a natural language prompt > and let the AI generate or update code. > [card] Code-first > > Write code directly into artifacts. Create a working branch, edit files, and > publish when done. > [card] Design-system authoring > > Build a reusable design system by writing components, styling, and rules > directly, then publish versioned releases. > [card] Inspiration concepts > > Publish a shareable set of side-by-side design concepts, then fill in or > revise each concept's content as you explore directions. ### 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) ``` ### Workflow D — Inspiration concepts Publish a shareable `magicpatterns.com/inspiration/` link that renders 4 design concepts side by side. The preferred flow declares placeholder concepts first (so the link is publishable immediately), then streams each concept's content in one at a time. ``` 1. create_inspiration_document(title, files) → declare concepts (with or without html), get the shareable URL 2. inspiration_add_variant(inspirationId, variantId, html) → fill in each placeholder concept 3. get_inspiration_document(inspirationId) → read concepts back (e.g. to implement one) 4. inspiration_update_variant(inspirationId, variantId, html) → revise a single filled concept in place 5. inspiration_clear_variants(inspirationId) → reset every concept back to a placeholder ``` > [!TIP] > > Slide decks share the design/artifact tooling: `create_slide_deck(prompt)` > kicks off AI generation just like `create_design`, then you poll > `get_design_status` the same way. *** ## Important Guidance > [!WARNING] > > **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. > [!WARNING] > > **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. > [!WARNING] > > **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 **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. This tool takes no parameters. **Returns** 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 **send\_feedback\_to\_magic\_patterns\_team** `Tool` Sends feedback straight to the Magic Patterns team. Agents can report what they ran into themselves (a tool that errored, confused them, or couldn't do what their user needed), and relay feedback from the person driving them. Changes nothing in any design. Also available on the read-only endpoint. **Parameters** **feedback** `string` *required* The feedback in plain language, up to 2000 characters. For a problem: what you were trying to do, what you expected, what happened, and any workaround. **from** `string` *required* `agent` for something the agent ran into itself, or `user` when relaying what its user said. **category** `string` Optional. One of `bug`, `confusing`, `feature_request`, `praise`, or `other`. **toolName** `string` Optional. The Magic Patterns tool the feedback is about. **Returns** * `ok` — `true` once the feedback has been sent *** ## 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. **Parameters** **name** `string` Optional name for the design. Defaults to "Untitled". **prompt** `string` Optional natural language prompt. If omitted, a blank design is created instantly. **imageUrls** `string[]` Optional image URLs as visual references (only used with prompt). **designSystemId** `string` Optional design system ID. Use `list_design_systems` to discover IDs. **designSystem** `string` Optional design system name (e.g. "Shadcn", "MUI"). Resolved case-insensitively. `designSystemId` takes precedence if both provided. **templateId** `string` 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`. **Returns** * `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 > [!WARNING] > > This tool requires credits when used with a prompt. **create\_slide\_deck** `Tool` Creates a new Magic Patterns **slide deck** and kicks off AI generation. A slide deck is a 16:9, full-bleed, one-slide-at-a-time React presentation where each slide maps to a screen in the canvas. Unlike `create_design`, a `prompt` is **required** — there is no blank-deck path. Generation is long-running (2–10 minutes); poll `get_design_status` every 60s. **Parameters** **prompt** `string` *required* Natural language description of the slide deck to generate (e.g. "A 10-slide startup pitch deck for a fintech company"). **name** `string` Optional name for the slide deck. Defaults to "Untitled". **imageUrls** `string[]` Optional image URLs as visual references. **designSystemId** `string` Optional design system ID. Use `list_design_systems` to discover IDs. **designSystem** `string` Optional design system name (e.g. "Shadcn", "MUI"). Resolved case-insensitively. `designSystemId` takes precedence if both provided. **Returns** * `editorId` — the editor ID for subsequent operations * `editorUrl` — URL to edit the slide deck * `previewUrl` — URL to preview the slide deck * `activeArtifactId` — the currently active artifact ID * `availableFiles` — array of file paths > [!WARNING] > > Generation typically takes **2–10 minutes**. Poll `get_design_status` every 60 seconds until `isGenerating=false`. This tool requires credits. **get\_editor\_id\_from\_url** `Tool` Resolves a Magic Patterns URL to an editor ID. **Parameters** **url** `string` *required* The Magic Patterns URL. Supported formats: * `magicpatterns.com/c/` * `https://www.magicpatterns.com/c/` * `project-.magicpatterns.app` * `magicpatterns.com/s/?nodeIds=` **Returns** * `editorId` — use with `get_design_status`, `send_prompt`, `get_artifact`, and other tools **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`. **Parameters** **editorId** `string` *required* The editor ID from `create_design` or `get_editor_id_from_url`. **Returns** * `isGenerating` — `true` if AI is still generating - `activeArtifactId` — the current active artifact ID - `availableFiles` — list of file names in the active artifact > [!NOTE] > > 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. **Parameters** **editorId** `string` *required* The editor ID of the design to update. **prompt** `string` *required* A natural language description of what to create or change. **Returns** * `requestId` — identifier for this generation request > [!NOTE] > > Check `get_design_status` first to ensure `isGenerating=false` before sending a prompt. > [!WARNING] > > 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. **Parameters** **editorId** `string` *required* The editor ID of the design. **skip** `number` Number of recent items to skip (for pagination). Defaults to 0. **Returns** * `items` — array of chat history items (id, role, app, content summary, timeCreated) * `hasMore` — whether older items exist **list\_version\_history** `Tool` Lists the artifact version history for a design. Returns the most recent **20** versions. **Parameters** **editorId** `string` *required* The editor ID of the design. **skip** `number` Number of recent versions to skip (for pagination). Defaults to 0. **Returns** * `versions` — array of versions (artifactId, versionLabel, title, timeCreated) * `hasMore` — whether older versions exist **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 **Parameters** **artifactId** `string` *required* The artifact ID to compile and publish. **editorId** `string` *required* The editor ID of the design this artifact belongs to. **Returns** * `artifactId` — the published artifact ID * `compiledFiles` — list of compiled file names *** ## 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. **Parameters** **editorId** `string` *required* The editor ID of the design. **Returns** * `artifactId` — the current active artifact ID * `files` — list of file names **create\_new\_artifact** `Tool` Creates a new artifact by cloning an existing one. The new artifact becomes the active artifact. > [!NOTE] > > 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. **Parameters** **artifactId** `string` *required* The artifact ID to clone from (typically the active artifact). **name** `string` *required* A name for this artifact version (shown in the design timeline). **Returns** * `artifactId` — the new artifact ID * `files` — list of file names cloned from the source **read\_artifact\_files** `Tool` Reads the contents of one or more files from an artifact. > [!NOTE] > > Always read files **before** making changes with `write_artifact_files` so you > understand the current state. **Parameters** **artifactId** `string` *required* The artifact ID to read files from. **fileNames** `string[]` *required* Array of file names/paths to read. **Returns** * `files` — array of `{ name, content }` for each matched file **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. > [!NOTE] > > This only saves source files — it does **not** compile or publish. Call > `publish_artifact` after finishing all file changes. **Parameters** **artifactId** `string` *required* The artifact ID to write files to. **files** `array` *required* 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 **Returns** * `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. > [!TIP] > > 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. **get\_design\_system** `Tool` 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`. **Parameters** **designSystemId** `string` *required* The design system ID (`ds-...`). Use `list_design_systems` to discover available design systems. **Returns** * `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 **read\_design\_system\_files** `Tool` Reads the contents of one or more files from a design system's active artifact. > [!NOTE] > > Call `get_design_system` first to discover available file names, and always > read files **before** editing them so you preserve current content. **Parameters** **designSystemId** `string` *required* The design system ID (`ds-...`). **fileNames** `string[]` *required* Array of file names/paths to read (as listed by `get_design_system`). **Returns** * `files` — array of `{ name, content }` for each matched file **create\_design\_system** `Tool` 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. > [!NOTE] > > 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`. **Parameters** **name** `string` *required* The name of the new design system. **logo** `string` Optional logo URL. Defaults to a placeholder. **Returns** * `designSystemId` — the new design system ID * `name` — the design system name * `editorUrl` — URL to edit the design system **write\_design\_system\_files** `Tool` 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. > [!NOTE] > > 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. **Parameters** **designSystemId** `string` *required* The design system ID (`ds-...`). **files** `array` *required* 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 **baseArtifactId** `string` 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. **Returns** * `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 **publish\_design\_system** `Tool` Publishes the design system's active artifact as a new immutable version. > [!NOTE] > > 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. **Parameters** **designSystemId** `string` *required* The design system ID (`ds-...`). **Returns** * `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 *** ## Inspiration Tools These tools publish and manage a Magic Patterns **inspiration document** — a shareable `magicpatterns.com/inspiration/` link that renders 4 design **concepts** (variants) side by side. Each concept is a self-contained sketch of a UI direction. **create\_inspiration\_document** `Tool` Creates an inspiration document and returns a shareable URL. Declare each concept's `name`/`description` **without** `html` to publish the link immediately, then stream each concept in with `inspiration_add_variant`. You may also pass `html` inline to publish concepts fully in one call. **Parameters** **title** `string` Short label for what the concepts explore (e.g. "Projects list empty state"). **files** `array` *required* 1–8 concepts, each with: - `name` — the concept name - `description` — one-line description of the direction - `html` — the full, self-contained concept content (omit to declare a placeholder to fill later) **repositoryUrl** `string` Optional GitHub repo URL the concepts were generated from (kept for context). **baseline** `object` Optional baseline the variants diverge from: `{ html, focus, sharedCopy, baselineStyle }` where `html` is a faithful recreation of the current UI's content. **Returns** * `id` — the inspiration document ID * `url` — the shareable URL (login may be required) * `variants` — array of `{ id, name }`; pass each `id` to `inspiration_add_variant` **inspiration\_add\_variant** `Tool` Fills in one placeholder concept with its content. The concept renders live on the shared page as soon as its content arrives; the document flips to "ready" once every concept is filled. **Parameters** **inspirationId** `string` *required* The inspiration document ID from `create_inspiration_document`. **variantId** `string` The concept ID to fill. If omitted, the first still-empty concept is filled. **name** `string` Optional update to the concept's name. **description** `string` Optional update to the concept's design direction. **html** `string` *required* The full, self-contained concept content (non-empty). **Returns** * `ok` — whether the concept was filled * `variantId` — the filled concept ID * `url` — the shareable URL **get\_inspiration\_document** `Tool` Loads an inspiration document by its ID. Use this to read concepts back — for example, to implement a specific concept ("Implement Concept B from inspiration ``"). **Parameters** **inspirationId** `string` *required* The inspiration document ID (the `` in `magicpatterns.com/inspiration/`). **Returns** * `title`, `userPrompt` — the original request the concepts explore * `status` — `generating` while concepts are still being produced, else `ready`/`error` * `variants` — the concepts in order (Concept A = `variants[0]`, etc.), each with `{ id, name, description, implementationPrompt, html, status }` > [!NOTE] > > A concept is only usable once its `status` is `ready`; a non-ready one has empty/partial `html`. **inspiration\_update\_variant** `Tool` Revises a single **already-filled** concept in place, replacing its content (and optionally its name/description). Use this to update a subset of concepts without touching the others. **Parameters** **inspirationId** `string` *required* The inspiration document ID. **variantId** `string` *required* The concept ID to revise (from `get_inspiration_document`). Targets an existing filled concept, unlike `inspiration_add_variant`. **name** `string` Optional update to the concept's name. **description** `string` Optional update to the concept's design direction. **html** `string` *required* The full, self-contained concept content (non-empty). **Returns** * `ok` — whether the concept was updated * `variantId` — the revised concept ID * `url` — the shareable URL **inspiration\_clear\_variants** `Tool` Resets **every** concept back to an empty placeholder — dropping each concept's content and its pre-created "Iterate" room. Use this to replace all concepts with a fresh set of directions. **Parameters** **inspirationId** `string` *required* The inspiration document ID. **Returns** * `ok` — whether the concepts were cleared * `url` — the shareable URL * `variants` — array of `{ id, name }`; each keeps its ID and name for refilling via `inspiration_add_variant` ## Video Walkthrough Getting existing code from your codebase into Magic Patterns: [Magic Patterns MCP - Importing Existing Components](https://www.youtube.com/embed/2QOc6vXftHo?start=178) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.