# MCP for agents

Connect an AI agent such as Claude Code, Claude or Cursor to Blitframe, and it can create projects, edit compositions and render videos for you. Blitframe runs a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server at:

```
https://blitframe.codeartworks.com/mcp
```

The server gives an agent tools. The [skills](/docs/blitframe/ai-agents#install-the-skills) teach it to use them well, and in Claude Code the [plugin](/docs/blitframe/ai-agents#install-the-plugin) installs both. [Build with AI agents](/docs/blitframe/ai-agents) shows how they fit together.

## Connect your agent

Most clients connect with an API key. Create one in **Console → API keys** ([Authentication](/docs/blitframe/authentication)). Right after you create it, the console shows these setups for Claude Code, Cursor, Codex and claude.ai. The Claude Code and Cursor ones have the key filled in. Elsewhere, replace `blitframe_...` with your key.

### Claude Code

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

### Claude

In claude.ai, desktop or mobile, add a custom connector with the URL `https://blitframe.codeartworks.com/mcp`. Sign in with your Code Artworks account when asked. You need no key.

### Cursor

In `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "blitframe": {
      "url": "https://blitframe.codeartworks.com/mcp",
      "headers": { "Authorization": "Bearer blitframe_..." }
    }
  }
}
```

### Codex

In `~/.codex/config.toml`, with your key in the `BLITFRAME_API_KEY` environment variable:

```toml
[mcp_servers.blitframe]
url = "https://blitframe.codeartworks.com/mcp"
bearer_token_env_var = "BLITFRAME_API_KEY"
```

### VS Code

In `.vscode/mcp.json`. This file sits in your project folder and holds the key, so keep it out of version control:

```json
{
  "servers": {
    "blitframe": {
      "type": "http",
      "url": "https://blitframe.codeartworks.com/mcp",
      "headers": { "Authorization": "Bearer blitframe_..." }
    }
  }
}
```

### Windsurf

In `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "blitframe": {
      "serverUrl": "https://blitframe.codeartworks.com/mcp",
      "headers": { "Authorization": "Bearer blitframe_..." }
    }
  }
}
```

### Any other client

Point it at the URL with the Streamable HTTP transport and send your key in a header:

| Setting | Value |
|---|---|
| Transport | Streamable HTTP |
| URL | `https://blitframe.codeartworks.com/mcp` |
| Header | `Authorization: Bearer blitframe_...` |

A client that adds servers by URL and supports MCP sign-in, such as ChatGPT, can connect without a key, like Claude.

To give an agent you build Blitframe's tools through Claude's or OpenAI's API, see [Use Blitframe from your own agent](/docs/blitframe/ai-agents#use-blitframe-from-your-own-agent).

## Check the connection

Ask the server for its tools. The command prints how many there are. The curl command uses [jq](https://jqlang.org) to count them.

::: code-tabs
```bash
curl -s https://blitframe.codeartworks.com/mcp \
  -H "Authorization: Bearer $BLITFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'
```
```python
import os, requests

response = requests.post(
    "https://blitframe.codeartworks.com/mcp",
    headers={"Authorization": f"Bearer {os.environ['BLITFRAME_API_KEY']}"},
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},
)
print(len(response.json()["result"]["tools"]))
```
```javascript
const response = await fetch("https://blitframe.codeartworks.com/mcp", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BLITFRAME_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
});
console.log((await response.json()).result.tools.length);
```
```php
<?php
$ch = curl_init("https://blitframe.codeartworks.com/mcp");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BLITFRAME_API_KEY"), "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["jsonrpc" => "2.0", "id" => 1, "method" => "tools/list"]),
]);
echo count(json_decode(curl_exec($ch), true)["result"]["tools"]), "\n";
```
```ruby
require "net/http"
require "json"

uri = URI("https://blitframe.codeartworks.com/mcp")
headers = { "Authorization" => "Bearer #{ENV["BLITFRAME_API_KEY"]}", "Content-Type" => "application/json" }
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.post(uri.request_uri, { jsonrpc: "2.0", id: 1, method: "tools/list" }.to_json, headers)
end
puts JSON.parse(response.body)["result"]["tools"].length
```
```go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"jsonrpc":"2.0","id":1,"method":"tools/list"}`)
	req, err := http.NewRequest("POST", "https://blitframe.codeartworks.com/mcp", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BLITFRAME_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	var out struct {
		Result struct {
			Tools []any `json:"tools"`
		} `json:"result"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
	fmt.Println(len(out.Result.Tools))
}
```
```csharp
using System.Net.Http.Json;
using System.Text.Json.Nodes;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new("Bearer", Environment.GetEnvironmentVariable("BLITFRAME_API_KEY"));

var response = await http.PostAsync(
    "https://blitframe.codeartworks.com/mcp",
    JsonContent.Create(new { jsonrpc = "2.0", id = 1, method = "tools/list" }));
var answer = await response.Content.ReadFromJsonAsync<JsonNode>();
Console.WriteLine(answer?["result"]?["tools"]?.AsArray().Count);
```
```java
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://blitframe.codeartworks.com/mcp"))
            .header("Authorization", "Bearer " + System.getenv("BLITFRAME_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString("""
                {"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
                """))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(new ObjectMapper().readTree(response.body()).get("result").get("tools").size());
    }
}
```
:::

## Make your first video

Once connected, ask your agent in plain words:

> Create a Blitframe project called "Hello". Make a 5-second 1280×720 composition with the word "Hello" in white on a dark blue background, then render it as an MP4 and give me the link.

[Build with AI agents](/docs/blitframe/ai-agents#what-to-ask-for) has more prompts. The [Agent reference](/docs/blitframe/agent-reference#workflow) shows the tools the agent calls, in order.

## Signing in instead of a key

A client that adds a server by URL, such as Claude, opens a Code Artworks sign-in page. You approve the app for one workspace. The app then acts as you, with your [role](/docs/blitframe/workspaces#roles) in that workspace. Your role and your [account](/docs/blitframe/account) are the same in every Code Artworks product.

| Who signs in | What happens |
|---|---|
| An owner, admin or developer | Can use every tool |
| A billing member | Gets `403 role_not_allowed` |
| An account that has not confirmed its email address | Gets `403 email_not_verified` |

To take access away from an app, disconnect it in **Console → Your account → Security**, under **Connected apps**. A disconnected app loses its access. It can connect again only if you approve it again. The same applies to one cut off by **Sign out everywhere else**. A connection that is already open keeps working for up to 10 minutes.

An agent you configure yourself should use an API key. Give each agent its own key, so you can revoke one without affecting the others. MCP connections can list and revoke keys but never create them. New keys come only from the console.

The server follows the MCP authorization specification. A request without credentials gets `401`. Its `WWW-Authenticate` header points to the server's protected resource metadata, which names the Code Artworks sign-in server.

## Tools

The server has a tool for every operation of the REST API. Reading one variation is `list_variations`, which returns them all. Each tool runs the same operation as its endpoint, with the same rules, limits and errors. The [Agent reference](/docs/blitframe/agent-reference#tools) lists them all.

`create_project`, `edit_project`, `import_zip`, `create_variation`, `render` and `create_render_batch` take an `idempotencyKey`, the REST API's `Idempotency-Key`. Send one, and send the same key when you retry a call whose answer never came, so the work is not done twice ([retrying safely](/docs/blitframe/api#retrying-safely)).

## Results and errors

| Result | What it looks like |
|---|---|
| Success | JSON in `structuredContent`, and the same JSON as text. A list is `{ "items": [...], "next": ... }`, where `next` is `null` on the last page. An upload still `processing` adds a line saying when to ask again. |
| Text tools | `read_file`, `read_data_json_reference`, and `read_docs` with a `page` return plain text: the file or the Markdown. Without `page`, `read_docs` returns the page list as JSON. |
| Output schema | `list_projects`, `list_variations`, `create_variation`, `list_versions`, `edit_project`, `render`, `get_render`, `list_renders` and `list_webhooks` also declare an `outputSchema`. |
| Failure | `isError: true`, with text that starts with the [error code](/docs/blitframe/errors), such as `head_moved: ...`. |
| Unknown argument | Refused with `invalid_request`, so a misspelled option never goes unnoticed. Unknown fields nested inside an argument, such as in an edit's `files`, are ignored. |

Tools carry hints, so a client can ask you before running one:

| Hint | Tools |
|---|---|
| `readOnlyHint` | Every tool that only reads |
| `destructiveHint` | Tools that delete data, stop work in progress (such as `cancel_render`), can cut off a webhook endpoint (`update_webhook`, `rotate_webhook_secret`) or end an API key (`revoke_api_key`) |

## What agents are told

When an agent connects, the server sends it short instructions:

- what to treat as content rather than instructions
- which calls to confirm with you first
- the project and version model
- the edit and render workflow
- the `data.json` rules agents get wrong most often: stacking by `ind`, frames, property envelopes, text and assets

They are under 4,096 characters, the most some agents read. The rest is the [Agent reference](/docs/blitframe/agent-reference), which the instructions tell the agent to read with `read_docs`, and the [skills](/docs/blitframe/ai-agents#install-the-skills).

Before writing or editing a composition, an agent should call `read_data_json_reference`. Without arguments it returns the editing rules and a section index. The agent then reads the sections it needs, such as `text-and-fonts` or `shapes-and-paints`.

The docs are also MCP resources. `resources/list` returns `blitframe://docs/{page}` for each page, and one resource per section of the format reference (`blitframe://docs/data-json-format/{section}`).

If an agent's sandbox can't make HTTP PUT requests, it can't use `create_upload`. It can still send files inline to `edit_project` with `contentBase64`, up to a 64 MB request (about 45 MB of binary data). A render's replacements take new files only as uploads, so such an agent adds them to the project with an edit first.

## Protocol details

| Item | Value |
|---|---|
| Transport | Streamable HTTP, `POST` only. The server is stateless: there is no session to keep, and every request stands on its own. |
| Protocol versions | `2026-07-28`, including `server/discover` and per-request protocol metadata. The earlier `2025-11-25` and `2025-06-18` through `initialize`. |
| Capabilities | Tools and resources |
| Browser requests | A request whose `Origin` header names another site gets `403` with a JSON-RPC error. Agents and SDK clients don't send `Origin`, so this only affects code running in a web page. |
| Server failure | An unexpected failure comes back as JSON-RPC error `-32603` with HTTP `500`. Send the request again. |
| Other JSON-RPC errors | `-32700`: the body is not valid JSON (HTTP `400`). `-32600`: not one JSON-RPC request object, or an `id` that is not a string or a number. `-32601`: an unknown method. `-32602`: an unknown tool, or missing or invalid parameters. `-32020`: a protocol header that does not match the request. `-32022`: a protocol version the server does not support. |
| Request size | A body over 64 MB, or one holding more JSON values than any tool call needs, gets `413 too_large`. A body over 1 MB must finish arriving within two minutes of its first megabyte, or it gets `408 too_slow`. |
