--- title: "Configure the flare.design MCP server" description: "Connect an MCP client to flare.design so it can read projects, inspect live canvas state, place media, run AI jobs, and apply controlled edits." locale: "en" section: "MCP" updated: "2026-06-22" source: "https://flare.design/docs/configure-flare-design-mcp" --- # Configure the flare.design MCP server Connect an MCP client to flare.design so it can read projects, inspect live canvas state, place media, run AI jobs, and apply controlled edits. > Section: MCP [HTML](https://flare.design/docs/configure-flare-design-mcp) | [Markdown](https://flare.design/docs/configure-flare-design-mcp/index.md) flare.design exposes a remote MCP endpoint for clients that can work with protected resources and OAuth. Connected clients can inspect project context, place media, create AI generation and render jobs, and make controlled edits to the collaborative canvas. ## Endpoint Use this endpoint in your MCP client: ```json { "mcpServers": { "flare-design": { "url": "https://mcp.flare.design/mcp" } } } ``` ## Recommended agent skill For Codex, Claude Code, or other local agents that support skills, install the Flare Skill so the agent follows the preferred canvas, asset, motion, and generated-media workflows: ```bash npx skills add flare-design/flare-skill --skill flare --global ``` For internal or private SSH access: ```bash npx skills add git@github.com:flare-design/flare-skill.git --skill flare --global ``` To install it for Codex and Claude Code at the same time: ```bash npx skills add git@github.com:flare-design/flare-skill.git --skill flare --agent codex claude-code --global ``` Keep installed skills current: ```bash npx skills check npx skills update flare ``` The MCP `check_client_setup` tool lets agents compare the installed skill version with the server-recommended version before visible canvas writes. When a newer skill is available, the agent can remind you to run `npx skills update flare` instead of silently continuing with stale instructions. The skill is guidance for the agent. You still need to configure the MCP endpoint above in the target client. ## Authorization The MCP server is a protected resource. Your client should start the OAuth flow, ask you to sign in with flare.design, and request the scopes it needs. The Flare authorization page keeps requested MCP scopes selectable. Agent-recommended scopes are selected by default: `projects:read`, `canvas:read`, `canvas:write`, `assets:read`, and `assets:write`. Flare backend generation and cloud rendering scopes are shown as optional and are not selected by default because create permissions may consume Flares, render allowance, or plan usage. Common scopes: - `projects:read` lists and reads project metadata. - `canvas:read` allows canvas snapshots, live context, and image annotation context through `get_canvas_snapshot`, `get_live_canvas_context`, `get_image_annotation_context`, and `export_project_snapshot`. - `canvas:write` allows controlled canvas, timeline, and motion edits through tools such as `apply_canvas_patch`, `insert_text`, `insert_rect`, `create_frame`, `insert_html`, `update_text`, `set_layer_style`, `reorder_nodes`, `group_nodes`, `delete_nodes`, `add_audio_track`, `add_caption_track`, and `apply_motion_design`. - `assets:read` lists account assets and lets clients place existing media with `insert_asset_image` or `insert_asset_video`. - `assets:write` creates short-lived binary upload sessions with `create_image_upload_session` or `get_image_upload_endpoint`, saves public HTTPS images with `save_image_asset_from_url`, and places agent-provided images with `insert_agent_generated_image`, `insert_generated_image`, or `insert_asset_image`. - `generation:read` and `generation:create` read or create Flare AI generation jobs. - `render:read` and `render:create` read or create cloud render jobs. Grant write access only to clients you trust. If you only want inspection and summaries, read scopes are enough. Select `generation:create` or `render:create` only when you want the agent to start Flare backend jobs. ## Tool families | Need | Tools | | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Client setup | `check_client_setup` | | Project and canvas context | `list_projects`, `get_project`, `get_canvas_snapshot`, `get_live_canvas_context`, `get_image_annotation_context`, `export_project_snapshot` | | Capability discovery | `list_generation_models`, `list_motion_presets`, `list_shader_presets`, `list_canvas_patch_operations`, `list_media_capabilities`, `list_render_presets` | | Account assets and placement | `list_assets`, `create_image_upload_session`, `get_image_upload_endpoint`, `save_image_asset_from_url`, `insert_agent_generated_image`, `insert_generated_image`, `insert_codex_generated_image`, `insert_asset_image`, `insert_asset_video` | | Canvas construction and edits | `apply_canvas_patch`, `insert_text`, `insert_rect`, `create_frame`, `insert_html`, `update_text`, `set_layer_style`, `reorder_nodes`, `group_nodes`, `delete_nodes` | | Timeline and motion | `add_audio_track`, `add_caption_track`, `apply_motion_design` | | AI generation and cloud render | `create_generation_job`, `get_generation_job`, `list_generation_jobs`, `create_render_job`, `get_render_job`, `list_render_jobs` | Use `export_project_snapshot` when a client needs project metadata, the current canvas document, related assets, and live awareness in one response. Use `get_live_canvas_context` when placement should follow the active collaborator selection, viewport, cursor, or active text node. ## Usage limits During beta, MCP usage has a generous rolling 7-day allowance: | Workspace | Beta MCP tool-call allowance | | --------- | ---------------------------- | | Free | 1M/week | | Creator | 1M/week | | Pro | 1M/week | | Team | 4M pooled/week | These beta allowances may change before general availability. Team workspaces add 1M MCP tool calls per week for each extra editor seat during beta. OAuth handshakes, `initialize`, `tools/list`, and the setup health check `check_client_setup` do not count; normal `tools/call` requests count. Binary upload bytes, storage, AI generation, cloud render, and batch/API work are governed by their own limits and billing rules instead of the MCP call allowance. Creating AI generation or cloud-render jobs through MCP still uses the normal Flares quote and reservation flow. The MCP allowance only covers the tool-call control plane. ## Media placement When an agent or MCP client generates an image as a local file, do not pass base64 or data URLs through MCP JSON. Use binary upload: 1. Call `create_image_upload_session` with `fileName`, `fileSize`, `mimeType`, and provenance fields. Use `sourceClient` for the agent/client (`codex`, `claude`, `chatgpt`, etc.), `generationModel` for the actual image model, and `generationPrompt`/`generationTool` when known. 2. `POST` the local file bytes to the returned `uploadUrl` with `Authorization: Bearer `, `Content-Type`, and `x-flare-file-size`. 3. Call `insert_asset_image` with the returned `assetId` and the target `projectId`. Assets created through this flow are recorded as generated media with `ingestMethod: mcp-binary-upload`, not as ordinary user uploads. This keeps Codex/Claude-generated images searchable by source and prompt without creating a fake Flare generation job. If the client has an older tool list that does not expose `create_image_upload_session`, call `get_image_upload_endpoint` to get a generic short-lived `uploadToken`, then upload the local file bytes in the same way. If the agent only has a data URL or base64 payload, it should first save that payload as a real local image file, then use the binary upload flow. Do not search for or expose the MCP OAuth access token in shell commands. For public HTTPS image URLs, use `insert_agent_generated_image` to save the URL image into Assets and place it on the canvas in one step. `insert_generated_image` and `insert_codex_generated_image` are compatibility aliases. These tools are for agent-provided images; they do not start a Flare/canvas generation job. For existing account media, use `insert_asset_image` or `insert_asset_video`. Video placement supports `autoplay`, `loop`, `muted`, and `mediaFit`. `insert_agent_generated_image`, `insert_generated_image`, `insert_codex_generated_image`, `insert_asset_image`, and `insert_asset_video` support smart placement: - `anchorNodeId` places media relative to a specific node. - `clientId` chooses which collaborator presence state to use. - `placement` can be `left`, `right`, `above`, `below`, `center`, or `fill`. - `fitSelection` fits media to the active selection. - `replaceNodeId` replaces the media source for an existing image or video node. - `x` and `y` are center-origin scene coordinates. `width` and `height` are unscaled layer sizes. - `parentId` only changes nesting or clipping. Coordinates stay in canvas scene space. When coordinates are omitted, the MCP server can use `get_live_canvas_context` presence data: active selection, viewport, cursor, and the currently edited text node. Presence is realtime context only; it is not stored in the project document. For generated images, omit `parentId` by default. Only pass `parentId` when the user specifically asks to place the generated image inside a frame or group. Image uploads and remote image imports are capped at 20 MB. Binary upload sessions expire after 10 minutes. Remote image fetches must use HTTPS. ## Annotated image revision When a user annotates an image layer in Flare and asks an external agent such as Codex to revise it, call `get_image_annotation_context` first. The tool returns the exact target image node, matched asset/provenance, structured arrow, region, and text annotations with 0..1 normalized target points, an optional target-image-plus-annotations composite preview, and a suggested placement next to the original image. This flow is for agent-side image generation. The agent should use its own image generation/editing capability, keep the revised result as a local image file, upload it with `create_image_upload_session`, then place it with `insert_asset_image` using the suggested placement. Do not call `create_generation_job` unless the user explicitly asks to use Flare backend generation. ## HTML import Use `insert_html` when an agent has an HTML snippet or document and the user wants it on the canvas. The MCP server converts one HTML input into one root Flare frame. Supported text, simple boxes, and public HTTPS images become editable child layers inside that frame. `insert_html` is a structured editable import, not a high-fidelity browser screenshot. It does not run Playwright or execute scripts. If you need pixel-perfect browser rendering, render externally first, save the result as a local image file, upload it with `create_image_upload_session`, and place it with `insert_asset_image`. Image handling follows the same media rules as generated images. Do not put data URLs, base64 strings, or local image paths into MCP JSON. Save those images as local files and upload them as binary assets first. ## Canvas, media, and timeline For direct canvas edits, prefer the specific tools when possible: - Use `insert_text`, `insert_rect`, and `create_frame` for simple layer creation. - Use `update_text`, `set_layer_style`, `reorder_nodes`, `group_nodes`, and `delete_nodes` for focused edits. - Use `apply_canvas_patch` for batched or mixed edits. A patch can contain up to 50 operations. For timeline work, use `add_audio_track` to add an account audio asset with trim, volume, fade, and ducking options. Use `add_caption_track` to add manual or transcript caption cues. For rendering and AI generation, use the job tools: - `create_generation_job`, `get_generation_job`, and `list_generation_jobs` use the same Flare AI backend queue as the app. - `create_render_job`, `get_render_job`, and `list_render_jobs` create and inspect cloud render jobs from a project or explicit render snapshot. ## AI Motion Design Clients can call `get_live_canvas_context` to read the selected frame, then `get_canvas_snapshot` to analyze titles, media, CTA layers, and hierarchy. After generating a motion plan, call `apply_motion_design`: - When `frameId` is omitted, the server uses the selected frame; if a child layer is selected, it walks up to the owning frame. - `composition`, `durationMs`, `fps`, and `posterTimeMs` control frame timing and playback parameters. - Each `layers` item targets a child layer with `nodeId` and can write `timeline`, `motionClips`, `animation`, or `textAnimation`. - `replaceExisting` controls whether existing motion clips are replaced. It defaults to replacement, which is best for full AI redesigns. ## Smoke test After connecting, ask the client to list projects, then call `export_project_snapshot` for one project. If that works, try a small write action such as inserting one text layer on a temporary canvas. If the client reports an authorization error, reconnect and make sure the requested resource URL is `https://mcp.flare.design/mcp`.