name: flora-mcp-api-cli description: Use this skill whenever the user wants to generate image or video assets using Flora AI, Flora MCP, or Flora API. Triggers include "Flora", "Flora API", "Flora MCP", or requests to automate generations across Kling, Flux, Sora, or Veo using a single interface. Includes workflows for discovering techniques, running stills, stills-to-motion branching, batching with coding agents, and comprehensive troubleshooting.

Run FLORA MCP & API CLI

This skill teaches your agent how to use the FLORA MCP server and API to automate generative workflows. FLORA provides a single endpoint for all generative workloads, abstracting the complexities of multiple model providers. It allows access to over 60 image and video models (including Kling, Flux, Sora 2, and Veo 3.1) from a single credit pool and interface.

The FLORA MCP server lets any Model Context Protocol (MCP) client — Claude, Cursor, VS Code, Hermes Agent, OpenClaw, and others — discover and run Techniques in plain English without API wiring.

When to use FLORA

Reach for FLORA when the user wants:

• To generate assets across different model families without managing multiple API keys.
• To execute complex workflows (Techniques) that combine multiple steps (e.g., Image Generation -> Video Generation -> Upscaling).
• To leverage "Fauna" capabilities (infinite canvas, node-based workflows).
• To easily branch and iterate on previously generated assets.
• To batch generate variants via a script or coding agent.

Do not reach for FLORA when:

• The user specifically requests raw access to a native provider's API (e.g., raw Kling JWT auth) to utilize provider-specific endpoints not exposed by Flora.

Installation & Authentication

Using MCP (For Agents)

FLORA MCP uses OAuth 2.1 with PKCE.

1. The first tool call triggers an OAuth flow in the browser.
2. The user signs in with their FLORA account at app.flora.ai.
3. The client stores a token scoped to the workspace locally. Future calls happen silently.

Using API/CLI (For Developers)

Use the API key flow (Authorization: Bearer sk_live_...) for server-side automation, backend jobs, and CI.

Available MCP Tools

FLORA MCP mirrors the FLORA REST API 1:1.

| Resource | Tools | When the agent uses it | | :--- | :--- | :--- | | Techniques | list_techniques, retrieve_technique, create_technique_run, retrieve_technique_run | "What Techniques do I have?", "run this Technique", polling runs | | Runs | start_technique_run, start_generation_run | Chaining earlier results or generic generations without a Technique | | Assets | create_asset, complete_asset, retry_asset, list_assets, retrieve_asset | User provides local file; agent uploads via signed URL to pass as inputs | | Projects | list_projects, create_project, retrieve_project, list_project_nodes, attach_project_asset | Organizing runs into projects in FLORA | | Workspaces | list_workspaces | Resolving workspaces after OAuth or if user has multiple | | Models | list_models | Finding model IDs for generic workflows | | Feedback | record_feedback | User wants to send feedback to the FLORA team |

The Core Loop: Discover and Run

1. list_techniques: Filter the Technique library for generators (e.g., list_techniques(query="thumbnail")).
2. retrieve_technique: Inspect the Technique's input schema (e.g., theme, audience, brand_directives).
3. create_technique_run: Map the brief onto the inputs and submit the run with a count parameter.
4. retrieve_technique_run: Poll the run until status: "completed". Render outputs inline.

Advanced Workflows

Iterate on Favorites

Refer to outputs by position: "Love #4 and #7. Make 5 more variations of those." Extract the asset IDs/URLs and re-run the Technique passing them as references.

Stills to Motion

Branch from stills to motion without losing context.

1. User says "Now take the winners and run them through the Social Motion Technique."
2. Switch to background mode (Cowork, Agent Run) if supported.
3. Find the motion Technique and run it, passing the still URLs as keyframe inputs. duration and loop can also be passed.
4. Poll independently and return inline MP4 previews.

Batch with a Coding Agent

For 10-50+ runs (e.g., localizing for 12 markets):

1. Pair FLORA MCP with external data tools (Drive, CSV).
2. The agent drafts a script to iterate over rows.
3. Call create_technique_run inside the loop with parallelization limits (e.g., --max-concurrent 4).
4. Download outputs or attach_project_asset after each completion.

Prompting Tips for the User

• Name the Technique: "Use the Thumbnail v3 Technique" skips discovery.
• Lead with structure: Structured briefs help the agent map inputs correctly (e.g., Do's/Don'ts lists).
• Ask for inspection: Ask the agent to confirm cost first for big batches (using run_cost from retrieve_technique).
• Tell the agent when to stop: "Generate one, show it to me, only continue if I approve."
• Switch surfaces explicitly: "Do this in the background" vs "Stay inline".
• Course-correct: "#3 has the wrong headline — re-run that one with X."

Troubleshooting

• OAuth browser doesn't open: Find the auth URL in the agent logs/output and open it manually.
• Failed to connect: Verify network via curl -I https://agents.flora.ai/mcp. Check corporate VPNs or proxies.
• 401 invalid_token: Re-authenticate the client or clear auth cache.
• 402 insufficient_credits: Top up the workspace balance in FLORA -> Settings -> Billing.
• 403 forbidden: User lacks permission for the operation (e.g., wrong workspace, archived technique). Call list_workspaces to check.
• input_validation_error: Run retrieve_technique to check the updated schema.
• Images don't render: Ensure the client supports image block rendering.
• Polling feels slow: Move long tasks to background mode. Techniques take up to 30s+.

Limitations

• No streaming inside a single run. Multi-output runs appear tile-by-tile.
• No webhooks; all result-checking happens via polling.
• Cannot edit assets in place; must run through a Technique producing a new asset.