--- title: Floyo MCP slug: floyo-mcp icon: 🤖 createdAt: 2026-08-03T13:28:05.501Z --- ::embed[]{url="https://youtu.be/osHIAH08XNs?si=bG2v0LEAZjpVyt8v"} Use Floyo MCP to connect AI agents to Floyo over the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, your agent can discover workflows, start runs, inspect outputs, and upload files into your team’s private storage — all from chat, without opening the Floyo app. **Ask your AI to build it** Connect Floyo to the AI assistant you already use. Every workflow on the platform, available right in the chat. Works with **Claude · ChatGPT · Cursor · Codex · Antigravity** and any MCP-compatible client. 1. **Find the right workflow** — Describe what you're making. Your assistant searches every workflow on Floyo, picks the best fit, and tells you why. 2. **Run it and get your outputs** — Hand it your images, let it run the workflow, and get the finished files back without leaving the chat. 3. **Your team's workflows too** — Point it at a team and its private workflows, files, run history and costs are all there. ## Introduction **Floyo MCP** is a remote MCP server hosted by Floyo. Your agent talks to the server over HTTPS; the server translates tool calls into authenticated requests to Floyo on your behalf. Workflows execute on Floyo infrastructure, so you do not need a local GPU. :::hint{type="success"} MCP Server URL: `https://mcp.floyo.ai/mcp` ::: Any MCP-compatible client that supports remote HTTP transport and OAuth can connect. This page covers first-class setup for Claude Desktop / Web, Claude Code, ChatGPT, Codex, Cursor, Antigravity IDE, and Antigravity CLI. :::hint{type="info"} Prefer raw HTTP and API keys for scripts or CI? See [Floyo API - Introduction](https://docs.floyo.ai/floyo-api-introduction) instead. Floyo MCP is designed for interactive agents and uses **Floyo OAuth** — you never paste a Floyo API key into your agent config. ::: *** ## Install Instructions You need a [Floyo](https://www.floyo.ai) account before connecting. During setup, your client opens a browser so you can sign in with Floyo OAuth and approve access. Open the client you use: :::ExpandableHeading ### Claude Desktop / Web Claude connects Floyo as a **custom connector**, then completes Floyo OAuth in the browser. You can add the Floyo MCP to Claude with a one-click link or set it up manually through the Settings panel. **ONE-CLICK Installation: **:InlineCtaButton[]{label="Add Floyo MCP to Claude" docId docAnchorId externalHref="https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Floyo&connectorUrl=https%3A%2F%2Fmcp.floyo.ai%2Fmcp" openInNewTab="true" noFollow="false"} **MANUAL Installation:** 1. Open Settings panel 2. Open **Customize → Connectors** (on [claude.ai](https://claude.ai) or in Claude Desktop). ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/yB5q1aIYBZX6SsuXSfZpd_image.png) 3. Add a custom connector named **Floyo **and set the remote MCP server URL to `https://mcp.floyo.ai/mcp`. Click **Add **to save the connector. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/y2LFRl9vl2R1gdkRjhl9I_image.png) **Authenticate with Floyo** After adding the MCP using either method, you’ll be prompted to connect. Click **Connect**, then complete the OAuth authentication flow in the browser window that opens. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/tM66nSrLiC74g8fPk2Ndf_image.png) After connecting, ask in plain language — for example, “list my Floyo teams” or “find a text-to-image workflow on my team.” ::: :::ExpandableHeading ### Claude Code Add Floyo as a remote HTTP MCP server, then authenticate. 1. Register the server: ```bash claude mcp add --transport http floyo https://mcp.floyo.ai/mcp ``` 2. Run `/mcp`, select **floyo**, and choose **Authenticate**. 3. Complete Floyo OAuth in the browser. Tokens refresh automatically afterward. ::: :::ExpandableHeading ### ChatGPT 1. Open ChatGPT → **Settings → Plugins → MCPs **and click on **+ Add Server**. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/7yTTXXQ43S5QTegBPMcL0_image.png) 2. On the **Connect to a custom MCP **screen set `Floyo` as the MCP **name**, select **Streamable HTTP**, use `https://mcp.floyo.ai/mcp` as **URL **and click **Save**. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/gmxf5bUZ-6vcBeigt5S9H_image.png) 3. Back to the MCPs list, click on `Authenticate` next to Floyo MCP. This will start the OAuth flow. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/Za5aq4wcKqZsgd89WGbmV_image.png) After connecting, ask in plain language — for example, “list my Floyo teams” or “find a text-to-image workflow on my team.” ::: :::ExpandableHeading ### Codex [Codex](https://developers.openai.com/codex/cli) connects over Streamable HTTP. Add the server, then sign in with Floyo OAuth. 1. Register and log in: ```bash codex mcp add floyo --url https://mcp.floyo.ai/mcp ``` 2. Codex will detect that the Floyo MCP needs authentication and will open a browser window to guide you through the OAuth flow. If it doesn’t start the authentication process automatically, simply run: `codex mcp login floyo` 3. Approve access in the browser when prompted. This writes an entry to `~/.codex/config.toml` (or `.codex/config.toml` in a trusted project), for example: ```toml [mcp_servers.floyo] url = "https://mcp.floyo.ai/mcp" ``` Ask in plain language after login — Codex invokes Floyo tools on your behalf. ::: :::ExpandableHeading ### Cursor **ONE-CLICK Installation: **:InlineCtaButton[]{label="Add Floyo MCP to Cursor" docId docAnchorId externalHref="https://cursor.com/install-mcp?name=floyo&config=eyJ1cmwiOiJodHRwczovL21jcC5mbG95by5haS9tY3AifQ%3D%3D" openInNewTab="true" noFollow="false"} Cursor will open with the MCP configuration already prefilled. Click **Install** to add the MCP. Once the installation is complete, it will appear under **Installed MCP Servers**. Finally, click **Authenticate** and complete the OAuth authentication flow. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/jzzyJvRaZD21Q1Tycgm12_image.png) *** **MANUAL Installation** Cursor connects to Floyo MCP over HTTP and completes **Floyo OAuth**. You do not put a Floyo API key in `mcp.json`. 1. Open **Cursor Settings → Tools & MCP**. 2. Add a custom MCP server, or edit `~/.cursor/mcp.json` (global) / `.cursor/mcp.json` (project): ```json { "mcpServers": { "floyo": { "url": "https://mcp.floyo.ai/mcp" } } } ``` 3. When Cursor prompts for authentication, sign in with Floyo and approve access. 4. Confirm Floyo tools appear under MCP, then ask in plain language (for example, “discover verified workflows on my team”). ::: :::ExpandableHeading ### Antigravity 1. Open **Settings → Customizations **and click on** Open MCP Config** ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/UYCsrTOUTi14a8qdNQ5Xc_image.png) 2. Your OS file browser will open to Antigravity's `mcp_config.json` file. Open the file in your favourite text editor. 3. Edit `mcp_config.json` to include `floyo` under `mcpServers` like this: ```json { "mcpServers": { "floyo": { "serverUrl": "https://mcp.floyo.ai/mcp" } } } ``` 4. Save the file. 5. Go back to Antigravity and click on **Refresh** button. 6. Floyo MCP will appear on the **Installed MCP Servers **list. Click on the **Authenticate **button. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/bbYRrwQibuIyN9LApqP86_image.png) 7. You'll be taken through the OAuth flow. After authorizing the agent you'll get an authorization code. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/kSQV_XEfnieIhTz1i2y2C_image.png) 8. Go back to Antigravity and paste the code. Then click **Submit**. ![](https://api.archbee.com/api/optimize/1hT0XoAHMhU4co8ZZjygd/4DDFvafp-idBtkCjkIa6N_image.png) ::: :::ExpandableHeading ### Antigravity CLI Antigravity CLI uses the same remote schema as the IDE. Prefer the interactive MCP manager after the config entry exists. 1. Add Floyo to `~/.gemini/antigravity-cli/mcp_config.json` (global) or `.agents/mcp_config.json` (workspace): ```json { "mcpServers": { "floyo": { "serverUrl": "https://mcp.floyo.ai/mcp" } } } ``` 2. In the CLI prompt panel, run `/mcp` to open the MCP manager and confirm Floyo is listed. 3. Select `floyo` MCP, use the arrow keys to select `Authenticate` 4. A browser window will open to authorize Antigravity to connect to your Floyo account. After authorizing the agent you'll get an authorization code. Copy the code. 5. Paste the code back to Antigravity CLI to finish setup. Reload the server from `/mcp` if the connection shows as disconnected after login. ::: *** ## Authentication Floyo MCP authenticates with **Floyo OAuth**. Your MCP client opens a browser consent flow; after you approve, the client stores tokens and refreshes them as needed. :::hint{type="info"} **We care about your API keys security.** Floyo MCP does **not** need an API key at all. Floyo API keys are reserved for API-only usage. MCP authentication is **OAuth-only**, so your API keys are never pasted into agent configs and never shared with an AI agent or third-party MCP host. Sign in once in the browser; the agent works under your Floyo identity without ever holding a long-lived key. ::: What OAuth unlocks: - The agent acts as **you**, the signed-in Floyo user. - Your memberships, roles, and team-private assets follow that identity — see [Work under a team context](./#work-under-a-team-context). *** ## Work under a team context Floyo MCP is built around **Floyo Teams**. After you sign in, you can work under any team you belong to — personal or shared — with the same OAuth session. Runs, files, uploads, and team workflow discovery stay inside the team you select. You do not need to memorize team IDs. Talk to your agent in plain language: | What you want | Example prompt | | ------------------------------------------- | -------------------------------- | | See every team you can use | `List my teams` | | Start (or lock) a team for the conversation | `Work under [team name] context` | | Change teams later | `Switch to [team name] team` | ### The agent keeps the active team AI agents are smart enough to **remember the team context** for the conversation. You do not need to restate which team to use before every prompt. Once you say something like `Work under Acme Studio context`, later requests — discover workflows, run a job, list recent runs, upload a file — should execute under that team until you switch. If you are unsure which team is active, ask: `Which team are we working under?` ### Switch anytime Team context is not permanent. Change it whenever you need a different workspace: - `Switch to [team name] team` - `Use my [team name] team for the next runs` After a switch, subsequent tool calls should use the new team. Assets and run history from the previous team stay isolated there. ### Why team context matters on Floyo Floyo MCP treats teams as a first-class security and collaboration boundary — not an afterthought: - **You stay you.** OAuth maps to your Floyo user. The agent only sees teams you already belong to; it cannot invent access to someone else’s workspace. - **Hard isolation.** Workflows, runs, uploads, and downloads for a team stay in that team’s private storage. Switching context changes which vault the tools talk to. - **Shared workspaces, individual consent.** Invite collaborators on Floyo as usual. Each person connects MCP with their own OAuth login — no shared API keys in agent configs, and no key sprawl across laptops or CI secrets for chat agents. - **Roles follow Floyo.** What you can list or run respects the same team membership you have in the Floyo app. Revoke a member in Floyo and their agent loses that team context on the next authorized call. - **Clear mental model.** One signed-in user, many teams, one active context at a time. Ask `List my teams`, pick a name, and keep chatting. :::hint{type="info"} Prefer browsing public community workflows? You can still ask the agent to discover public workflows. For anything that creates runs, uploads files, or reads team history, set an active team first. ::: *** ## Available Tools and Apps You do not call MCP tools yourself. Your agent chooses tools from what you ask. Plain language is enough — for example, “list my teams,” “find an upscaler workflow,” or “run this on my active team.” Typical flow: 1. **Set team context** — `List my teams`, then `Work under [team name] context`. 2. **Discover** a workflow (team-scoped, or public when browsing the community). 3. **Upload** inputs when needed via the Upload widget. 4. **Run** the workflow, then check status and outputs. ### Tools | Tool | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `list_user_teams` | Lists Floyo teams available to the signed-in user. Each `id` is the public team ID to pass as `team_id` elsewhere. | | `get_team_balance` | Retrieves the active team’s FloTime and Partner Nodes balance (plan allocation, flex FloTime, reserved/active usage, and USD Partner Nodes). | | `discover_workflows` | Searches and filters Floyo workflows (search, tags, sort, scope, verification, pagination, optional field expansion). | | `list_team_runs` | Lists workflow runs for a team, with filters, sorting, pagination, and optional expansions (outputs, costs, and more). | | `run_workflow` | Creates a Floyo run from Comfy API workflow JSON for the selected team. Prefer discovering a workflow with `expand` including `prompt`, then pass that prompt as `workflow`. | | `retrieve_run` | Retrieves a single run by ID for the active team, optionally with presigned output URLs or Partner Nodes cost details. | | `list_files` | Browses team storage (files and folders) for a path, with search, sort, size/date filters, and cursor pagination. | | `retrieve_file` | Retrieves file metadata for a team-owned file, optionally with a temporary presigned download URL. | | `delete_file` | Permanently deletes a file or folder by ID. Use `recursive` to delete a non-empty folder and its contents. | | `prepare_file_upload` | Opens the Floyo Upload widget and creates a short-lived upload session for the selected team. | | `prepare_local_file_upload` | Prepares a short-lived direct upload for CLI agents that can read a local file and execute HTTP requests. File bytes never pass through MCP — they go straight from the device to Floyo storage. | | `complete_file_upload` | Verifies and finalizes a successful direct CLI upload. Call it only after the file has reached Floyo storage. | :::hint{type="danger"} **Deleting files is permanent.** `delete_file` removes items from your team’s storage with no undo through Floyo. The tool instructs agents to confirm with you first, but that is **not a guarantee** — behavior depends on the model and your MCP client. If tool calls are auto-approved (or you said something like “clean up my uploads”), the agent may delete without asking again. Prefer clients that require approval for each tool call when cleaning storage, name the exact file or folder you want removed, and treat recursive folder deletes as a full wipe of that tree. Root folders such as `inputs` and `outputs` cannot be deleted. ::: *** ### Upload widget Floyo MCP includes an interactive **Upload** MCP App for attaching images and other inputs to your team. In a single session you can upload **up to 10 files**, each no larger than **90 MB**. :::hint{type="warning"} **Limited widget support. **The widget is currently supported only by ChatGPT and Claude Web/Desktop. CLI applications do not support interactive HTML widgets. ::: When your agent calls `prepare_file_upload`: 1. Floyo creates a short-lived upload session for the chosen `team_id`. 2. The Upload widget opens in your MCP client. 3. You pick a file on your device. 4. The file is uploaded **directly from your device to Floyo’s CDN** into your team’s private, secure storage. :::hint{type="warning"} **We care about your files privacy and security.** File bytes never travel through the MCP host, the language model, or third-party agent infrastructure. The widget redeems short-lived CDN credentials privately inside the app; those credentials are not shown to you or to the model. Only session metadata needed to complete the upload is exchanged with the agent tools. ::: After a successful upload, your agent can use the resulting file IDs with workflows and runs under the same team context. *** ### Direct uploads from CLI agents Claude Code, Codex, Cursor, and other agents with local files and HTTP access can upload without the widget — up to **5 GiB** per file. Your file never passes through MCP, the language model, or Floyo’s servers. Bytes go **directly from your device to your team’s private Floyo storage**. Nothing sits in between. 1. The agent calls `prepare_local_file_upload` with the file’s name, type, and size only — never the contents. 2. It uploads the file straight from your device to Floyo storage. 3. After a successful transfer, it calls `complete_file_upload` so the file appears in the team. :::hint{type="warning"} **We care about your files privacy and security.** File bytes never travel through the MCP host, the language model, or any third-party agent infrastructure. They go only from your device into your team’s private, secure storage. The short-lived upload destination is a secret: agents must not print, share, or reuse it. If the transfer fails, they must not call `complete_file_upload`. :::