配置 flare.design MCP

flare.design 提供远程 MCP endpoint，适合支持 OAuth 和 protected resource 的 MCP 客户端接入。接入后，客户端可以读取项目上下文、放置媒体、创建 AI 生成和云端渲染任务，也可以对协作画布执行受控编辑。

Endpoint

在 MCP 客户端里使用这个 endpoint：

{
  "mcpServers": {
    "flare-design": {
      "url": "https://mcp.flare.design/mcp"
    }
  }
}

推荐安装 Flare Skill

如果使用 Codex、Claude Code 或其他支持 skill 的本地 agent，建议安装 Flare Skill，让 agent 按照 Flare 推荐的画布、资产、动效和生成媒体流程操作：

npx skills add flare-design/flare-skill --skill flare --global

如果需要走内部或私有 SSH 仓库：

npx skills add git@github.com:flare-design/flare-skill.git --skill flare --global

如果想同时安装到 Codex 和 Claude Code：

npx skills add git@github.com:flare-design/flare-skill.git --skill flare --agent codex claude-code --global

保持已安装 skill 为最新版本：

npx skills check
npx skills update flare

MCP 的 check_client_setup 工具会让 agent 在可见画布写入前，对比本地已安装 skill 版本和服务端推荐版本。如果有新版本，agent 会提醒你运行 npx skills update flare，避免继续使用过期说明。

Skill 只是给 agent 的操作说明。目标客户端仍然需要单独配置上面的 MCP endpoint。

授权

MCP server 是 protected resource。客户端应发起 OAuth 流程，引导你登录 flare.design，并请求它需要的 scope。

Flare 授权页会把 MCP 请求的 scope 展示成可选择权限。Agent 推荐权限默认勾选：projects:read、canvas:read、canvas:write、assets:read、assets:write。Flare 后端生成和云端渲染权限会单独展示，默认不勾选，因为创建生成或渲染任务可能消耗 Flares、渲染额度或套餐用量。

常用 scope：

• projects:read 用于列出和读取项目 metadata。
• canvas:read 用于通过 get_canvas_snapshot、get_live_canvas_context、get_image_annotation_context、export_project_snapshot 读取画布快照、实时上下文和图片批注上下文。
• canvas:write 用于通过 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、apply_motion_design 等工具执行画布、时间线和动效编辑。
• assets:read 用于列出账号资产，并通过 insert_asset_image 或 insert_asset_video 把已有媒体放入画布。
• assets:write 用于通过 create_image_upload_session 或 get_image_upload_endpoint 创建短时二进制上传会话，通过 save_image_asset_from_url 保存公开 HTTPS 图片，并通过 insert_agent_generated_image、insert_generated_image 或 insert_asset_image 放置 agent 提供的图片。
• generation:read 和 generation:create 用于查询或创建 Flare AI 生成任务。
• render:read 和 render:create 用于查询或创建云端渲染任务。

只把写权限授权给你信任的客户端。如果只是做分析、总结或读取画布，读权限通常就够了。只有在你希望 agent 启动 Flare 后端任务时，才勾选 generation:create 或 render:create。

工具分组

如果客户端需要一次拿到项目 metadata、当前画布文档、相关资产和实时 awareness，用 export_project_snapshot。如果媒体放置要跟随当前协作者的选区、视口、光标或正在编辑的文本节点，用 get_live_canvas_context。

用量限制

Beta 阶段，MCP 用量使用较宽松的 rolling 7-day allowance：

这些 beta 额度在正式开放前可能调整。Beta 期间，Team workspace 每增加一个额外编辑席位，会增加每周 1M 次 MCP 工具调用。OAuth 握手、initialize、tools/list 和设置健康检查 check_client_setup 不计入额度；普通 tools/call 请求会计入。二进制上传字节、存储、AI 生成、云渲染和批量/API 工作仍由各自的限制和计费规则管理，不消耗 MCP call 额度。

通过 MCP 创建 AI 生成或云渲染任务时，仍然走正常的 Flares 报价和预留流程。MCP 额度只覆盖工具调用控制层。

媒体放置

如果 agent 或 MCP 客户端生成的是本地图片文件，不要把 base64 或 data URL 塞进 MCP JSON。走二进制上传流程：

1. 调用 create_image_upload_session，传入 fileName、fileSize、mimeType 和来源信息。用 sourceClient 记录 agent/客户端（如 codex、claude、chatgpt），用 generationModel 记录真实生图模型，知道的话同时传 generationPrompt/generationTool。
2. 把本地文件字节 POST 到返回的 uploadUrl，请求头带上 Authorization: Bearer <uploadToken>、Content-Type 和 x-flare-file-size。
3. 用上传返回的 assetId 和目标 projectId 调用 insert_asset_image。

这条路径创建的素材会记录为生成媒体，并标记 ingestMethod: mcp-binary-upload，不是普通用户上传。这样 Codex/Claude 生成的图可以按来源和 prompt 搜索，也不会伪造一个 Flare 内部生成任务。

如果客户端工具列表较旧，还没有 create_image_upload_session，可以调用 get_image_upload_endpoint 获取通用的短时 uploadToken，再用同样方式上传本地文件字节。

如果 agent 手里只有 data URL 或 base64 payload，应先把它保存成本地图片文件，再走二进制上传流程。不要在 shell 命令里搜索、暴露或复用 MCP OAuth access token。

如果图片已经是公开 HTTPS URL，可以用 insert_agent_generated_image 一步保存到 Assets 并放到画布上。insert_generated_image 和 insert_codex_generated_image 是兼容别名。这些工具用于 agent 已经生成或拿到的图片，不会启动 Flare/canvas 的生成任务。

已有账号媒体可以用 insert_asset_image 或 insert_asset_video 放入画布。视频放置支持 autoplay、loop、muted 和 mediaFit。

insert_agent_generated_image、insert_generated_image、insert_codex_generated_image、insert_asset_image 和 insert_asset_video 支持智能放置参数：

• anchorNodeId 指定围绕哪个节点放置。
• clientId 指定读取哪个协作者的实时选区。
• placement 可选 left、right、above、below、center、fill。
• fitSelection 会让图片适配当前选区。
• replaceNodeId 会替换已有图片或视频节点的媒体来源。
• x 和 y 是以图层中心为准的 canvas scene 坐标。width 和 height 是未缩放尺寸。
• parentId 只改变层级或裁剪关系，坐标依然使用 canvas scene 坐标。

如果没有传入坐标，MCP server 会优先读取 get_live_canvas_context 的实时 presence：包括当前选区、视口、光标和正在编辑的文本节点。presence 只用于实时上下文，不会写进项目文档。

对生成图片来说，默认不要传 parentId。只有当用户明确要求把生成图片放进某个 frame 或 group 时，再传 parentId。

图片上传和远程图片导入上限都是 20 MB。二进制上传会话 10 分钟后过期。远程图片必须使用 HTTPS。

批注改图

当用户在 Flare 里给图片图层加箭头、框选、圈选或文字批注，并让 Codex、Claude 等外部 agent 按批注改图时，先调用 get_image_annotation_context。这个工具会返回准确的目标图片节点、匹配到的素材和 provenance、带 0..1 归一化目标点的结构化箭头、区域和文字批注、可选的“目标图 + 批注”合成预览，以及建议把新版图片放在原图旁边的位置。

这条流程属于 agent 侧生图。Agent 应该用自己的图像生成或编辑能力生成新版图片，把结果保留为本地图片文件，通过 create_image_upload_session 二进制上传，再用 insert_asset_image 按建议位置放回画布。除非用户明确要求使用 Flare 后端生成，否则不要调用 create_generation_job。

HTML 导入

当 agent 手里有一段 HTML snippet 或完整 HTML document，并且用户希望放到画布上时，使用 insert_html。MCP server 会把一份 HTML 输入转换成一个根 Flare frame；支持的文字、简单盒子和公开 HTTPS 图片会变成这个 frame 里的可编辑子图层。

insert_html 是结构化、可编辑导入，不是高保真的浏览器截图。它不会运行 Playwright，也不会执行脚本。如果需要像素级浏览器渲染，应先在外部渲染成图片，把结果保存成本地图片文件，再用 create_image_upload_session 二进制上传，并通过 insert_asset_image 放到画布。

图片处理规则和生成图片一致。不要把 data URL、base64 字符串或本地图片路径放进 MCP JSON；先保存成本地文件，再按二进制资产上传。

画布、媒体和时间线

直接编辑画布时，尽量优先使用更具体的工具：

• 用 insert_text、insert_rect、create_frame 创建简单图层。
• 用 update_text、set_layer_style、reorder_nodes、group_nodes、delete_nodes 做聚焦编辑。
• 用 apply_canvas_patch 执行批量或混合编辑。单次 patch 最多 50 个 operation。

时间线相关能力：

• add_audio_track 可以把账号音频资产加入项目时间线，并设置 trim、volume、fade、ducking。
• add_caption_track 可以添加手动字幕或 transcript 字幕 cue。

生成和渲染任务：

• create_generation_job、get_generation_job、list_generation_jobs 使用和 app 一样的 Flare AI 后端队列。
• create_render_job、get_render_job、list_render_jobs 可以基于项目或显式 render snapshot 创建和查询云端渲染任务。

AI 设计 Motion

客户端可以先用 get_live_canvas_context 读取当前选中的画板，再用 get_canvas_snapshot 分析画板里的标题、图片、CTA 和层级关系。生成 motion plan 后调用 apply_motion_design：

• 不传 frameId 时，server 会优先使用当前选中的 frame；如果选中的是 frame 内子图层，会自动找到所属 frame。
• composition、durationMs、fps、posterTimeMs 用于设置画板时长和播放参数。
• layers 里每一项用 nodeId 指向子图层，并可写入 timeline、motionClips、animation 或 textAnimation。
• replaceExisting 控制是否替换已有 motion clips；默认替换，适合 AI 重新设计整套动效。

连通性测试

连接后，先让客户端列出项目，再对某个项目调用 export_project_snapshot。如果读取正常，可以在临时画布里插入一段小文字来验证写入能力。

如果客户端提示授权错误，重新连接并确认 resource URL 是 https://mcp.flare.design/mcp。