> 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/tools/workspaces-and-projects.md).

# Workspace and project tools

Reference for the FLORA MCP tools that list workspaces, find, create, rename and open projects, and file them in folders.

These [FLORA MCP](https://flora.ai/mcp) tools find where work lives: the workspaces you can bill, the projects inside them, and the folders that file them. A connection isn't tied to one workspace, so tools take `workspace_id` per call and project tools resolve it from `project_id`. When several workspaces come back and none is current, the agent should name them and ask which one to bill.

| Tool                                                | What it does                                                                                     | Labels                 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------- |
| [`flora_list_workspaces`](#flora_list_workspaces)   | List the workspaces this account can use, and the current one when the user is already in one.   | read-only              |
| [`flora_list_projects`](#flora_list_projects)       | List a workspace's projects, most recently active first, with an optional name filter.           | read-only              |
| [`flora_get_project`](#flora_get_project)           | Read one project's metadata.                                                                     | read-only              |
| [`flora_create_project`](#flora_create_project)     | Create an empty project canvas in a workspace, optionally filed in a shared folder.              | writes                 |
| [`flora_list_folders`](#flora_list_folders)         | List a workspace's shared project folders with their IDs, names and project counts.              | read-only              |
| [`flora_rename_project`](#flora_rename_project)     | Rename a project (up to 120 characters).                                                         | writes                 |
| [`flora_open_project`](#flora_open_project)         | Create a one-time sign-in link that opens a project canvas in a browser tab the agent can drive. | writes                 |
| [`flora_projects`](#flora_projects)                 | Open FLORA's project browser from the client's sidebar.                                          | read-only, app UI only |
| [`flora_project_tray`](#flora_project_tray)         | Open FLORA's project tray beside a conversation.                                                 | read-only, app UI only |
| [`flora_mention_projects`](#flora_mention_projects) | Search projects for @-mentions while the user types in the client's message box.                 | read-only, app UI only |

## flora\_list\_workspaces <a href="#flora_list_workspaces" id="flora_list_workspaces"></a>

List the workspaces this account can use, and the current one when the user is already in one.

**Labels:** read-only

**Shown in clients as:** List workspaces

**Use when:** You need a `workspace_id`, or the user hasn't said which workspace to bill. If several come back and none is current, name them and ask which one to bill.

**Don't use when:** You already have a `project_id`. Project-scoped tools such as [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas) and [`flora_create_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_create_generations) resolve the workspace from it.

**Arguments**

None. Call it with `{}`.

**Returns:** `workspaces`, each with its `workspace_id` (`ws_…`), name and your role, plus `organization_id` (`org_…`) when it belongs to an organization. Also `current_workspace_id` when the connection is signed into a workspace.

**Cost:** Free. This tool doesn't spend money.

**Usually comes before:** [`flora_list_projects`](#flora_list_projects), [`flora_get_usage`](https://docs.flora.ai/mcp/tools/usage-sharing-and-comments.md#flora_get_usage)

**Example prompt:** "List my FLORA workspaces. Don't generate anything."

**Example call:**

```json
{}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
List the FLORA workspaces this account can use. For an existing project, use its own workspace: canvas tools with optional workspace_id resolve it from project_id, so no separate workspace lookup is needed. For operations that require choosing a workspace, use current_workspace_id when returned; it is the workspace the user is already in. Otherwise, if multiple workspaces come back, name them and ask which to bill — workspaces differ in plan and entitlements. Pair any explicit workspace_id with the project's own workspace; a mismatch is rejected.
```

{% endcode %}

</details>

## flora\_list\_projects <a href="#flora_list_projects" id="flora_list_projects"></a>

List a workspace's projects, most recently active first, with an optional name filter.

**Labels:** read-only

**Shown in clients as:** List projects

**Use when:** You need the `project_id` (`prj_…`) of an existing project, or want to show the user their recent projects.

**Don't use when:** The user wants a fresh canvas: use [`flora_create_project`](#flora_create_project). To read one project you already have the ID for, use [`flora_get_project`](#flora_get_project).

**Arguments**

| Argument       | Type   | Required | Notes                                                                                                                                                                                          |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace_id` | string | no       | Workspace to list (ws\_…), from flora\_list\_workspaces. Optional: when omitted, the connection's workspace or the caller's only workspace; with several workspaces the error names their ids. |
| `query`        | string | no       | Filter by project name.                                                                                                                                                                        |
| `visibility`   | string | no       | private: the caller's private projects. workspace: canvases shared with the whole workspace. Omit for everything the caller created. One of `private`, `workspace`.                            |
| `limit`        | number | no       | Max items to return (default 20).                                                                                                                                                              |
| `cursor`       | string | no       | Pagination cursor from a previous call's meta.next\_cursor.                                                                                                                                    |

**Returns:**

* `projects` (array of object)
* `meta` (object)

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_workspaces`](#flora_list_workspaces)

**Usually comes before:** [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas), [`flora_create_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_create_generations)

**Example prompt:** "Find my FLORA project called Spring campaign."

**Example call:**

```json
{
  "workspace_id": "ws_123",
  "query": "Spring campaign",
  "limit": 10
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
List projects in a workspace, most recently active first. workspace_id may be omitted when the caller has a single workspace (or the connection is signed into one). Without visibility, the caller's own projects; visibility narrows to their private ones or widens to every member's shared canvases. Project ids (prj_…) come from this response or an API-issued canvas URL; never guess one.
```

{% endcode %}

</details>

## flora\_get\_project <a href="#flora_get_project" id="flora_get_project"></a>

Read one project's metadata.

**Labels:** read-only

**Shown in clients as:** Get project

**Use when:** You have a `project_id` and need the project's details, such as its name or workspace.

**Don't use when:** You need what's on the canvas: use [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas). A bare ID without the `prj_` prefix isn't accepted.

**Arguments**

| Argument     | Type   | Required | Notes                                                                                                                                                                  |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id` | string | yes      | Project to read (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>. |

**Returns:**

* `project_id` (string): Project identifier
* `name` (string): Project name
* `thumbnail_url` (string (uri) or null): HTTPS project thumbnail URL, or null when unavailable. Uses the manual cover, then the automatic thumbnail, then the legacy project picture. Non-HTTPS URLs are returned as null.
* `is_private` (boolean): True when only the creator sees the project, rather than the whole workspace. Absent when the API cannot tell.
* `workspace_id` (string): Workspace identifier
* `origin` (string or null): Project origin
* `last_modified` (number or null)
* `created_at` (number)

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_projects`](#flora_list_projects)

**Usually comes before:** [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas)

**Example prompt:** "Show me the details of my Spring campaign project in FLORA."

**Example call:**

```json
{
  "project_id": "prj_abc"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Get one project's metadata. Pass project_id with the prj_ prefix from flora_list_projects or flora_create_project; an API-issued canvas URL's /projects/<id> segment becomes prj_<id>, while a bare ID is not accepted.
```

{% endcode %}

</details>

## flora\_create\_project <a href="#flora_create_project" id="flora_create_project"></a>

Create an empty project canvas in a workspace, optionally filed in a shared folder.

**Labels:** writes

**Shown in clients as:** Create project

**Use when:** The user wants new work kept apart from existing projects, or no suitable project exists yet.

**Don't use when:** The user named an existing project: find it with [`flora_list_projects`](#flora_list_projects) instead of creating a duplicate.

**Arguments**

| Argument       | Type   | Required | Notes                                                                                                                    |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `workspace_id` | string | yes      | Workspace to create in (ws\_…).                                                                                          |
| `name`         | string | yes      | Project name.                                                                                                            |
| `folder`       | string | no       | Shared project folder name to file the project under; created if missing. Existing names come from flora\_list\_folders. |

**Returns:** The new project, including its `project_id` (`prj_…`). A `folder` that doesn't exist yet is created.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_workspaces`](#flora_list_workspaces), [`flora_list_folders`](#flora_list_folders)

**Usually comes before:** [`flora_create_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_create_generations), [`flora_add_to_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_add_to_canvas)

**Example prompt:** "Create a FLORA project called Spring campaign in the Campaigns folder."

**Example call:**

```json
{
  "workspace_id": "ws_123",
  "name": "Spring campaign",
  "folder": "Campaigns"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Create an empty project canvas in a workspace. Pass folder to file it under a shared project folder with that name — the folder is created when it does not exist yet; list names with flora_list_folders first.
```

{% endcode %}

</details>

## flora\_list\_folders <a href="#flora_list_folders" id="flora_list_folders"></a>

List a workspace's shared project folders with their IDs, names and project counts.

**Labels:** read-only

**Shown in clients as:** List folders

**Use when:** The user wants a new project filed in a folder and you need the folder's exact name.

**Don't use when:** You're looking for projects: use [`flora_list_projects`](#flora_list_projects). Private folders never appear here.

**Arguments**

| Argument       | Type   | Required | Notes                      |
| -------------- | ------ | -------- | -------------------------- |
| `workspace_id` | string | yes      | Workspace to list (ws\_…). |

**Returns:** Shared folders in workspace order, each with its `folder_id` (`fld_…`), name and project count.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_workspaces`](#flora_list_workspaces)

**Usually comes before:** [`flora_create_project`](#flora_create_project)

**Example prompt:** "Which project folders does my FLORA workspace have?"

**Example call:**

```json
{
  "workspace_id": "ws_123"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
List a workspace's shared project folders — folder_id (fld_…), name and project count, in workspace order; private folders never appear. Pass a folder name as flora_create_project's folder to file new projects into it.
```

{% endcode %}

</details>

## flora\_rename\_project <a href="#flora_rename_project" id="flora_rename_project"></a>

Rename a project (up to 120 characters).

**Labels:** writes

**Shown in clients as:** Rename project

**Use when:** The user asks to rename a project.

**Don't use when:** The project is managed by a Generation Table or backs a Production. Rename it from that surface in the FLORA app.

**Arguments**

| Argument     | Type   | Required | Notes                                                                                                                                                                    |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `project_id` | string | yes      | Project to rename (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>. |
| `name`       | string | yes      | New project name.                                                                                                                                                        |

**Returns:** The renamed project. Surrounding whitespace is trimmed, and an empty name is rejected.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_projects`](#flora_list_projects)

**Example prompt:** "Rename my Spring campaign project to Spring campaign final."

**Example call:**

```json
{
  "project_id": "prj_abc",
  "name": "Spring campaign final"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Rename a project: pass project_id (prj_…) and the new name. The API allows up to 120 characters, trims surrounding whitespace, and rejects an empty result. Projects managed by a Generation Table or backing a Production cannot be renamed here — rename them from the owning surface.
```

{% endcode %}

</details>

## flora\_open\_project <a href="#flora_open_project" id="flora_open_project"></a>

Create a one-time sign-in link that opens a project canvas in a browser tab the agent can drive.

**Labels:** writes

**Shown in clients as:** Open project

**Use when:** Your agent has a browser tab and a JavaScript tool (Claude Code Desktop, Cowork or a similar host) and needs to work on the live canvas through FLORA's in-page WebMCP tools.

**Don't use when:** Your client has no browser tool, which is true of most chat clients. Read the project with [`flora_get_project`](#flora_get_project) and [`flora_get_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_get_canvas) instead. Never share the link or paste it in a reply: it signs in as the user.

{% hint style="info" %}
The `flora-open-project` skill walks through this flow. Load it with [`flora_discover_skills`](https://docs.flora.ai/mcp/tools/skills-and-discovery.md#flora_discover_skills).
{% endhint %}

**Arguments**

| Argument        | Type   | Required | Notes                                                                                                                                                                  |
| --------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`    | string | yes      | Project to open (prj\_…). Use project\_id from flora\_list\_projects or flora\_create\_project. An API-issued canvas URL's /projects/\<id> segment becomes prj\_\<id>. |
| `session_hours` | number | no       | Browser session length in hours, 1–24 (default 8).                                                                                                                     |

**Returns:** A one-time `url` that opens the canvas signed in as the user for `session_hours`. A `404` means the project ID is wrong or the user lacks access; report it and don't retry.

**Cost:** Free. This tool doesn't spend money.

**Usually comes after:** [`flora_list_projects`](#flora_list_projects)

**Example prompt:** "Open my Spring campaign project in your browser so you can edit the canvas directly."

**Example call:**

```json
{
  "project_id": "prj_abc",
  "session_hours": 2
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Create a single-use sign-in link that opens one project canvas in a browser, signed in as the user, for session_hours. One API operation; it changes nothing in the project and returns url, canvas_url and expires_at. Open url in a browser tab you control and navigate within that tab rather than reloading it; the canvas then behaves as it does for the user. Only useful in hosts that can open and operate a browser tab (Claude Code Desktop, Cowork, or similar); elsewhere read the project with flora_get_project and flora_get_canvas, and change it with the canvas tools, instead. The link works once and acts as the user — never share it or put it in a reply. A 404 means the project id is wrong or the caller lacks access — report it, do not retry.
```

{% endcode %}

</details>

## flora\_projects <a href="#flora_projects" id="flora_projects"></a>

Open FLORA's project browser from the client's sidebar.

**Labels:** read-only · app UI only

**Shown in clients as:** FLORA projects

**Use when:** Never as the agent. The user opens it from FLORA's entry in the ChatGPT sidebar to browse workspaces and projects.

**Don't use when:** You're the model: use [`flora_list_workspaces`](#flora_list_workspaces) and [`flora_list_projects`](#flora_list_projects).

**Arguments**

None.

**Returns:** The user's workspaces, which the client shows as FLORA's project browser.

**Cost:** Free. This tool doesn't spend money.

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Open the FLORA projects browser. Launched from the sidebar, not by the model.
```

{% endcode %}

</details>

## flora\_project\_tray <a href="#flora_project_tray" id="flora_project_tray"></a>

Open FLORA's project tray beside a conversation.

**Labels:** read-only · app UI only

**Shown in clients as:** Project tray

**Use when:** Never as the agent. The user opens it from a ChatGPT conversation's tabs, and the projects they pick become context for that conversation.

**Don't use when:** You're the model: use [`flora_list_workspaces`](#flora_list_workspaces) and [`flora_list_projects`](#flora_list_projects).

**Arguments**

None.

**Returns:** The user's workspaces, which the client shows as FLORA's project tray.

**Cost:** Free. This tool doesn't spend money.

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Open the FLORA project tray beside this conversation. Launched from the conversation's tabs, not by the model.
```

{% endcode %}

</details>

## flora\_mention\_projects <a href="#flora_mention_projects" id="flora_mention_projects"></a>

Search projects for @-mentions while the user types in the client's message box.

**Labels:** read-only · app UI only

**Shown in clients as:** Mention projects

**Use when:** Never as the agent. The client calls it as the user types `@` to mention a FLORA project.

**Don't use when:** You're the model looking for a project: use [`flora_list_projects`](#flora_list_projects) with `query`.

**Arguments**

| Argument | Type   | Required | Notes                            |
| -------- | ------ | -------- | -------------------------------- |
| `query`  | string | no       | Search text, which may be empty. |

**Returns:** Projects whose names match `query`, for the client's mention picker.

**Cost:** Free. This tool doesn't spend money.

**Example call:**

```json
{
  "query": "spring"
}
```

<details>

<summary>Full description from the server</summary>

{% code overflow="wrap" %}

```
Search FLORA projects for composer @-mentions. Called by the host as the user types, not by the model.
```

{% endcode %}

</details>


---

# 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/tools/workspaces-and-projects.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.
