> 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/quickstart.md).

# FLORA MCP quickstart: your first generation

Connect FLORA MCP to your AI client, check the connection, then quote, approve and generate your first image on a FLORA canvas.

This page takes you from nothing to one generated image on a FLORA canvas in about five minutes, with the cost shown in US dollars before anything runs. It works the same in any client that has [FLORA MCP](https://flora.ai/mcp) connected.

**You need:** an AI client such as Claude, Claude Code, ChatGPT, Codex or Cursor, and a FLORA workspace with a few cents of balance. Starter and above include API and MCP; a Free account can generate on the $2.50 of usage every new workspace gets, which covers this quickstart. See [How FLORA pricing works](https://docs.flora.ai/plans-and-billing/pricing.md).

{% stepper %}
{% step %}

### Connect FLORA to your client

Pick your client and follow its page. Each takes a minute.

| Client                                                                  | Fastest route                                                                                                  |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| [Claude (web and Desktop)](https://docs.flora.ai/mcp/install/claude.md) | **Customize → Connectors → Add custom connector**, paste `https://agents.flora.ai/mcp`                         |
| [ChatGPT](https://docs.flora.ai/mcp/install/chatgpt.md)                 | Open the [FLORA app](https://chatgpt.com/plugins/plugin_asdk_app_6a8c516c7e308191a0091f1b9c98a621) and connect |
| [Claude Code](https://docs.flora.ai/mcp/install/claude-code.md)         | `claude mcp add --transport http flora https://agents.flora.ai/mcp`                                            |
| [Codex](https://docs.flora.ai/mcp/install/codex.md)                     | `codex mcp add flora --url https://agents.flora.ai/mcp`                                                        |
| [Cursor](https://docs.flora.ai/mcp/install/cursor.md)                   | One-click install, or add `flora` to `~/.cursor/mcp.json`                                                      |
| [Anything else](https://docs.flora.ai/mcp/install/other-clients.md)     | Server URL `https://agents.flora.ai/mcp`, Streamable HTTP, OAuth                                               |

Your browser opens FLORA's sign-in page. Sign in with the account you use at [app.flora.ai](https://app.flora.ai), then return to your client. See [Authentication](https://docs.flora.ai/mcp/authentication.md) for what happens during sign-in.
{% endstep %}

{% step %}

### Check the connection

Ask your agent:

> List my FLORA workspaces. Don't generate anything.

<a href="https://claude.ai/new?q=List%20my%20FLORA%20workspaces.%20Don%27t%20generate%20anything." class="button secondary">Open in Claude</a> <a href="https://chatgpt.com/?q=List%20my%20FLORA%20workspaces.%20Don%27t%20generate%20anything." class="button secondary">Open in ChatGPT</a>

The agent calls `flora_list_workspaces` with no arguments:

```json
{}
```

It gets back every workspace your account can use. `current_workspace_id` appears when you're already working in one:

```json
{
  "workspaces": [
    {
      "workspace_id": "ws_123",
      "name": "Brand Studio",
      "role": "admin",
      "organization_id": "org_456",
      "organization_name": "Acme Inc",
      "created_at": 1767225600000
    },
    {
      "workspace_id": "ws_789",
      "name": "Personal",
      "role": "editor",
      "organization_id": "org_012",
      "created_at": 1759276800000
    }
  ],
  "current_workspace_id": "ws_123"
}
```

If you see your workspaces, you're connected. If several come back and none is current, the agent should name them and ask which one to bill. Tell it.
{% endstep %}

{% step %}

### Ask for an image, and get a quote first

Ask your agent:

> In FLORA, create a project called "MCP quickstart" and make one image: a ripe lemon on a cobalt blue background, studio light. Quote the cost in US dollars first and wait for my OK.

<a href="https://claude.ai/new?q=In%20FLORA%2C%20create%20a%20project%20called%20%22MCP%20quickstart%22%20and%20make%20one%20image%3A%20a%20ripe%20lemon%20on%20a%20cobalt%20blue%20background%2C%20studio%20light.%20Quote%20the%20cost%20in%20US%20dollars%20first%20and%20wait%20for%20my%20OK." class="button secondary">Open in Claude</a> <a href="https://chatgpt.com/?q=In%20FLORA%2C%20create%20a%20project%20called%20%22MCP%20quickstart%22%20and%20make%20one%20image%3A%20a%20ripe%20lemon%20on%20a%20cobalt%20blue%20background%2C%20studio%20light.%20Quote%20the%20cost%20in%20US%20dollars%20first%20and%20wait%20for%20my%20OK." class="button secondary">Open in ChatGPT</a>

The agent creates the project with `flora_create_project`. This is free:

```json
{
  "workspace_id": "ws_123",
  "name": "MCP quickstart"
}
```

Then it prices the image with `flora_create_generations` and `quote: true`. A quote reserves nothing and starts nothing:

```json
{
  "quote": true,
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "model": "t2i-gemini-3.1-flash-image",
      "prompt": "A ripe lemon on a cobalt blue background, studio light"
    }
  ]
}
```

The quote comes back in US dollars (response trimmed). It has no `run_id`, because nothing ran:

```json
{
  "generations": [
    {
      "index": 0,
      "ok": true,
      "type": "generation_quote",
      "model": { "model_id": "t2i-gemini-3.1-flash-image" },
      "estimated_cost": 0.072,
      "currency": "USD",
      "is_estimate": true,
      "quoted_at": "2026-10-11T18:00:00.000Z",
      "expires_at": "2026-10-11T18:05:00.000Z",
      "assumptions": [
        "Not a price lock. Final usage, discounts, routing, model prices, and reference outputs can change the final charge; requote after expiry."
      ]
    }
  ]
}
```

The agent tells you something like "This costs about $0.07. Go ahead?" A quote is an estimate, not a price lock, and it expires after five minutes. Prices vary by model; see [Model Pricing](https://docs.flora.ai/plans-and-billing/model-pricing.md).
{% endstep %}

{% step %}

### Approve, and the agent generates

Reply "Yes". The agent sends the same request without `quote`:

```json
{
  "generations": [
    {
      "project_id": "prj_abc",
      "type": "image",
      "model": "t2i-gemini-3.1-flash-image",
      "prompt": "A ripe lemon on a cobalt blue background, studio light"
    }
  ]
}
```

The response confirms the run started and where it lives on the canvas:

```json
{
  "generations": [
    {
      "index": 0,
      "ok": true,
      "run_id": "run_123",
      "type": "generation",
      "model": { "model_id": "t2i-gemini-3.1-flash-image" },
      "estimated_seconds": 65,
      "node_id": "n1",
      "canvas_url": "https://app.flora.ai/projects/abc"
    }
  ]
}
```

{% endstep %}

{% step %}

### Wait, then read the result

Images take tens of seconds. The agent waits at least 15 seconds, then reads the run with `flora_list_generations`:

```json
{
  "run_ids": ["run_123"]
}
```

When `status` is `completed`, the output URL and the final cost are in the response:

```json
{
  "runs": [
    {
      "run_id": "run_123",
      "status": "completed",
      "charged_cost": 0.072,
      "outputs": [
        {
          "output_id": "output_1",
          "type": "imageUrl",
          "url": "https://media.flora.ai/output.png",
          "asset_id": "asset_abc"
        }
      ]
    }
  ]
}
```

If it's still `pending` or `running`, the agent waits another 15 seconds and reads again. `charged_cost` is in US dollars.
{% endstep %}

{% step %}

### Open it on the canvas

The agent gives you the `canvas_url` from step 4. Open it: your image is a node on the **MCP quickstart** canvas, ready to edit, reuse as a reference, or build on in FLORA.
{% endstep %}
{% endstepper %}

## If it fails

| Symptom                                               | Cause                                                                                          | Fix                                                                                                                                                         |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The agent says it has no FLORA tools                  | The connector is off for this chat, or sign-in didn't finish                                   | Turn FLORA on in your client's tools menu, or reconnect. See your [client's install page](https://docs.flora.ai/mcp/install.md).                            |
| `401` or "Missing or invalid access token"            | Not signed in, or the sign-in expired                                                          | Reconnect FLORA in your client and sign in again.                                                                                                           |
| `paid_plan_required` (HTTP 403)                       | The workspace's plan doesn't include what you asked for, such as API access or another feature | Adding balance won't fix it. Pick a workspace whose plan includes it, or see [How FLORA pricing works](https://docs.flora.ai/plans-and-billing/pricing.md). |
| `insufficient_credits` or a `BILLING_*` error         | Not enough balance in that workspace, or a spending limit was hit                              | Stop. Read the message the agent relays, then add balance or pick another workspace. Don't retry.                                                           |
| `429`, or a cooldown error with `retry_after_seconds` | The agent polled too soon                                                                      | Wait the number of seconds given, then read again. See [Runs](https://docs.flora.ai/mcp/runs.md).                                                           |
| The run shows `failed`                                | The model rejected the prompt or input, or the provider failed                                 | Read `error_message`, change the prompt, and generate again. A retry is billed again.                                                                       |

More fixes: [Troubleshooting](https://docs.flora.ai/mcp/troubleshooting.md).

## Next steps

* [Generate an image or video](https://docs.flora.ai/mcp/recipes/generate.md) with references, other models, and video.
* [Batch-generate 20 to 500 assets](https://docs.flora.ai/mcp/recipes/batch.md) from a list.
* [Run your team's Technique](https://docs.flora.ai/mcp/recipes/run-a-technique.md).
* [Cost, balance and limits](https://docs.flora.ai/mcp/cost-and-limits.md): check your balance with `flora_get_usage`.


---

# 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/quickstart.md?ask=<question>&goal=<user_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.
