MCP Server - Framelane

Overview

Framelane runs a hosted, authenticated MCP (Model Context Protocol) action server at:

https://mcp.framelane.io/mcp

Any MCP host — Claude, Claude Desktop, Cursor, VS Code, LangChain, CrewAI, etc. — can connect and drive Framelane over MCP without writing HTTP integration code. It speaks the Streamable HTTP transport, and every tool requires authentication (see below). It is an action server — it renders, runs tasks, and edits projects. For documentation, agents read the static channels instead: llms.txt, the installable skill, or any docs page as raw markdown (append .md to its URL).

Getting a credential first

Onboarding happens over REST, not MCP — an MCP client connects after it holds a key:

POST /v1/signup with a workspace_name and an email you control — returns an fl_ API key and emails a 6-digit code.
POST /v1/signup/verify with the code. The key works the moment this succeeds; until then authed calls return 403 email_not_verified.

GET /v1/capabilities (no auth) returns an onboarding block describing this loop plus the action_mcp_url in machine-readable form. See Self-provisioning for agents. Interactive clients can instead authenticate via OAuth 2.1 (PKCE) — Framelane is an OAuth resource server and delegates the login to Clerk as the authorization server; MCP hosts discover it automatically from the server’s WWW-Authenticate challenge.

Key tools

Every tool requires a credential (an fl_ key or a Clerk OAuth token), and every tool that acts on your workspace requires a verified one — get_capabilities is the exception, so an unverified workspace can still read the onboarding block that explains how to verify. The full set, 30 tools (one of them panel-only):

Tool	Does
`get_capabilities`	The machine-readable catalog, sliced: call it bare for an index of every section and its size, then `section='request_schema'` / `'element_schemas.text'` / `'catalogs'`
`create_render`	Submit a render job
`wait_for_render` / `get_render`	Await terminal status (streams progress) / fetch status
`get_render_download`	Signed download URL for a completed render
`list_renders` / `cancel_render`	List / cancel renders
`run_task`	Run an AI task (`transcribe`)
`wait_for_task` / `get_task`	Await / fetch a task — structured output arrives on `result` (`transcribe` returns its transcript there)
`get_task_download`	Signed download URL for a task whose artifact is a file; `not_found` for `transcribe`, which has none
`create_preview`	Validate (`dry_run`) or cheaply preview a composition
`get_render_preview`	See a finished preview as an inline image — a `contact_sheet` preview returns the grid PNG inline for a single vision call; a full-video render returns a `download_url` instead
`create_project` / `list_projects` / `get_project` / `edit_project` / `preview_project` / `render_project`	The stateful, versioned edit loop. Every project receipt carries an `editor_url` that opens the project in the console for a person to edit; `list_projects` is cursor-paginated, newest first; `get_project` takes `view` (`full`, the default, or `summary` to omit the composition) and also reads a published template from the gallery, read-only
`list_templates`	Templates to start from: the public gallery plus your workspace’s own, newest first and cursor-paginated. Filter with `scope` (`public`, `workspace`, or `all`, the default), `category`, `q` (name, title or description), `aspect` and `family` (the sizes of one design). Start a project from one with `create_project` and its `id` as `source_project_id`, or swap one into an open project with an `apply_template` op in `edit_project`
`extract_brand_kit` / `list_brand_kits` / `get_brand_kit`	Pull a palette, fonts, logo and corner feel from a website URL and reuse them across renders
`list_assets`	The workspace’s reusable media (video, audio, images), newest first. Each item’s source URL drops straight into an element. Filter with `kind`
`get_asset`	One asset by id, including one not listed yet. `ready: false` means the duration probe is still running, so poll it rather than treating the id as missing. `bytes_uploaded: false` is the other answer: the row is a reservation whose upload never completed
`get_asset_preview`	See an image asset as an inline image. The surest way to tell one stored logo from another: an object key is a uuid, and `filename` is caller-supplied and absent on older assets. SVG/TIFF and oversized files come back as a URL and a note
`create_upload`	Put a local video, audio or image file into the workspace. On hosts that render interactive panels (Claude.ai, Claude Desktop, ChatGPT, Cursor, VS Code) a file picker appears with the result: the user drops the file there and the panel reports the final asset id. Under 256 KB, send the bytes as base64 and the one call stores them (`uploaded: true`) — no outbound request of your own, which is what makes it work inside a sandbox. Larger, it returns a signed upload URL you PUT to yourself; those bytes never pass through the server, so a successful call means a slot exists, not that a file arrived
`replace_upload_slot`	Panel-only (hidden from the model): swaps an empty slot for one matching the file the user actually picked, deleting the empty one
`create_upload_link` / `get_upload_link`	Hand a person a one-hour web page to upload one file when you can neither PUT from where you run nor show a panel; poll the link for the asset it produced

Start by calling the get_capabilities tool. Call it with no argument for a small index naming every catalog section and its byte size, then fetch the sections you need. There are three tiers, and an agent needs all three:

section='catalogs' — every flat catalog in one slice (effects, motions, transitions, blend_modes, easings, word_animations, motion_scopes, output_formats, input_formats, element_types, task_types, rate_limits) — what exists, each flagged with whether it is supported today. Fetch one on its own with section='effects', section='motions', and so on.
section='element_schemas' — the full JSON Schema of every field each element type accepts (video, audio, text, image, shape), nested motion / effects / counter / glow / trim_keyframes included. It is by far the largest section — the index reports its exact size — so prefer one type at a time: section='element_schemas.text'.
section='request_schema' — the composition-level body: groups, custom_animations, motion_blur, background_gradient, watermark_url, transitions, canvas and output settings. None of these appear in the flat catalogs.

Read per-element fields from element_schemas, not request_schema — the latter deliberately elides them. motions[] also carries a per-preset surface matrix (element_entrance / element_exit / character / text_block); check it before picking a preset, since a preset used on the wrong surface is a 422.Every response is wrapped as {section, api_version, data} — the slice you asked for is under data. An unknown section is an invalid_request error carrying valid_sections and a suggestion, so a typo is self-correcting.

Composition bodies are plain JSON objects. create_render.body, create_preview.request, create_project.body.render_request and the replace_request op all take the composition as an ordinary object; their schema comes from get_capabilities, deliberately not inlined into the tool definitions. That keeps every tool’s input schema under 4 KB, so size-capped MCP clients keep the whole toolset instead of silently dropping the ones that create things.Validation is unchanged: the server validates each body against the same model the REST API uses, unknown keys are still rejected, and a bad field comes back as invalid_request with an RFC 6901 pointer (e.g. /elements/0/font_wight) and a suggestion (font_weight).

For visual review, use the native preview. create_preview (or preview_project) at a frame or with a contact_sheet option → wait_for_render → get_render_preview returns what the export engine renders, as an inline image, before you pay for a full render.Open the browser only for editor interaction, such as handing a project to a person through its editor_url. The editor draws its own preview in the browser, which can differ from the export (text shaping, for example), so it is not evidence of how a render looks.

Media an agent can reach. list_assets serves exactly the rows GET /v1/workspace/assets serves (one shared query, so kind and readiness cannot drift), and its cursors are interchangeable with the REST ones.Two timing models, and mixing them up is the usual 422. For video and audio, duration is the source file’s full length: omit an element’s out_point and the server fills it from that, or set in_point / out_point to trim. An image has no duration (always null, on every path) and no out_point; its element carries a required duration of its own, in seconds on screen, which you choose.ready is derived, not stored: video and audio become ready when the duration probe lands, an image as soon as its bytes are in the bucket. list_assets shows only ready assets, so get_asset is what you poll after an upload.To add a local file, call create_upload (or POST /v1/uploads over REST). There are two routes and the size decides which. Under 256 KB — logos, crests, icons, SVG overlays — pass the file’s bytes as base64 and that single call stores them; it makes no outbound request on your behalf and asks none of you, so it is the route that works from a sandbox whose egress is allow-listed per host. Larger files come back with a signed upload URL you PUT to, in one request, with the same Content-Type; those bytes go straight to storage, so the server cannot confirm them and get_asset has to check — it answers bytes_uploaded. If your own network refuses that host, the result also carries a first-party upload URL on uploads.framelane.io — the same session, one Framelane domain to allow instead of Google’s. If that is refused too, the file is either small enough to inline or needs to be reachable at a public URL.Passing the duration you probed locally makes a video or audio asset usable immediately instead of waiting on the server probe. A file already at a public https URL needs none of this — pass the URL as an element’s source URL and it is fetched at the workspace on first render.

Waiting is one tool call, not a loop. wait_for_render / wait_for_task block until the job is terminal, streaming progress as it advances. If a call returns still_running: true (the server hold elapsed), call again. Ensure your MCP client’s per-tool timeout is ≥ 30s.

Tool errors carry a stable machine code. A domain failure is not a transport error: it comes back in the tool result as {"error": {"code", "message", "details"}} — branch on code. The set is invalid_request, not_found, conflict, quota_exceeded, rate_limited, email_not_verified, unauthorized, invalid_source (extract_brand_kit could not read the URL), unsupported_content_type (create_upload was given a type we do not store; the details.allowed list says what to re-encode to), inline_too_large (the base64 you sent create_upload is past the 256 KB inline cap — call it again without the bytes and PUT to the upload_url it returns), plan_required (create_project or edit_project made or used one of your own templates while your plan does not include custom templates; details.required_plan names the plan, and public templates are never gated) and internal. Only an unexpected exception surfaces as a real tool error.rate_limited is per workspace, not per IP, and only the submission tools are metered — create_render, render_project and run_task. Previews (create_preview / preview_project), reads and get_capabilities are unmetered. Its details carry limit_per_minute and retry_after_seconds; wait that long and retry rather than backing off blindly.

Connecting

Point your MCP host at https://mcp.framelane.io/mcp and send your key as a Bearer token.

Cursor / VS Code

Add to your MCP settings (~/.cursor/mcp.json, or the workspace .vscode/mcp.json):

{
  "mcpServers": {
    "framelane": {
      "url": "https://mcp.framelane.io/mcp",
      "headers": {
        "Authorization": "Bearer ${FRAMELANE_API_KEY}"
      }
    }
  }
}

Then ask: “Use the Framelane MCP to render this composition…”

Claude Desktop

Add to claude_desktop_config.json (mcp-remote bridges the hosted server over stdio):

{
  "mcpServers": {
    "framelane": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.framelane.io/mcp"],
      "env": {
        "FRAMELANE_API_KEY": "fl_live_..."
      }
    }
  }
}

Agent Skills

The Framelane Agent Skills are served by this server: each workflow skill is an MCP prompt, and every skill is also a get_capabilities section named skills.<name> (section='skills' lists them) for hosts that do not show prompts. Load one, then drive the calls through the tools above. How-tos for the REST API are in the Guides.

​Overview

​Getting a credential first

​Key tools

​Connecting

​Cursor / VS Code

​Claude Desktop

​Agent Skills

Overview

Getting a credential first

Key tools

Connecting

Cursor / VS Code

Claude Desktop

Agent Skills