# Build with AI agents

Let a coding agent such as Claude Code, Codex or Cursor make your videos. It can create projects, write and edit compositions, turn one project into many videos and render them. This page sets your agent up and gives it a first prompt.

Blitframe gives an agent three things:

| | What the agent gets | How to add it |
|---|---|---|
| [MCP server](#connect-over-mcp) | Tools: the API's operations, as calls the agent makes itself | Add `https://blitframe.codeartworks.com/mcp` to your agent |
| [Agent Skills](#install-the-skills) | Knowledge: how Blitframe works, the rules for `data.json`, and how to do each task | `npx skills add CodeArtworks/blitframe-skills` |
| [Plugin](#install-the-plugin) | The skills and the MCP server in one install, for Claude Code | `claude plugin marketplace add CodeArtworks/blitframe-skills`, then `claude plugin install blitframe@codeartworks` |

## Before you start

1. [Create a Code Artworks account](https://app.codeartworks.com/signup?product=blitframe) and confirm your email. Your first workspace starts on a free trial, so you need no card.
2. Open **Console → API keys** and create a key. Put it in an environment variable in the shell your agent runs in:

```bash
export BLITFRAME_API_KEY=blitframe_...
```

Keep the key out of the chat. The agent reads it from the variable.

## Start with one prompt

Paste this into your agent. It works in Claude Code, Codex, Cursor and other agents that can run shell commands.

```text
Set up Blitframe, the video render API by Code Artworks, and make a first video with it.

1. Install the Blitframe skills: npx skills add CodeArtworks/blitframe-skills -y
   Then read the blitframe and blitframe-create-video skills and follow them.
2. Connect the Blitframe MCP server at https://blitframe.codeartworks.com/mcp to this agent, the way
   https://codeartworks.com/docs/blitframe/mcp.md describes for it. Use the API key in the
   BLITFRAME_API_KEY environment variable. If it is not set, stop and ask me to create a key at
   https://app.codeartworks.com/blitframe/. Never print the key or commit it.
3. If the MCP tools only load in a new session, carry on now with the REST API and curl.
4. Make a 5-second 1280x720 video: the word "Hello" in white on a dark blue background,
   fading in. Render one frame and look at it, then render an MP4.
5. Give me the MP4 link and say what it cost in render seconds.
```

What the agent does:

| Step | What happens |
|---|---|
| 1. Installs the skills | The [skills](#install-the-skills) are short guides that teach it how Blitframe works. They are files in your project. Nothing runs. |
| 2. Connects the MCP server | The [MCP server](#connect-over-mcp) gives it Blitframe's operations as tools. Most agents load a new server's tools when the next session starts. So the first video may be made through the REST API instead, with the same result. |
| 3. Writes a composition | A small `data.json`: a background, and a line of text in a font from the [font library](/docs/blitframe/fonts). |
| 4. Creates a project and adds the composition | The edit answers with the project's first version. If its `renderable` is `false`, the agent fixes the `problems` and edits again. |
| 5. Previews, then renders | One frame costs 1 render second and shows whether the video will look right. The 5-second MP4 at 1280×720 costs 3 ([pricing](/docs/blitframe/renders#pricing)). |
| 6. Gives you the link | `mp4Url` downloads the video for an hour. The project and the render also show in the console. |

The free trial renders videos up to 30 seconds at up to 1280×720, with a small watermark ([plan limits](/docs/blitframe/limits#plan-limits)).

The prompt connects the server and installs the skills for you. To do it yourself, follow the next three sections.

## Connect over MCP

The MCP server lets the agent act. Each tool runs the same operation as a REST endpoint, with the same rules, limits and errors. When an agent connects, the server also sends it short instructions: the model, the workflow, the safety rules and the mistakes agents make most.

In Claude Code, with your key in `BLITFRAME_API_KEY`:

```bash
claude mcp add --transport http blitframe https://blitframe.codeartworks.com/mcp \
  --header "Authorization: Bearer $BLITFRAME_API_KEY"
```

[MCP for agents](/docs/blitframe/mcp#connect-your-agent) has the setup for Claude, Cursor, Codex, VS Code, Windsurf and any other client. In Claude you sign in instead of using a key.

## Install the skills

Skills help the agent act well. In your project folder (`npx` comes with [Node.js](https://nodejs.org)):

```bash
npx skills add CodeArtworks/blitframe-skills
```

The installer lists the skills and asks which agents to install them for. The same skills install from this site, without GitHub:

```bash
npx skills add https://codeartworks.com
```

| Option | Does |
|---|---|
| `--skill blitframe-render` | Installs one skill instead of all |
| `-g` | Installs for every project on your machine, not just this one |
| `-y` | Answers the installer's questions with their defaults |

Run the command again to get the newest version.

| Skill | What it teaches | A prompt that uses it |
|---|---|---|
| `blitframe` | Start here: projects and versions, the edit and render workflow, safety rules, uploads, errors, and when to use the MCP tools or the REST API | "Show me my Blitframe projects and what changed in the Summer ad lately." |
| `blitframe-create-video` | From nothing to a first MP4, with a starter composition | "Make a 5-second title card that says 'Hello' and render it." |
| `blitframe-data-json` | Writing and editing `data.json`: the rules agents get wrong most, and how to read the format reference one section at a time | "Move the logo 40 pixels to the right and make the background dark green." |
| `blitframe-variations` | Variations, batches and duplicates. Replacing text, images and video by layer, a video per row of a spreadsheet, and text fitting | "Keep a Spanish variation of the Summer ad and render it." |
| `blitframe-render` | Formats, quality, cost and refunds, waiting, batch renders, ZIP archives, share links, HTML5 ads | "Render the Summer ad as an MP4 and give me a link a client can watch." |
| `blitframe-docs` | Finding any docs page, and fetching it as Markdown | "What is the largest image Blitframe accepts?" |

You don't call a skill by name. Describe the task, and the agent picks the skill that fits. To make sure it reads one, name it: "use the blitframe-variations skill".

## Install the plugin

In Claude Code, the plugin installs the skills and connects the MCP server in one step. Add the Code Artworks marketplace, then install the plugin:

```bash
claude plugin marketplace add CodeArtworks/blitframe-skills
claude plugin install blitframe@codeartworks
```

Inside a session, the same two steps are `/plugin marketplace add CodeArtworks/blitframe-skills` and `/plugin install blitframe@codeartworks`.

Then connect the server:

1. Start Claude Code and run `/mcp`.
2. Choose `blitframe` and sign in with your Code Artworks account.
3. Approve it for one workspace. The page asks about an app called **MCP client**. That is Claude Code, under a neutral name because the name it gives itself contains "blitframe". It then acts as you, with your [role](/docs/blitframe/workspaces#roles) there.

Claude loads the skill a task needs on its own. You can also start one yourself: `/blitframe:blitframe`, `/blitframe:blitframe-create-video`, `/blitframe:blitframe-data-json`, `/blitframe:blitframe-variations`, `/blitframe:blitframe-render` or `/blitframe:blitframe-docs`.

The plugin connects by signing in. To connect with an [API key](/docs/blitframe/authentication) instead, for example on a server without a browser, skip the plugin and add the two parts yourself:

```bash
npx skills add CodeArtworks/blitframe-skills
claude mcp add --transport http blitframe https://blitframe.codeartworks.com/mcp \
  --header "Authorization: Bearer $BLITFRAME_API_KEY"
```

In Codex, Cursor and GitHub Copilot, set up the two parts yourself, which gives the agent the same skills and tools:

1. [Install the skills](#install-the-skills).
2. Connect the MCP server ([MCP for agents](/docs/blitframe/mcp#connect-your-agent) has the setup for each agent).

## Use Blitframe from your own agent

If you build an app on Claude's or OpenAI's API, the model can call Blitframe's tools itself. The model provider connects to the MCP server for you, with these settings:

| Setting | Value |
|---|---|
| Server URL | `https://blitframe.codeartworks.com/mcp` |
| Authentication | Your API key, sent as `Authorization: Bearer blitframe_...` |
| Tools | An allowlist of the tools your agent needs ([recommended allowlist](#recommended-allowlist)) |

Create a key for this agent alone ([API keys](/docs/blitframe/authentication)). The provider sends it with each call, so you can revoke it without affecting your other apps. Each render spends your workspace's [render seconds](/docs/blitframe/renders#pricing).

Your agent works best when it knows Blitframe's rules. Put the rules it needs from the [Agent reference](/docs/blitframe/agent-reference) in its system prompt, or tell it to read that page with `read_docs` first.

### Claude

The Messages API connects to the server with its MCP connector, a beta feature. This example uses the `anthropic` Python package (`pip install anthropic`) and reads your Anthropic key from `ANTHROPIC_API_KEY`:

```python
import os

import anthropic

BLITFRAME_TOOLS = [
    "list_projects", "get_project", "list_versions", "get_version", "read_file", "inspect_layers",
    "list_fonts", "read_data_json_reference", "read_docs", "get_usage",
    "create_project", "edit_project", "render", "get_render", "list_renders",
]

client = anthropic.Anthropic()
response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    betas=["mcp-client-2025-11-20"],
    mcp_servers=[{
        "type": "url",
        "url": "https://blitframe.codeartworks.com/mcp",
        "name": "blitframe",
        "authorization_token": os.environ["BLITFRAME_API_KEY"],
    }],
    tools=[{
        "type": "mcp_toolset",
        "mcp_server_name": "blitframe",
        "default_config": {"enabled": False},
        "configs": {name: {"enabled": True} for name in BLITFRAME_TOOLS},
    }],
    messages=[{"role": "user", "content": "List my Blitframe projects and render the newest one as an MP4."}],
)
print("".join(block.text for block in response.content if block.type == "text"))
```

`authorization_token` becomes the `Authorization: Bearer` header. `default_config` turns every tool off, and `configs` turns on the ones in the allowlist.

### OpenAI

The Responses API connects to the server with its `mcp` tool. This example uses the `openai` Python package (`pip install openai`) and reads your OpenAI key from `OPENAI_API_KEY`. Use a model that supports remote MCP servers:

```python
import os

from openai import OpenAI

BLITFRAME_TOOLS = [
    "list_projects", "get_project", "list_versions", "get_version", "read_file", "inspect_layers",
    "list_fonts", "read_data_json_reference", "read_docs", "get_usage",
    "create_project", "edit_project", "render", "get_render", "list_renders",
]

client = OpenAI()
response = client.responses.create(
    model="gpt-6.1-sol",
    tools=[{
        "type": "mcp",
        "server_label": "blitframe",
        "server_url": "https://blitframe.codeartworks.com/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"},
        "allowed_tools": BLITFRAME_TOOLS,
        "require_approval": "never",
    }],
    input="List my Blitframe projects and render the newest one as an MP4.",
)
print(response.output_text)
```

`require_approval: "never"` lets the model call the allowed tools without asking. If a person should confirm each call, leave approvals on and answer OpenAI's approval requests.

### Recommended allowlist

Start with the tools that read, plus the ones that make a video. They are the list in the examples above.

| Tools | What they let the agent do |
|---|---|
| `list_projects`, `get_project`, `list_versions`, `get_version`, `read_file`, `inspect_layers` | Find a project, and read its composition and editable layers |
| `list_fonts`, `read_data_json_reference`, `read_docs`, `get_usage` | Pick fonts, read the format reference and these docs, and check the balance |
| `create_project`, `edit_project`, `render`, `get_render`, `list_renders` | Make a project, change it, render it and fetch the result |

Leave out the tools that delete, publish, redirect or revoke: every `delete_` and `cancel_` tool, `create_share_link`, the webhook tools and `revoke_api_key`. Add one only when your app asks a person before the agent uses it. The [Agent reference](/docs/blitframe/agent-reference#tools) lists every tool.

## What to ask for

Once your agent is set up, ask in plain words:

- "Make a 10-second 1920×1080 intro with our name and tagline, and render it." On the free trial, the agent tells you this needs a plan.
- "Change the headline of the Summer ad to 'Last days' and render a frame so I can check it."
- "Add our logo from `logo.png` above the headline and render it again."
- "Render this video with the headline in Spanish and in French."
- "Here is products.csv. Render the Product card project once per row, with that row's name and price, and give me the videos as one ZIP."
- "The Spanish text overflows the price tag. Make it fit."
- "Render this version for The Trade Desk as an HTML5 ad."
- "Give me a link I can send to a client to watch it." The agent asks before it makes anything public.
- "Why did my last render fail?"

## What stays with you

| What | How it stays with you |
|---|---|
| The design | Blitframe has no AI features of its own. It renders exactly the composition it is given, and the agent you bring writes or edits that composition. |
| Your API keys | Agents can list and revoke keys, but only you create them, in the console. |
| Spending | A render costs render seconds. A well-behaved agent checks the balance first and previews with a few frames. The skills and the server's instructions tell it to. |
| Anything public or permanent | The skills and the server's instructions tell the agent to ask you first. That covers deleting something, cancelling a render, creating a [share link](/docs/blitframe/sharing) and changing a [webhook](/docs/blitframe/webhooks). |

## Details

### Skills and the MCP server

The skills and the server do different jobs, and work best together.

| | Skills | MCP server |
|---|---|---|
| Gives the agent | Knowledge | Tools |
| Loaded | When a task needs it | When the agent starts |
| Without the other | The agent calls the REST API with curl and your API key | The agent has the tools and the server's short instructions |

With curl, the agent reads your key from the `BLITFRAME_API_KEY` environment variable ([Authentication](/docs/blitframe/authentication)).

A skill is a folder with a `SKILL.md` file, in the open [Agent Skills](https://agentskills.io) format. Claude Code, Codex, Cursor, GitHub Copilot and many other agents read it. The agent sees each skill's one-line description and loads the rest only when a task needs it, so a skill costs nothing until then.

Without the server or the skills, an agent can still read these docs. Every page is Markdown at `/docs/blitframe/{page}.md`, and [llms.txt](/docs/blitframe/llms.txt) lists them all.

### Where the skills come from

The skills are plain Markdown, published in two places with the same content:

- The repository [CodeArtworks/blitframe-skills](https://github.com/CodeArtworks/blitframe-skills) on GitHub.
- This site, listed at `https://codeartworks.com/.well-known/skills/index.json`.

Read them before you install them, as you would any instructions you give your agent. They contain no scripts.

### What the plugin contains

The plugin lives in the repository [CodeArtworks/blitframe-skills](https://github.com/CodeArtworks/blitframe-skills). It holds:

- The six Blitframe skills: Markdown files, no scripts.
- The address of the Blitframe MCP server, `https://blitframe.codeartworks.com/mcp`.

It has no hooks and runs no code on your machine. Every call the agent makes to Blitframe goes through the MCP server with the access you gave it, under the same [limits](/docs/blitframe/limits) as the API.

The repository also carries the manifests Codex, Cursor and GitHub Copilot read. They are the portable [Agent Plugins](https://agent-plugins.org) format (`plugin.json` and `mcp.json`), and a manifest each for Codex and Cursor.

### Update or remove the plugin

Update the plugin from the `/plugin` panel. To remove the marketplace, and the plugin with it:

```bash
claude plugin marketplace remove codeartworks
```

To take away the access you approved, disconnect it in **Console → Your account → Security**, under **Connected apps**, where it is listed as **MCP client** ([signing in](/docs/blitframe/mcp#signing-in-instead-of-a-key)).

### For the agent itself

- [Agent reference](/docs/blitframe/agent-reference): every tool and the rules for using it.
- [Composition format](/docs/blitframe/data-json-format): the reference for `data.json`, readable one section at a time.
- [Errors](/docs/blitframe/errors) and [Limits](/docs/blitframe/limits).
