For the complete documentation index, see llms.txt. This page is also available as Markdown.

FLORA MCP authentication

How FLORA MCP signs you in with OAuth or a FLORA API key, how agents pick the workspace to bill, and how to disconnect a client or revoke a key.

FLORA MCP signs you in with your FLORA account over OAuth, so you never paste a key into Claude, ChatGPT or Cursor. For headless setups such as CI jobs and scripts, it also accepts a FLORA API key in the Authorization header.

OAuth (default)
API key

Use for

Chat and coding clients a person uses

CI, scripts, servers, clients that can't open a browser

How it connects

Your client opens FLORA's sign-in page once

Authorization: Bearer <key> on every request

Acts as

You, in every workspace you belong to

You, in the workspaces and with the permissions chosen for the key

Stored by

Your client

You (environment variable or secrets manager)

Turn it off

Remove FLORA in the client

Revoke the key in FLORA, and remove it from the client

Who can connect

API and MCP are included from Starter up. A Free account can also connect and try FLORA MCP on the $2.50 of usage every new workspace gets. What you can do depends on the workspace you pick:

  • Starter, Pro, Max and Enterprise workspaces include API and MCP access. Generations spend the workspace's usage in US dollars. See How FLORA pricing works.

  • Free workspaces can connect, read and generate. Generations spend the $2.50 of usage every new workspace gets, the same as in the app; there's no separate MCP trial. Reading is free. When that usage is spent, generations stop with a billing error (insufficient_credits or BILLING_*). Ongoing use needs Starter or above.

  • paid_plan_required (HTTP 403) means the workspace's plan doesn't include what was asked for, such as API access or another feature. Adding balance doesn't fix it. Pick a workspace whose plan includes it, or ask your FLORA admin about upgrading.

How sign-in works

FLORA MCP is a hosted server at agents.flora.ai. Your client sends tool calls to it over HTTPS. Web clients such as Claude and ChatGPT connect from their own servers, not from your computer.

  1. Your client calls https://agents.flora.ai/mcp without a token and gets 401 Unauthorized. The WWW-Authenticate header points to https://agents.flora.ai/.well-known/oauth-protected-resource/mcp. This 401 is normal: it's how clients discover sign-in.

  2. The client registers itself with FLORA automatically (dynamic client registration). You don't need a client ID or secret; leave any OAuth fields in your client empty.

  3. Your browser opens FLORA's sign-in page on clerk.flora.ai. Sign in with the account you use at app.flora.ai. If you're already signed in to FLORA in that browser, this step can be quick.

  4. FLORA asks for your basic profile and email, plus offline access so your client can stay signed in.

  5. The browser hands you back to your client, which stores the tokens and refreshes them as needed. You sign in again only if the refresh fails or you disconnect.

There's no workspace picker at sign-in. One connection reaches every workspace your account belongs to (see Workspaces).

For client developers, the OAuth endpoints are:

Endpoint
URL

Protected resource metadata

https://agents.flora.ai/.well-known/oauth-protected-resource/mcp

Authorization server metadata

https://agents.flora.ai/.well-known/oauth-authorization-server

Authorize

https://agents.flora.ai/authorize

Token (also token revocation)

https://agents.flora.ai/token

Dynamic client registration

https://agents.flora.ai/register

FLORA supports the authorization code grant with PKCE (S256) and refresh tokens.

What the connection can do

The connection acts as you. It can do what your FLORA role allows in each workspace, and nothing more:

  • Read workspaces, projects, canvases, models, Techniques, assets and run history.

  • Create projects, add and change nodes, upload assets, and share projects, where your role allows it.

  • Start generations and Technique runs, which spend the workspace's balance in US dollars.

  • Read balance and spend with flora_get_usage (spend totals need billing permission).

No tool manages plans, payment methods or workspace members. Do that in the FLORA app.

Workspaces: chosen per call

A connection isn't scoped to one workspace. Tools take workspace_id on each call, and tools that work on a project use that project's own workspace (from project_id). If you pass both and they don't match, the call is rejected. One exception: flora_run_technique takes no workspace_id and bills the connection's default workspace. See Run your team's Technique.

flora_list_workspaces returns every workspace you can use, with current_workspace_id when you're already working in one:

Ask which workspace to bill. Workspaces differ in plan, balance and model access. When the agent needs a workspace for a new project or generation:

  • If current_workspace_id is present, it uses that one.

  • If you have one workspace, it uses that one.

  • If several come back and none is current, it names them and asks you which to bill. It doesn't guess.

You can always tell it up front: "Use my Client work workspace."

API keys for headless setups

Use an API key when no person is there to sign in through a browser. FLORA MCP accepts any FLORA API key (keys start with ak_; older flora_sk_ keys also work) as a bearer token:

Create a key

  1. Sign in to FLORA and open Settings → API Keys. In an organization, open Settings, choose the workspace under Workspaces, and find API Keys under Security.

  2. Click Create API Key and name it.

  3. Choose the workspaces it can reach and its permissions in each: Read, Write (needed to generate, upload and edit canvases) and Billing (needed for flora_get_usage).

  4. Copy the key from the API Key Created dialog. It isn't shown again.

You can hold up to five active keys. Admins can always create keys. Editors can too, unless an admin turns off Allow editors to create API keys in the workspace's settings. Full details: API authentication.

Add the key to your client

Claude Code:

A JSON config that supports headers:

Keep the key out of anything you commit. Check how your client expands environment variables before you rely on ${...}.

Disconnect and revoke

Removing FLORA from your client deletes the tokens it stored for FLORA. Do it in each client you connected:

Client
How to disconnect

Claude (web and Desktop)

Claude Code

claude mcp remove flora, or uninstall the plugin (its server is plugin:flora-mcp-skills:flora). See Claude Code: Remove

Codex

codex mcp logout flora, then codex mcp remove flora

Cursor

VS Code

Clients using mcp-remote

Remove the server from the config, then delete ~/.mcp-auth

Revoke an API key: in FLORA, open API Keys, click Revoke next to the key, and confirm. Anything using it loses access right away. Revoking can't be undone.

FLORA doesn't list OAuth connections in its settings. If a device with a connected client is lost or shared, remove FLORA from that client if you can, revoke any API keys it used, and email [email protected].

Admin controls

Admins control agent access through the same settings that govern the FLORA app:

Control
Where
Effect on MCP

Plan

Plans & Billing

API and MCP access follow the workspace's plan. Without it, tools return paid_plan_required.

Roles

Members & Roles or People & Seats

An agent can do only what its user's role allows.

Allow editors to create API keys

Workspace settings, API key access

Off: only admins can create keys for the workspace.

Model access

Workspace settings, Model access

Models an admin turns off are left out of flora_list_models.

Spending limits

Member and workspace limits

Agent generations count against them. When one is hit, generation returns a BILLING_* error and the agent stops.

On Claude Team and Enterprise, an owner also decides which connectors members can add. See Install in Claude.

Last updated

Was this helpful?