# Flato MCP Agent Skill

## Goal

Install and use Flato MCP so an MCP-capable AI agent can create, inspect, and continuously update editable Flato canvas projects.

Flato MCP connects Claude Code, Codex, Cursor, and other MCP-capable agents to Flato's AI-native canvas runtime. Agents can create and continuously update editable designs such as presentations, posters, and social visuals, while users can open the browser editor, make manual edits, export PDFs or images, share links, and continue collaborating with AI on the same project.

## When to use

Use this skill when the user asks an AI agent to:

1. Install Flato MCP.
2. Connect Claude Code, Codex, Cursor, or another MCP client to Flato.
3. Create a new editable design project in Flato.
4. Work on an existing Flato editor URL.
5. Turn a Flato share URL into an editable project copy.
6. Inspect or update an existing Flato canvas through MCP.

## Quick handoff instruction

If you are handing this skill to another AI agent, send:

```text
Please read this Flato MCP guide, install Flato MCP, trigger OAuth authorization when needed, guide me through the browser confirmation, verify the connection with flato_whoami, then follow the agent workflow in the guide. Important Codex App rule: after adding flato-editor or completing codex mcp login, the current Codex conversation may not hot-load newly added MCP tools. If flato_* tools are unavailable in this same conversation, stop and ask me to open a new Codex conversation or restart Codex App; do not inspect local OAuth/token stores or manually extract bearer tokens. When a project returns waiting_for_live_editor_bridge or needs_open_editor, have the MCP host/client open editorUrl automatically when supported, and only ask me to open editorUrl if the host cannot open URLs. Markdown guide: https://www.flato.ai/docs/mcp.md
```

## What Flato MCP Does

Flato MCP gives an external AI agent controlled access to Flato's AI-native canvas runtime:

1. Create a saved editable design project.
2. Take over an existing editor URL or share link.
3. Read the current canvas, pages, blocks, styles, and layout feedback.
4. Create and update presentations, posters, social visuals, and other design formats.
5. Let the user open the live editor, make manual edits, export, share, and continue collaborating with AI.
6. Keep every AI change grounded in the same live project instead of generating disconnected files.

## Install Flato MCP

Use this HTTP MCP server URL when adding Flato to an AI coding tool:

```text
https://api.flato.ai/api/mcp/editor
```

## First-time authorization

Adding the MCP server only saves the connection settings. In most clients, the Flato OAuth window opens when the AI tool first calls the Flato MCP server, not at the moment you save the configuration.

If no browser window opens after installation, ask your AI tool to trigger Flato MCP authorization by calling mcp_auth or flato_whoami. After authorization succeeds, ask it to call flato_whoami again to confirm the connection.

## Verify the connection

After installing the MCP server, call:

```text
flato_whoami
```

If OAuth has not completed, this call should trigger authorization. After the browser authorization succeeds, call `flato_whoami` again and confirm the connected account and current project/editor status.

## Claude Code

Run this command in your terminal:

```bash
claude mcp add --transport http flato https://api.flato.ai/api/mcp/editor
```

Then type /mcp in a Claude Code session to start the OAuth sign-in flow. Claude Code opens your browser for Flato authorization when it first calls the Flato MCP server.

## Codex App

In Codex App, add this direct Streamable HTTP MCP server configuration to ~/.codex/config.toml:

```toml
[mcp_servers.flato-editor]
url = "https://api.flato.ai/api/mcp/editor"
tool_timeout_sec = 120
```

After adding the server, open a new Codex conversation or restart Codex App. Current Codex conversations may not hot-load newly added MCP tools. If flato_* tools are unavailable in the same conversation that installed the server, stop and ask the user to open a new Codex conversation or restart Codex App instead of inspecting local OAuth/token stores. If OAuth does not start automatically in the new conversation, run codex mcp login flato-editor. OAuth is completed in the browser; do not ask for a Flato username, password, or Authorization header. A personal Codex plugin is only for legacy local demos, not normal Flato MCP setup.

## Cursor

Open Cursor Settings > MCP and add a new server, or add this to ~/.cursor/mcp.json:

```json
{
  "mcpServers": {
    "flato": {
      "type": "http",
      "url": "https://api.flato.ai/api/mcp/editor"
    }
  }
}
```

Authentication is handled via OAuth. Cursor usually opens your browser for Flato authorization on the first actual MCP tool call. If Cursor loads the server but no OAuth window appears, ask Cursor Agent to call mcp_auth for the Flato server, or to call flato_whoami; either action should start authorization.

## Required agent workflow

Always follow this sequence before making design changes:

1. Trigger OAuth authorization if it has not already happened.
2. Call flato_whoami to confirm auth and inspect project/editor status.
3. For a new design, choose a concise user-facing projectName and call flato_create_project.
4. For an editor URL, call flato_use_project with the full projectUrl.
5. For a share URL, call flato_use_share_link with the full shareUrl.
6. If the returned status is waiting_for_live_editor_bridge or needs_open_editor, have the MCP host/client open the returned editorUrl automatically when supported; if the host cannot open URLs, ask the user to open editorUrl.
7. Call flato_get_project_status until canWrite=true.
8. Call flato_get_design_context before creating, editing, or exporting.

## Create a new Flato project

1. Choose a concise user-facing `projectName`.
2. Call `flato_create_project`.
3. If the response includes an `editorUrl`, keep it as the editor target.
4. If the response status is `waiting_for_live_editor_bridge` or `needs_open_editor`, have the MCP host/client open `editorUrl` automatically when supported. Only ask the user to open `editorUrl` manually when the host cannot open URLs.
5. Call `flato_get_project_status` until `canWrite=true`.
6. Call `flato_get_design_context` before creating or editing content.

## Use an existing Flato editor URL

If someone gives your AI agent a Flato project URL such as https://www.flato.ai/editor/<projectId>, install and authorize Flato MCP, then ask the agent to call flato_use_project with that full projectUrl.

Required call:

```text
flato_use_project({ projectUrl: "<full Flato editor URL>" })
```

Then call `flato_get_project_status` until `canWrite=true`, followed by `flato_get_design_context`.

## Use a Flato share URL

If someone gives your AI agent a Flato share URL such as https://www.flato.ai/share/<shareId>, ask the agent to call flato_use_share_link with that full shareUrl. Flato MCP creates an editable project copy in the authorized user account and returns a new editorUrl.

If flato_use_share_link is unavailable in an older MCP client, open the share link, use Edit a copy, then ask the agent to call flato_use_project with the copied editor URL.

Required call:

```text
flato_use_share_link({ shareUrl: "<full Flato share URL>" })
```

Then have the MCP host/client open the returned `editorUrl` when the project status requires a live editor bridge and the host supports opening URLs. If the host cannot open URLs, ask the user to open `editorUrl`. Call `flato_get_design_context` before changing the canvas.

## Readiness and wait conditions

When flato_create_project, flato_use_project, or flato_use_share_link returns waiting_for_live_editor_bridge or needs_open_editor, the agent should have the MCP host/client open the returned editorUrl automatically when supported. If the host cannot open URLs, it should ask you to open editorUrl. After the editor page loads, the agent should call flato_get_project_status until canWrite=true, then call flato_get_design_context before making any design changes.

The agent must stop and wait when:

1. OAuth authorization has not completed.
2. The MCP host cannot open the returned `editorUrl` and the user needs to open or refresh it manually.
3. `flato_get_project_status` does not return `canWrite=true`.

## Credits Usage Notice

Flato MCP does not consume Flato Credits for tokens used by your local AI agent, such as Claude Code, Codex, Cursor, or other MCP clients.

Flato Credits are consumed only when Flato-side AI generation or media-processing features are used. Manual canvas edits, such as changing text, adjusting layout, moving elements, or cropping images, do not consume Credits.

Some Flato features require an active subscription, including MPEG export, vectorizer, and video generation. Feature availability follows the current platform rules; other supported MCP and platform features are free to use unless marked otherwise.

Local model/API usage remains billed by your AI agent or AI service provider, not by Flato Credits.

## Operating rules

1. Do not fabricate canvas state. Call `flato_get_design_context` before editing.
2. Keep all design changes grounded in the same live Flato project.
3. Prefer editable canvas updates over detached files whenever possible.
4. If an export or share operation is requested, inspect current project status first.
5. When blocked by authorization or live editor bridge state, use host-assisted URL opening when available; otherwise tell the user exactly what to open or authorize, then wait.