> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryflowy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Flowy is a node-based AI creative platform: you generate images, video, audio, 3D and vector on an infinite Canvas, refine on the Studio timeline, and export or publish from the same project.
> Prefer the Flowy MCP server (https://mcp.tryflowy.ai/mcp) or the REST API at https://apis.tryflowy.ai/v1 for programmatic work. Install with `flowy mcp install` from the @flowy/cli package.
> Credits are workspace-scoped. Generations reserve credits on start and only deduct on success, so failed runs refund automatically.

# MCP server

> Connect an AI agent to your Flowy account over the hosted MCP server.

Flowy ships a hosted [MCP](https://modelcontextprotocol.io) server at:

```text theme={"theme":{"light":"github-light","dark":"vesper"}}
https://mcp.tryflowy.ai/mcp
```

It speaks Streamable HTTP (the current MCP transport) and authenticates over
OAuth. No API key to copy anywhere. Point a compatible agent at the URL, sign
in and consent once in the browser, and the connection is **bound to your
Flowy account**: by default every tool call acts in and bills your personal
account wallet, and can act in any workspace you can manage by passing a
`workspace_id` (from `list_workspaces`).

## Discovery flow

An MCP client never needs the OAuth details hardcoded. It discovers them from
the server itself, per the MCP authorization spec:

<Steps>
  <Step title="Unauthenticated request">
    The client `POST`s to `/mcp` with no bearer token.
  </Step>

  <Step title="401 challenge">
    The server responds `401` with a `WWW-Authenticate: Bearer
            resource_metadata="…"` header pointing at its protected-resource metadata.
  </Step>

  <Step title="Protected-resource metadata (RFC 9728)">
    The client fetches that URL and reads `authorization_servers` (which
    authorization server to use) and `scopes_supported`.
  </Step>

  <Step title="Authorization-server metadata (RFC 8414)">
    The client fetches `/.well-known/oauth-authorization-server` on that
    authorization server (mirrored on the MCP server's own origin) to learn
    the `authorize`, `token`, and `registration` endpoints.
  </Step>

  <Step title="Dynamic client registration (RFC 7591)">
    The client registers itself against the `registration` endpoint and gets
    back a `client_id`, with no manual app setup required.
  </Step>

  <Step title="Authorize with PKCE">
    The client opens the `authorize` URL with a PKCE challenge. You sign in
    (if needed) and see the consent screen: the same one described in
    [OAuth apps](/api/oauth#the-consent-screen), and approve.
  </Step>

  <Step title="Token exchange">
    The client exchanges the authorization code for an access token at the
    `token` endpoint.
  </Step>

  <Step title="Retry with the bearer">
    The client retries the original `/mcp` request with
    `Authorization: Bearer <token>`, and the session proceeds normally.
  </Step>
</Steps>

<Note>
  Every step above is automatic in an MCP-native client (Claude, Claude Code,
  Cursor, ChatGPT). You only ever interact with the sign-in + consent screen
  in step 6.
</Note>

## Scopes

The server requests this fixed set of scopes on every connection, matching
the backend's registration ceiling for MCP clients, so a client that requests
exactly these gets the full tool surface below, flow creation included:

`apps:read` · `apps:write` · `runs:read` · `runs:write` ·
`generations:read` · `generations:write` · `assets:read` · `credits:read`

<Note>
  This scope set is specific to the MCP server's client registration. It
  isn't the same list a third-party [OAuth app](/api/oauth#scopes) can
  request from the console (that list adds `elements:read` /
  `elements:write` and omits `apps:write`).
</Note>

## Tools

The server exposes **38 tools**, grouped by what they work with:

<AccordionGroup>
  <Accordion title="Community (3)">
    | Tool                       | What it does                                                                           |
    | -------------------------- | -------------------------------------------------------------------------------------- |
    | `list_community_templates` | Browse community templates, featured, or searched by query/category.                   |
    | `get_community_template`   | One template's detail (description, remix/like/bookmark stats) plus similar templates. |
    | `remix_community_template` | Clone a template into a new project in a workspace you choose.                         |
  </Accordion>

  <Accordion title="Canvas (6)">
    | Tool            | What it does                                                              |
    | --------------- | ------------------------------------------------------------------------- |
    | `create_node`   | Start a generation as a visible node on a project's canvas.               |
    | `update_node`   | Regenerate an existing node in place with a new prompt or settings.       |
    | `layout_canvas` | Auto-arrange a project's nodes into a readable left-to-right layout.      |
    | `list_nodes`    | List a project's canvas nodes, read live from the collaboration document. |
    | `get_node`      | Poll one canvas node's live status and output.                            |
    | `connect_nodes` | Draw an edge so one node's output feeds another as a reference.           |
  </Accordion>

  <Accordion title="Generation (5)">
    | Tool             | What it does                                                    |
    | ---------------- | --------------------------------------------------------------- |
    | `generate_image` | Generate an image (spends credits).                             |
    | `generate_video` | Generate a video (spends credits).                              |
    | `generate_audio` | Generate audio: SFX or music (spends credits).                  |
    | `generate_3d`    | Generate a 3D model from 1–3 reference images (spends credits). |
    | `get_generation` | Poll a generation's status and read its output URLs.            |
  </Accordion>

  <Accordion title="Assets (2)">
    | Tool          | What it does                                                        |
    | ------------- | ------------------------------------------------------------------- |
    | `list_assets` | Browse a workspace's assets (images/videos/audio) with signed URLs. |
    | `get_asset`   | Fetch one asset by id with a fresh signed URL.                      |
  </Accordion>

  <Accordion title="Account & billing (4)">
    | Tool                | What it does                                                      |
    | ------------------- | ----------------------------------------------------------------- |
    | `get_account`       | The connected account: email, name, plan, account-wallet balance. |
    | `get_credits`       | A wallet's credit balance (total, blocked, available).            |
    | `list_workspaces`   | Every workspace the account can act in.                           |
    | `list_transactions` | The account's recent credit ledger.                               |
  </Accordion>

  <Accordion title="Projects (2)">
    | Tool             | What it does                          |
    | ---------------- | ------------------------------------- |
    | `list_projects`  | List the workspace's canvas projects. |
    | `create_project` | Create a new canvas project.          |
  </Accordion>

  <Accordion title="Brand kits (6)">
    | Tool                    | What it does                                                           |
    | ----------------------- | ---------------------------------------------------------------------- |
    | `list_brandkits`        | List the workspace's brand kits.                                       |
    | `get_brandkit`          | Fetch one brand kit with full colors, fonts, logos, and design tokens. |
    | `create_brandkit`       | Extract a brand kit from a website URL (async).                        |
    | `update_brandkit`       | Partially update a brand kit's fields.                                 |
    | `delete_brandkit`       | Permanently delete a brand kit.                                        |
    | `poll_brandkit_extract` | Check the status of an extraction started by `create_brandkit`.        |
  </Accordion>

  <Accordion title="Renders (3)">
    | Tool           | What it does                                                    |
    | -------------- | --------------------------------------------------------------- |
    | `start_render` | Render a composition timeline (Remotion JSON) to a final video. |
    | `get_render`   | Get one render's status by its workflow id.                     |
    | `list_renders` | Recent composition renders with their video URLs.               |
  </Accordion>

  <Accordion title="Flows (5)">
    | Tool          | What it does                                                         |
    | ------------- | -------------------------------------------------------------------- |
    | `list_flows`  | List the published flows (reusable apps) in the workspace.           |
    | `get_flow`    | One flow's input/output schema.                                      |
    | `run_flow`    | Start an async run of a flow (spends credits).                       |
    | `get_run`     | Poll a run's status and, once complete, its outputs.                 |
    | `create_flow` | Publish a canvas project as a reusable flow (requires `apps:write`). |
  </Accordion>

  <Accordion title="Skills (2)">
    | Tool          | What it does                                                         |
    | ------------- | -------------------------------------------------------------------- |
    | `list_skills` | List the [Flowy skills](/api/skills): expert step-by-step workflows. |
    | `load_skill`  | Load one skill's full instructions by name.                          |
  </Accordion>
</AccordionGroup>

## Connect from your agent

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
    claude mcp add --transport http --scope user flowy https://mcp.tryflowy.ai/mcp
    ```

    Or run it for you with the [CLI](/api/cli): `flowy mcp install --client claude`.
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={"theme":{"light":"github-light","dark":"vesper"}}
    { "mcpServers": { "flowy": { "url": "https://mcp.tryflowy.ai/mcp" } } }
    ```

    Or run `flowy mcp install --client cursor` from the [CLI](/api/cli).
  </Tab>

  <Tab title="Claude / Claude Desktop">
    In Settings → Connectors, add a custom connector with the URL
    `https://mcp.tryflowy.ai/mcp`. Claude discovers the OAuth flow
    automatically and prompts you to sign in.
  </Tab>

  <Tab title="ChatGPT">
    Enable Developer mode, then Settings → Apps → Developer mode → add an MCP
    server with the URL `https://mcp.tryflowy.ai/mcp`.
  </Tab>

  <Tab title="VS Code">
    Add an MCP server pointing at `https://mcp.tryflowy.ai/mcp` from the
    command palette's MCP server configuration (Streamable HTTP transport).
    VS Code drives the OAuth discovery flow the same way.
  </Tab>
</Tabs>

<Tip>
  Any other MCP-capable client can connect the same way: point it at
  `https://mcp.tryflowy.ai/mcp` over Streamable HTTP and let it run the
  [discovery flow](#discovery-flow) above.
</Tip>