> ## Documentation Index
> Fetch the complete documentation index at: https://docs.framelane.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Framelane to Claude, Cursor, or any MCP-capable agent framework.

## 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`](https://framelane.io/llms.txt), the
installable [skill](https://framelane.io/skill.md), 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:

1. `POST /v1/signup` with a `workspace_name` and an `email` you control — returns an `fl_`
   API key and emails a 6-digit code.
2. `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](/introduction/self-provisioning). 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 verified credential (an `fl_` key or a Clerk OAuth token). The ones an
agent reaches for most:

| Tool                                                                     | Does                                                                            |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `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, remove-background, super-resolution, gaze-redirect) |
| `wait_for_task` / `get_task` / `get_task_download`                       | Await / fetch / download a task                                                 |
| `create_preview`                                                         | Validate (`dry_run`) or cheaply preview a composition                           |
| `create_project` / `edit_project` / `preview_project` / `render_project` | The stateful, versioned edit loop                                               |

<Tip>
  Start by reading the `framelane://capabilities` resource — the machine-readable menu of
  every effect, motion, transition, format, and task parameter (with valid ranges), so the
  agent builds a correct request on the first try instead of discovering limits through `422`s.
</Tip>

<Tip>
  **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.
</Tip>

<Tip>
  Tool errors carry a stable machine code: domain failures come back as
  `{"error": {"code", "message", "details"}}` — branch on `code` (`quota_exceeded`,
  `email_not_verified`, `conflict`, `invalid_request`, `not_found`).
</Tip>

## 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`):

```json theme={null}
{
  "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):

```json theme={null}
{
  "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](/agent-skills/overview) are static YAML playbooks — read them
from the docs (append `.md`) or install the [skill](https://framelane.io/skill.md), then
drive the calls through the tools above.