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

Parameter	Type	Description
`id`	`uuid`	File ID

Output — "File deleted successfully"

This is irreversible. All screens in the file are deleted.

`generate-file-name`

Auto-generate a name for a Flowstep file based on its content. Input

Parameter	Type	Description
`userId`	`uuid`	User ID
`fileId`	`uuid`	File ID

Output — A plain string with the suggested name.

"Mobile Login Screen"

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 ai-prompt. 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 raw component tree for a screen. Returns the full element map used by the Flowstep editor. 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 `screenIds` from `ai-prompt`

Output — JSON map of component elements keyed by element ID. The top-level entry is the screen node; all other entries are its descendants.

{
  "3f9e6eb6-5525-4383-9375-67e0bd762dbe": {
    "id": "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
    "parentId": "root_id",
    "type": "wireframe",
    "fidelity": "ui",
    "lastPrompt": "Generate a simple mobile login screen...",
    "wireframe": {
      "dimensions": [402, 874],
      "screenDesignSpecification": {
        "screenType": "mobile_ios",
        "colorTheme": "default",
        "navigation": null
      }
    },
    "children": ["7f18fd75-a540-5652-8ada-2b7d605c3363"],
    "name": "Mobile login screen"
  },
  "7f18fd75-a540-5652-8ada-2b7d605c3363": {
    "id": "7f18fd75-a540-5652-8ada-2b7d605c3363",
    "parentId": "3f9e6eb6-5525-4383-9375-67e0bd762dbe",
    "type": "jsx-element",
    "jsxType": "div",
    "props": { "className": "" },
    "children": ["..."],
    "styles": {
      "backgroundFills": [{ "hex": "#ffffff", "opacity": 100 }],
      "textFills": [{ "hex": "#0a0a0a", "opacity": 100 }]
    },
    "layout": { "width": "full", "height": "fit" }
  }
}

`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 `screenIds` from `ai-prompt`

Output — MCP image content block (image/png).

AI tools

`ai-prompt`

Send an AI generation request and wait for the result. Blocks until the generation completes or times out (180 seconds). Operations

`operation`	What it does	Required fields
(none)	Generate a new screen from scratch	`fileId`, `message`
`regenerate`	Redo an existing screen	`targets` (one screenId), optionally `operationVariant`
`expand`	Add a follow-on screen	`targets` (one screenId), `operationVariant`
`edit`	Modify existing screens via prompt	`targets` (one or more screenIds), optionally `operationVariant`

regenerate, expand, and edit require design context that is only present on screens originally generated with a designs array. Screens generated without design context will return an error. For those screens, use upload-attachment to render the screen as an image, then call ai-prompt with no operation and the image in attachments, describing the desired changes in the message.

Input

Parameter	Type	Default	Description
`fileId`	`uuid`	—	Target file
`message`	`string`	—	Prompt text
`operation`	`"regenerate" \| "expand" \| "edit"`	—	Optional operation type
`operationVariant`	see below	—	Operation-specific variant
`targets`	`uuid[]`	`[]`	screenIds of screens to act on
`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 (resolved automatically for regenerate/expand/edit)

operationVariant values

operation	variants
`expand`	`next_screen`, `error_state`, `empty_state`, `web_version`, `mobile_version`, `tablet_version`, `mobile_ios_version`, `mobile_android_version`
`regenerate`	`different_layout`, `different_style`, `from_scratch`
`edit`	`dark_theme`, `light_theme`, `make_pretty`

Output — Array of generated screen IDs.

{
  "screenIds": ["3f9e6eb6-5525-4383-9375-67e0bd762dbe"]
}

Pass a screenId to get-screen-image to see the result.

`upload-attachment`

Upload a file to use as an attachment in ai-prompt. Returns { id, path, type, mimeType } — pass this object directly into ai-prompt.attachments. Three modes: Mode 1 — Screen with element state (fastest) Pass screenId and the elementState JSON string from get-screen. Renders the screen directly without a database fetch. fileId is not required.

Parameter	Type	Description
`screenId`	`uuid`	Screen to render
`elementState`	`string`	Raw element state JSON from `get-screen`

Mode 2 — Screen by ID Pass screenId and fileId. The server fetches the screen state from the database and renders it.

Parameter	Type	Description
`fileId`	`uuid`	File containing the screen
`screenId`	`uuid`	Screen to render

Mode 3 — 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"
}

Pass the entire object into ai-prompt.attachments. 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.

Get Started

Using Flowstep

Exporting & Integrations

MCP Server

Billing & Plans

Security & Privacy

MCP Tools Reference

File tools

`list-files`

`get-file`

`create-file`

`update-file`

`delete-file`

`generate-file-name`

Screen tools

`list-screens`

`get-screen`

`get-screen-image`

AI tools

`ai-prompt`

`upload-attachment`

Chat tools

`get-chat-history`

Design tools

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

Billing tools

`get-plan-details`

Get Started

Using Flowstep

Exporting & Integrations

MCP Server

Billing & Plans

Security & Privacy

Documentation Index

​File tools

​list-files

​get-file

​create-file

​update-file

​delete-file

​generate-file-name

​Screen tools

​list-screens

​get-screen

​get-screen-image

​AI tools

​ai-prompt

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

`generate-file-name`

Screen tools

`list-screens`

`get-screen`

`get-screen-image`

AI tools

`ai-prompt`

`upload-attachment`

Chat tools

`get-chat-history`

Design tools

`get-design-guidelines`

`update-design-guidelines`

`delete-design-guidelines`

Billing tools

`get-plan-details`