MCP for agents
View as MarkdownConnect 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 (MCP) server at:
https://blitframe.codeartworks.com/mcp
The server gives an agent tools. The skills teach it to use them well, and in Claude Code the plugin installs both. Build with AI agents shows how they fit together.
Connect your agent
Most clients connect with an API key. Create one in Console → API keys (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
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:
{
"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:
[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:
{
"servers": {
"blitframe": {
"type": "http",
"url": "https://blitframe.codeartworks.com/mcp",
"headers": { "Authorization": "Bearer blitframe_..." }
}
}
}
Windsurf
In ~/.codeium/windsurf/mcp_config.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.
Check the connection
Ask the server for its tools. The command prints how many there are. The curl command uses jq to count them.
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'
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"]))
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
$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";
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
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))
}
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);
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 has more prompts. The Agent reference 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 in that workspace. Your role and your 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 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).
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, 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.jsonrules agents get wrong most often: stacking byind, frames, property envelopes, text and assets
They are under 4,096 characters, the most some agents read. The rest is the Agent reference, which the instructions tell the agent to read with read_docs, and 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. |