MCP Tools Reference

All tools return a content array of MCP content blocks. Text tools return { type: "text", text: "<json-string>" }. Image tools return { type: "image", data: "<base64>", 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.

[
  {
    "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.

{
  "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.

{
  "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.

{
  "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, 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.

[
  {
    "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.

<!-- screenType: "iphone-x-vertical" width: "375" height: "812" name: "Change to a light theme" colorTheme: "blue" screenId: "c13d3707-0efe-49f5-b6cb-0ca5ac5223d0" -->
<div className="bg-white text-zinc-950 w-full h-fit">
  <div className="flex p-6 flex-col gap-6">
    <div className="flex pt-4 justify-between items-center">
      <ArrowLeft className="size-5 text-[#71717b]" />
      <span className="font-semibold text-zinc-950 text-lg leading-7">
        World Clock
      </span>
      <Plus className="size-5 text-[#2b7fff]" />
    </div>
    <div className="rounded-xl bg-zinc-100 flex p-2 items-center gap-2">
      <Search className="size-4 text-[#71717b] ml-2" />
      <span className="text-[#71717b] text-sm leading-5">Search cities...</span>
    </div>
...
    <div className="flex pt-2 pb-4 justify-center items-center gap-4">
      <Button variant="outline" className="rounded-full px-6 gap-2">
        <Clock className="size-4" />
        <span>Compare</span>
      </Button>
      <Button className="rounded-full bg-[#2b7fff] text-blue-50 px-6 gap-2">
        <Bell className="size-4" />
        <span>Set Alert</span>
      </Button>
    </div>
  </div>
</div>;

`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 <name>”), or “Untitled” if absent.  Output — The newly added screen Id.

{ "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.

`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.

{
  "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 (not regenerate-design or expand-design). File bytes never pass through the model, and the server never fetches URLs on your behalf. There are two modes — use exactly one, and don’t combine them. Mode A — files and images (mimeType + fileName) A required three-step flow for any image, PDF, or larger text file:

Call upload-attachment with mimeType and fileName only (for example image/png and dog.png). The response is a prepared upload, not a stored file:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "image",
  "mimeType": "image/png",
  "signedUrl": "https://…",
  "uploadCommand": "curl -sS -f -X PUT '…' -H 'Content-Type: image/png' -H 'x-metadata: …' --data-binary @LOCAL_FILE_PATH",
  "nextStep": "…"
}

Replace LOCAL_FILE_PATH in uploadCommand with the absolute path to your file and run that exact command in your shell — it must exit 0. The token in signedUrl authorizes only this single upload. Skipping this step leaves storage empty and the design tool fails its preflight check.
Pass only { id, path, type } into the design tool’s attachments array — not signedUrl, uploadCommand, or nextStep.

To attach a remote file, download it to a local path yourself first (for example with curl), then follow the same three steps. Never pass a URL to upload-attachment.

Parameter	Type	Description
`mimeType`	enum	File MIME type. One of `image/jpeg`, `image/png`, `image/webp`, `application/pdf`, `text/markdown`, `text/plain`, `text/javascript`. Use `text/javascript` for `.jsx`, `.tsx`, `.js`, `.ts` files
`fileName`	`string` (min 1)	Original filename with extension, for example `cat.png` or `design.md`

Mode B — short text (text + mimeType) Upload text that’s already in context — no shell command needed. The response is ready to use directly:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "attachments/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "document",
  "mimeType": "text/plain"
}

Parameter	Type	Description
`text`	`string` (max 64,000 chars)	Raw text content. Text files only — don’t use for images or PDFs. Longer than 64,000 characters? Use Mode A instead
`mimeType`	enum	One of `text/markdown`, `text/plain`, `text/javascript`

Pass the resulting { id, path, type } into the attachments array of create-new-design or edit-design. Maximum file size is 3 MB across both modes, and PDFs are capped at 100 pages. type is "image" for image files and "document" for PDFs and text 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").

{
  "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

{
  "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.

{
  "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

{
  "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.

Get Started

Using Flowstep

Teams & Organizations

Exporting & Integrations

MCP Server

Billing & Plans

Security & Privacy

MCP Tools Reference

File tools

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

Screen tools

`list-screens`

`get-screen`

`add-screen`

`get-screen-image`

AI tools

`create-new-design`

`regenerate-design`

`expand-design`

`edit-design`

`upload-attachment`

Chat tools

`get-chat-history`

Design tools

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

Figma tools

`import-figma`

Billing tools

`get-plan-details`

​File tools

​list-files

​get-file

​create-file

​update-file

​delete-file

​Screen tools

​list-screens

​get-screen

​add-screen

​get-screen-image

​AI tools

​create-new-design

​regenerate-design

​expand-design

​edit-design

​upload-attachment

​Chat tools

​get-chat-history

​Design tools

​get-design-guidelines

​update-design-guidelines

​delete-design-guidelines

​Figma tools

​import-figma

​Billing tools

​get-plan-details

File tools

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

Screen tools

`list-screens`

`get-screen`

`add-screen`

`get-screen-image`

AI tools

`create-new-design`

`regenerate-design`

`expand-design`

`edit-design`

`upload-attachment`

Chat tools

`get-chat-history`

Design tools

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

Figma tools

`import-figma`

Billing tools

`get-plan-details`