> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp.md). # FLORA MCP documentation Connect FLORA to Claude, Claude Code, ChatGPT, Codex, Cursor or any MCP client so your agent can generate, run Techniques and build on your FLORA canvases. [FLORA MCP](https://flora.ai/mcp) is FLORA's hosted MCP server. Connect it once and your AI agent can generate images, video, audio, text and 3D, run your team's Techniques, and put the results on your FLORA canvases. These docs cover installing it, what each tool does, and the rules your agent follows. | Setting | Value | | -------------- | ------------------------------------------------------------------------------------------------------------------ | | Server URL | `https://agents.flora.ai/mcp` (no trailing slash) | | Transport | Streamable HTTP. It's a remote server, so there's nothing to install. | | Sign-in | OAuth with your FLORA account. Headless clients can send a FLORA API key as `Authorization: Bearer ` instead. | | Server name | `flora` | | Check it works | Ask your agent: "List my FLORA workspaces. Don't generate anything." | * **Who can connect:** API and MCP are included from Starter up. A Free account can also connect and generate on the $2.50 of usage every new workspace gets. Each generation is billed in US dollars to the workspace you choose. See [How FLORA pricing works](/plans-and-billing/pricing.md) and [Authentication](/mcp/authentication.md#who-can-connect). * **Skills:** tested workflows (batch generation, refine loops, Technique runs and more) live at [github.com/florafauna-ai/flora-mcp-skills](https://github.com/florafauna-ai/flora-mcp-skills). Your agent lists them with `flora_discover_skills`. See [Skills and plugins](/mcp/skills.md). * **For agents:** every page here is also Markdown. Append `.md` to any URL, for example . The full index is . ## Install in your client
ClaudeWeb and Desktop. Add a custom connector.Claude
Claude CodeOne command, or the plugin with skills.Claude Code
ChatGPTFLORA is listed in ChatGPT. Click Connect.ChatGPT
CodexOne command or config.toml.Codex
CursorOne-click install or mcp.json.Cursor
VS CodeOne command or .mcp.json.VS Code
Other clientsWindsurf, Gemini CLI, Copilot Studio, Hermes, OpenClaw and any MCP client.Other clients
New to FLORA MCP? The [quickstart](/mcp/quickstart.md) takes you from connecting to your first image on a canvas. ## Start here: eight tools Your connection has more tools than these (the list depends on your account, plan and client; `flora_list_tools` returns the ones you have). Most jobs start with these eight. | Tool | What it does | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | [`flora_list_workspaces`](/mcp/tools/workspaces-and-projects.md#flora_list_workspaces) | Lists the workspaces you can use, and which one you're in. Read-only. | | [`flora_list_projects`](/mcp/tools/workspaces-and-projects.md#flora_list_projects) | Lists projects (canvases) in a workspace. Read-only. | | [`flora_list_models`](/mcp/tools/models-and-loras.md#flora_list_models) | Lists models with their `model_id`, estimated cost and parameters. Read-only. | | [`flora_create_generations`](/mcp/tools/generations.md#flora_create_generations) | Starts 1 to 20 generations on a canvas, or quotes their cost with `quote: true`. Spends money. | | [`flora_list_generations`](/mcp/tools/generations.md#flora_list_generations) | Reads up to 20 runs by `run_id`, or lists history. Read-only. | | [`flora_create_asset`](/mcp/tools/assets.md#flora_create_asset) | Brings your own files into FLORA from a URL or an upload link. | | [`flora_run_technique`](/mcp/tools/techniques-and-actions.md#flora_run_technique) | Runs one of your team's Techniques. Spends money. | | [`flora_get_usage`](/mcp/tools/usage-sharing-and-comments.md#flora_get_usage) | Reads balance and spend in US dollars for a workspace or organization. Read-only. | The full list, with arguments and examples, is in the [tools reference](/mcp/tools.md). ## What your agent can do | Job | Recipe | | ------------------------------------------------------------------------ | ----------------------------------------------------------------------- | | Make an image, video, audio clip or 3D model from a prompt or references | [Generate an image or video](/mcp/recipes/generate.md) | | Animate a product photo | [Turn a product photo into video](/mcp/recipes/image-to-video.md) | | Make 20 to 500 assets from a list or sheet | [Batch-generate 20 to 500 assets](/mcp/recipes/batch.md) | | Run a Technique your team built | [Run your team's Technique](/mcp/recipes/run-a-technique.md) | | Use your own images, video, audio or PDFs | [Upload your own images, video and files](/mcp/recipes/upload-files.md) | | Lay results out on a canvas | [Put results on a canvas](/mcp/recipes/canvas.md) | | Make more like the ones you liked | [Iterate on favorites](/mcp/recipes/iterate.md) | | Get better results from your prompts | [Brief your agent for better output](/mcp/recipes/prompting.md) | All recipes are indexed in [Recipes](/mcp/recipes.md). ### Tool sequences for common jobs | Job | Calls, in order | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | First image | `flora_list_workspaces` → `flora_list_projects` (or `flora_create_project`) → `flora_create_generations` with `quote: true` → approval → `flora_create_generations` → `flora_list_generations` | | Video from a photo URL | `flora_list_workspaces` → `flora_list_projects` → `flora_list_models` with the video `model_id` (to read its image field name) → quote → `flora_create_generations` with the URL in `params` → `flora_list_generations` | | Cost and balance | `flora_list_models` (`estimated_cost_usd`) or a `quote: true` call → `flora_get_usage` | | Run a Technique | `flora_list_techniques` → `flora_get_technique` → `flora_run_technique` → `flora_list_generations` with `run_ids` and `technique_id` | | Use a local file | `flora_create_asset` with `source: "signed-url"` → upload (shell) or `upload_page` link (chat) → `flora_complete_asset` | | Grid on a canvas | `flora_get_canvas` → `flora_arrange_canvas` with `node_ids` and `layout`, or `all: true` alone | | Animate a canvas image | `flora_add_to_canvas` (video node wired to the image) → `flora_run_canvas_nodes` → `flora_list_generations` | ## Rules your agent follows The server gives agents these rules. They're here so you know what to expect, and so you can hold your agent to them. * **Ask which workspace to bill.** A connection isn't tied to one workspace. If several come back from `flora_list_workspaces` and none is current, the agent names them and asks you which to bill. Project tools bill the project's own workspace. * **Quote first, in US dollars.** The agent calls `flora_create_generations` with `quote: true`, shows you the cost in US dollars (never credits), and runs the same request without `quote` only after you approve. `run_cost` and `charged_cost` are dollars: `0.009` means $0.009. A failed run isn't charged; a retry is a new run and is billed again. Details: [Cost, balance and limits](/mcp/cost-and-limits.md). * **Stop on billing errors.** On `insufficient_credits` or any `BILLING_*` error, the agent stops and passes the message on. It doesn't retry. `paid_plan_required` means the workspace's plan doesn't include what was asked. Balance and spend come from `flora_get_usage`. * **Poll slowly, in one call.** The agent saves every `run_id`, waits `max(15, 2 × number of runs)` seconds between polls (15 seconds for up to 7 runs, 40 seconds for 20), and reads all of them in one `flora_list_generations` call (up to 20 `run_ids`, plus `technique_id` for Technique runs). Faster polling returns `429` or cooldown errors with `retry_after_seconds`. Details: [Runs](/mcp/runs.md). * **Never re-fire a partial batch.** Items that started already cost money, and a timed-out call may still have started a run. The agent reads history before trying again. See [Runs](/mcp/runs.md). * **Link with `canvas_url`.** The agent opens results with the `canvas_url` each generation returns and never builds project links from IDs. ## FLORA MCP, fal, Replicate or a model provider's API? Model APIs and aggregators like fal and Replicate return a model's raw output to your code. FLORA MCP is built for creative work with an agent: * **Results land on a canvas.** Every generation becomes a node on a FLORA project your team can open, compare, edit and build on, not a file URL in a chat log. * **Your team's workflows come along.** Your agent can run the Techniques your team saved, and use FLORA's skills. * **Team billing and controls.** Workspaces, members, roles, per-workspace spend limits and usage reporting apply to agent runs too. Prices are FLORA's published per-generation rates on [Model Pricing](/plans-and-billing/model-pricing.md), the same as in the app. * **One connection, many model families.** Image, video, audio, text and 3D models from several providers behind one sign-in. If you only need one model's output inside your own app, with no canvas or team workspace, a provider's API or an aggregator may fit better. To call FLORA from your own code, use the [FLORA API](/api.md). ## Terms | Term | Meaning | | --------- | ------------------------------------------------------------------------------------------------- | | Workspace | Where projects live and where usage is billed. You can belong to several. IDs look like `ws_123`. | | Project | One FLORA canvas and its contents. IDs look like `prj_abc`. | | Canvas | The board inside a project where nodes sit and connect. | | Node | One block on a canvas: an image, video, text, Technique or other step. Generations land as nodes. | | Run | One generation or Technique execution, tracked by its `run_id`. | | Technique | A saved, reusable workflow your team built in FLORA. See [Techniques](/nodes/techniques.md). | | Asset | A file in FLORA, uploaded or generated, with an `asset_id`. | | Skill | Written instructions an agent follows for a bigger job, listed by `flora_discover_skills`. | ## Everything in these docs * [Quickstart](/mcp/quickstart.md): connect, check, and make your first image. * [Install](/mcp/install.md): steps for every client. * [Authentication](/mcp/authentication.md): OAuth, API keys, workspaces, and disconnecting. * [Cost, balance and limits](/mcp/cost-and-limits.md): quotes, balance, and billing errors. * [Runs](/mcp/runs.md): polling, timeouts and failures. * [Recipes](/mcp/recipes.md): step-by-step jobs. * [Tools reference](/mcp/tools.md): every tool and its arguments. * [Skills and plugins](/mcp/skills.md): tested workflows and how to install them. * [Troubleshooting](/mcp/troubleshooting.md): symptoms, causes and fixes. * [Security and data](/mcp/security.md): what leaves FLORA and what your agent can do. * [Changelog](/mcp/changelog.md): what changed and when. * [Retired tools](/mcp/retired-tools.md): older tool names and what replaced them. * [FLORA API](/api.md): call FLORA from your own code with an API key. ## Watch: Everything About FLORA MCP {% embed url="" %} An introduction to FLORA MCP from the FLORA team. {% endembed %} Need help? Email . --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.flora.ai/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.