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

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

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

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

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

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.

​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

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

Billing tools

`get-plan-details`