> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowstep.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP Tools Reference > Input schema, output shape, and examples for all 20 Flowstep MCP tools. All tools return a `content` array of MCP content blocks. Text tools return `{ type: "text", text: "" }`. Image tools return `{ type: "image", data: "", mimeType: "image/png" }`. On failure, `isError: true` is set and the text block contains the error message. *** ## File tools ### `list-files` List Flowstep files for the current user. **Input** | Parameter | Type | Default | Description | | ----------------- | ----------------- | ------- | ------------------------- | | `orderByCreation` | `boolean` | `true` | Order by creation date | | `limit` | `integer` (1–100) | `20` | Number of files to return | | `offset` | `integer` (≥0) | `0` | Pagination offset | **Output** — JSON array of file objects. ```json theme={"system"} [ { "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "name": "Dashboard redesign", "created_at": "2026-04-30T15:02:13.120152+00:00", "updated_at": "2026-04-30T15:02:13.120152+00:00", "owner": true, "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0" } ] ``` *** ### `get-file` Get a single file by ID. File content is intentionally omitted — use `get-screen` or `get-screen-image` to inspect screens, and `get-design-guidelines` to retrieve attached guidelines. **Input** | Parameter | Type | Description | | --------- | ------ | ----------- | | `id` | `uuid` | File ID | **Output** — JSON file object. ```json theme={"system"} { "file": { "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "name": "Dashboard redesign", "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d", "created_at": "2026-04-30T15:02:13.120152+00:00", "updated_at": "2026-04-30T15:02:13.120152+00:00", "access_level": "private", "owner": true, "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0" }, "user_access_level": "write" } ``` *** ### `create-file` Create a new Flowstep file. **Input** | Parameter | Type | Description | | --------- | ---------------- | ----------- | | `title` | `string` (min 1) | File name | **Output** — JSON file object with the new file's `id`. ```json theme={"system"} { "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "name": "Dashboard redesign", "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d", "created_at": "2026-04-30T15:02:13.120152+00:00", "updated_at": "2026-04-30T15:02:13.120152+00:00", "access_level": "private", "user_access_level": "write", "owner": true, "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0" } ``` Use the returned `id` as `fileId` in subsequent tool calls. *** ### `update-file` Rename a file. **Input** | Parameter | Type | Description | | --------- | ---------------- | ----------- | | `id` | `uuid` | File ID | | `name` | `string` (min 1) | New name | **Output** — Updated file object in the same shape as `get-file`. ```json theme={"system"} { "file": { "id": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "name": "Dashboard redesign (v2)", "project_id": "81cb84d6-c69f-492c-a895-7421b60d1a6d", "created_at": "2026-04-30T15:02:13.120152+00:00", "updated_at": "2026-04-30T15:02:13.120152+00:00", "access_level": "private", "owner": true, "url": "https://app.flowstep.ai/file?activeFileId=5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0" }, "user_access_level": "write" } ``` *** ### `delete-file` Permanently delete a file. The `name` you pass is verified against the file's actual name before deletion — if it does not match, the deletion is aborted. This prevents accidentally deleting the wrong file. **Input** | Parameter | Type | Description | | --------- | -------- | -------------------------------------------------------------------- | | `id` | `uuid` | File ID | | `name` | `string` | Current name of the file — must match exactly or deletion is aborted | **Output** — `"File deleted successfully"` This is irreversible. All screens in the file are deleted. *** ## Screen tools ### `list-screens` List all generated screens for a file. Use the returned `screenId` values to reference screens in `get-screen`, `get-screen-image`, `upload-attachment`, and as `targets` in `edit-design`, `regenerate-design`, or `expand-design`. **Input** | Parameter | Type | Description | | --------- | ------ | ----------- | | `fileId` | `uuid` | File ID | **Output** — JSON array of screen summaries. ```json theme={"system"} [ { "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe", "name": "Mobile login screen", "fidelity": "ui", "prompt": "Generate a simple mobile login screen with email and password fields and a sign in button", "createdAt": "2026-04-30T15:02:37.444139+00:00" } ] ``` `name` is the user-assigned screen name, or `null` if unnamed. *** ### `get-screen` Get the JSX code for a screen allowing you to edit or use the code outside of Flowstep. Use `get-screen-image` for a visual preview instead. **Input** | Parameter | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | File ID | | `screenId` | `uuid` | The `screenId` returned by `list-screens` or from the `screenIds` array returned by a design tool | **Output** — The screen as code (JSX). Note the first line comment which is required when using the `add-screen` tool. ```json theme={"system"}
World Clock
Search cities...
...
; ``` *** ### `add-screen` Adds a new screen to a Flowstep file from a raw JSX string. **Input** | Parameter | Type | Description | | ------------ | -------- | ------------------------------------------------------------------------------- | | `fileId` | `uuid` | File ID | | `jsxContent` | `string` | JSX to add to the file as a screen | | `screenType` | `string` | Required if the screen type is not defined as a comment at the start of the JSX | **Note** - A comment similar to the one below MUST be present as the first line of the JSX as it is used to add the screen correctly. `screenType`, `name`, and `screenId` are all optional — `screenId` is used (internally) if present (e.g. when passing JSX copied from `get-screen` output) but is not mandatory. The screen name is taken from the comment's `name` field (displayed as "Copy of \"), or "Untitled" if absent. `` **Output** — The newly added screen Id. ```json theme={"system"} { "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbf" } ``` *** ### `get-screen-image` Render a screen to PNG and return it as an inline image. Requires a client that supports image content blocks. **Input** | Parameter | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | File ID | | `screenId` | `uuid` | The `screenId` returned by `list-screens` or from the `screenIds` array returned by a design tool | **Output** — MCP image content block (`image/png`). *** ## AI tools `regenerate-design`, `expand-design`, and `edit-design` require design context that is only present on screens originally generated with a `designs` array. Screens generated without design context will return an error. Workaround: use `upload-attachment` to render the screen as an image, then call `create-new-design` with the image in `attachments` and a message describing the desired changes. ### `create-new-design` Generate one or more screen designs from a text prompt. Omit `fileId` to create a new file automatically. Blocks until generation completes or times out (180 seconds). **Input** | Parameter | Type | Default | Description | | ------------- | --------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `fileId` | `uuid` | — | Target file — omit to create a new file automatically | | `message` | `string` | — | Prompt describing the screens to generate | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Pre-uploaded attachments — images, PDFs, or code files. Always upload via `upload-attachment` first; do not inline file contents in the message | | `designs` | `DesignRequestData[]` | `[]` | Design references | **Output** — `{ fileId, screenIds }`. Pass each `screenId` to `get-screen-image` to view results. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"] } ``` *** ### `regenerate-design` Redo existing screens from scratch or with a style variation. Requires at least one `screenId` in `targets`. Blocks until generation completes or times out (180 seconds). **Input** | Parameter | Type | Default | Description | | ------------------ | ----------------------------------------------------------- | ------- | ------------------------------------------ | | `fileId` | `uuid` | — | Target file | | `message` | `string` | — | Prompt text | | `targets` | `uuid[]` (min 1) | — | screenIds of screens to regenerate | | `operationVariant` | `"different_layout" \| "different_style" \| "from_scratch"` | — | Optional style variant | | `designs` | `DesignRequestData[]` | `[]` | Design references (resolved automatically) | **Output** — `{ fileId, screenIds }`. Pass each `screenId` to `get-screen-image` to view results. *** ### `expand-design` Add follow-on screens to an existing design. Requires at least one `screenId` in `targets` and a mandatory `operationVariant`. Blocks until generation completes or times out (180 seconds). **Input** | Parameter | Type | Default | Description | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------- | | `fileId` | `uuid` | — | Target file | | `message` | `string` | — | Prompt text | | `targets` | `uuid[]` (min 1) | — | screenIds of screens to expand from | | `operationVariant` | `"next_screen" \| "error_state" \| "empty_state" \| "web_version" \| "mobile_version" \| "tablet_version" \| "mobile_ios_version" \| "mobile_android_version"` | — | **Required** — type of follow-on screen to generate | | `designs` | `DesignRequestData[]` | `[]` | Design references (resolved automatically) | **Output** — `{ fileId, screenIds }`. Pass each `screenId` to `get-screen-image` to view results. *** ### `edit-design` Modify existing screens via a prompt. Requires at least one `screenId` in `targets`. Blocks until generation completes or times out (180 seconds). **Input** | Parameter | Type | Default | Description | | ------------------ | ------------------------------------------------ | ------- | --------------------------------------------------------------------- | | `fileId` | `uuid` | — | Target file | | `message` | `string` | — | Instructions describing the edits to apply | | `targets` | `uuid[]` (min 1) | — | screenIds of screens to edit | | `operationVariant` | `"dark_theme" \| "light_theme" \| "make_pretty"` | — | Optional style shortcut | | `attachments` | `AttachmentRequestData[]` (max 5) | `[]` | Pre-uploaded attachments. Always upload via `upload-attachment` first | | `designs` | `DesignRequestData[]` | `[]` | Design references (resolved automatically) | **Output** — `{ fileId, screenIds }`. Pass each `screenId` to `get-screen-image` to view results. *** ### `upload-attachment` Upload a file to use as an attachment in `create-new-design` or `edit-design`. Returns `{ id, path, type, mimeType }` — pass this object directly into the `attachments` array. Two modes: **Mode 1 — Screen by ID** Pass `screenId` and `fileId`. The server fetches the screen state from the database and renders it as an image. | Parameter | Type | Description | | ---------- | ------ | ------------------------------------- | | `fileId` | `uuid` | File containing the screen (required) | | `screenId` | `uuid` | Screen to render | **Mode 2 — External file** Pass file content directly. Binary files must be base64-encoded; text files (including source code) are passed as plain UTF-8 strings. | Parameter | Type | Description | | ---------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `fileData` | `string` | File content — base64 for binary, UTF-8 string for text | | `fileName` | `string` | Original filename | | `mimeType` | `"image/jpeg" \| "image/png" \| "image/webp" \| "application/pdf" \| "text/plain" \| "text/javascript"` | MIME type. Use `text/javascript` for `.jsx`, `.tsx`, `.js`, `.ts` files | Max file size: **3 MB**. For large images, prefer `image/jpeg` over `image/png`. **Output** ```json theme={"system"} { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890", "type": "image", "mimeType": "image/jpeg" } ``` `type` is `"image"` for image/PDF uploads and `"document"` for text/code files. *** ## Chat tools ### `get-chat-history` Get the chat message history for a file. **Input** | Parameter | Type | Description | | --------- | ------ | ----------- | | `fileId` | `uuid` | File ID | **Output** — JSON object with a `messages` array. Each message has a `type` (`"request"` or `"response"`), `author` (`"human"` or `"ai"`), and `content_type` (`"text"`, `"summary"`, or `"followup"`). ```json theme={"system"} { "messages": [ { "id": "453f593d-2380-425b-ba29-127db08d6a8e", "chat_id": "146d0f19-497e-450c-ba53-3de15f6bd70b", "type": "request", "status": "success", "content": "Generate a simple mobile login screen with email and password fields", "author": "human", "content_type": "text", "sequence": 1, "request_message_id": null, "targets": [], "attachments": [] }, { "id": "d860186b-82d5-4bd1-8e8e-8ba5377a14bf", "chat_id": "146d0f19-497e-450c-ba53-3de15f6bd70b", "type": "response", "status": "success", "content": "Generated a mobile login screen with email and password input fields, sign in button, remember me checkbox, forgot password link, social login options (Apple/Google), and sign up link.", "author": "ai", "content_type": "summary", "sequence": 7, "request_message_id": "453f593d-2380-425b-ba29-127db08d6a8e", "targets": [{ "target_id": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" }], "attachments": [] } ] } ``` *** ## Design tools ### `get-design-guidelines` Get the design guidelines stored for a file. **Input** | Parameter | Type | Default | Description | | ------------ | -------- | -------- | ------------- | | `resourceId` | `uuid` | — | File ID | | `linkedTo` | `"file"` | `"file"` | Resource type | **Output** ```json theme={"system"} { "guidelines": "## Colors\n\nPrimary: #6366F1\nBackground: #FFFFFF\n\n## Typography\n\nFont: Inter", "linkedTo": "file" } ``` `guidelines` is `null` if no guidelines have been set. *** ### `update-design-guidelines` Set or replace the design guidelines for a file. Guidelines are passed as a plain text string in Google's `design.md` format — do not pass an object or JSON. The server performs soft validation and may return a `Warnings:` section in the response listing issues (unknown keys, non-hex colours) that were accepted but may be ignored by the AI. Surface these to the user. **Input** | Parameter | Type | Default | Description | | ------------------ | ---------------- | -------- | ----------------------------------------------------------------------------- | | `resourceId` | `uuid` | — | File ID | | `designGuidelines` | `string` (min 1) | — | Raw text content of the guidelines. Must be a plain string — not JSON-encoded | | `linkedTo` | `"file"` | `"file"` | Resource type | **Validation rules** * Frontmatter must be opened and closed correctly * Frontmatter lines must be valid block-style YAML * Markdown body must not contain duplicate `##` section headings **Output** — `"Design guidelines updated successfully"`, optionally followed by a `Warnings:` section. *** ### `delete-design-guidelines` Clear the design guidelines for a file. **Input** | Parameter | Type | Default | Description | | ------------ | -------- | -------- | ------------- | | `resourceId` | `uuid` | — | File ID | | `linkedTo` | `"file"` | `"file"` | Resource type | **Output** — `"Design guidelines deleted successfully"` *** ## Figma tools ### `import-figma` Import a Figma frame into a Flowstep file as editable elements on its canvas. Re-importing the same frame updates it in place. The file's organization must have Figma connected in Flowstep settings. **Input** | Parameter | Type | Description | | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `figmaUrl` | `string` | Link to a specific Figma frame. In Figma, right-click the frame and choose **Copy link to selection**. A link to a page imports all top-level frames on that page (capped at 20 frames over MCP). | | `fileId` | `uuid` | The Flowstep file to import the frame into | **Output** — `{ fileId, screenId }`. `screenId` is the id of the imported screen element — pass it to `get-screen-image` to view the result. When a page URL imports multiple frames, `screenId` is `null` and `frameCount` is returned instead. ```json theme={"system"} { "fileId": "5c2170f0-5b09-4a5a-ba7a-4d5c2cfb07e0", "screenId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe" } ``` *** ## Billing tools ### `get-plan-details` Get the current user's plan, subscription status, and remaining quota. Takes no input. **Output** ```json theme={"system"} { "plan": { "name": "Starter", "code": "starter", "type": "paid" }, "subscription": { "isPaid": true, "isTrial": false, "startDate": "2025-01-01T00:00:00Z", "endDate": null, "trialDaysRemaining": null }, "limits": { "messages": { "daily": { "max": 50, "warn": 40 }, "monthly": { "max": 500, "warn": 400 }, "unlimited": false } }, "usage": { "messages": { "daily": 12, "monthly": 87 } }, "remaining": { "messages": { "daily": 38, "monthly": 413 } } } ``` Limits vary by plan. Call this tool before a batch of generations to check available quota.