Connect via MCP

Two commands: save your key once, then connect your client. From then on the agent checks your balance and prices, creates projects, writes strategies and plans, and orders pictures, clips and songs — as tools built into Claude Code, Cursor or Codex.

MCP (Model Context Protocol) is the standard way agents get tools. Already use the protocol link (“Agent link” in Settings)? Keep it — MCP adds the tools, same key and projects. The commands are for the macOS / Linux terminal; on Windows use Git Bash or WSL.

1. Put your key in .env
2. Connect: Claude Code · Cursor · Codex
3. Check
4. If it doesn't work

What your agent can do
Agent2Agent — soon
Security
For developers

1. Put your key in `.env`

Your API key is in the dashboard: Settings → For developers → API key → Copy. Then, in the folder where you run your agent, one command asks for the key (typing is hidden) and writes it:

printf 'Paste your Video Blade key: ' && read -rs VB_KEY && echo \
  && { [ -f .env ] && grep -v '^VB_API_KEY=' .env; printf 'VB_API_KEY=%s\n' "$VB_KEY"; } > .env.new \
  && mv .env.new .env && echo "Saved to .env"

It adds one line, VB_API_KEY=vb_…, to the file .env (hidden in Finder and Explorer: names that start with a dot are). Running it again replaces the key. Already connected the agent with the protocol link? Then the line is there: grep VB_API_KEY .env prints it. The key never goes into chat or into git.

2. Connect

Claude Code

claude mcp add --transport http video-blade https://app.video-blade.com/mcp \
  --header "Authorization: Bearer $(grep '^VB_API_KEY=' .env | cut -d= -f2-)"

Run it in the folder with .env, then start a new Claude Code session there — a session that is already open does not see new servers. Claude Code remembers the server for this folder; to have it in every folder, add -s user to the command. To remove it: claude mcp remove video-blade.

Cursor

Cursor reads servers from .cursor/mcp.json in the project. The key goes into that file, so the command also adds the file to .gitignore; if the file already exists, the command stops and tells you.

test -e .cursor/mcp.json && echo "You already have .cursor/mcp.json: add the video-blade entry by hand" || {
  mkdir -p .cursor && printf '{"mcpServers":{"video-blade":{"url":"%s","headers":{"Authorization":"Bearer %s"}}}}\n' \
    "https://app.video-blade.com/mcp" "$(grep '^VB_API_KEY=' .env | cut -d= -f2-)" > .cursor/mcp.json \
  && echo '.cursor/mcp.json' >> .gitignore && echo "Saved. Restart Cursor"; }

Restart Cursor; the server appears in its MCP settings. If the file already exists, add this entry under mcpServers, with your key in place of <your key>; to remove the server, delete the entry:

"video-blade": {"url": "https://app.video-blade.com/mcp", "headers": {"Authorization": "Bearer <your key>"}}

Codex

Codex takes the key from the VB_API_KEY variable each time it starts. The first line sets the variable for this terminal window, the second registers the server:

export VB_API_KEY="$(grep '^VB_API_KEY=' .env | cut -d= -f2-)"
codex mcp add video-blade --url https://app.video-blade.com/mcp \
  --bearer-token-env-var VB_API_KEY

To stop repeating the export line in every new window, put export VB_API_KEY=<your key> into your shell profile (~/.zshrc or ~/.bashrc) — a file only you can read; when the key changes, change it there too. To remove the server: codex mcp remove video-blade.

3. Check

Ask the agent for your balance — a ready phrase:

What's my Video Blade balance?

The agent answers with your balance in tokens. claude mcp list shows the server with a check mark, codex mcp list lists it, Cursor shows it in its MCP settings. After the agent's first call, Settings → Connect your agent shows Agent connected with the date.

4. If it doesn't work

“command not found” — the client is not installed or not in PATH. Install it and open a new terminal window.
“.env: No such file or directory”, or the key in the command comes out empty — you are not in the folder with .env, or the file has no VB_API_KEY= line. Go to that folder or run step 1 again.
The server shows a cross, “Failed to connect” or 401 — the key is wrong or was regenerated. Run step 1 again with the current key (it replaces the old one), then reconnect: Claude Code — claude mcp remove video-blade and the connect command again; Cursor — delete .cursor/mcp.json if Video Blade is the only server in it and run the command again, otherwise replace the key in the file; Codex — the export line again, and the new key in your shell profile if the old one is there.
“already exists” when adding — the server is registered already. Remove it first, then add it again.
The agent does not see the tools — in Claude Code, start a new session: the one that was open when you ran the command does not see new servers. The tools are there in one folder and missing in another — the server was added for one folder; run the command there too, or once with -s user.
Cursor does not list the server — restart Cursor and look at its MCP settings; check that .cursor/mcp.json is valid JSON and sits in the folder Cursor opened.
Codex answers “no key” or 401 — run the export line in the same window before codex, or put the key into your shell profile.
The agent answers 402 — no active plan or not enough tokens: pick a plan or top up in the dashboard.
Anything else — write to support@video-blade.com with the command you ran and its output, without the key.

What your agent can do

Balance and prices — your token balance, the price of every model, your account and plan.
Projects — create and set up projects; read and write every section the dashboard shows: strategy and brief, matrix, content plan, scripts, references, characters, songs, pictures, videos, albums, ready videos.
Generation — order pictures, clips, songs, album covers and character photos. These spend tokens: the agent names the price in tokens before it orders.
Protocols — read Video Blade's protocols and prompts, so it knows what to ask you and in which order.
Feedback — with your permission (Settings → Share your requests) the agent sends Video Blade the text of what you ask it, so the protocols get better at it. When something stops it, it reports what happened in its own words, without your text.
Deleting — only a record you asked to delete. Every action is logged in the project as the agent's.

All 26 tools, as the agent sees them

read only reads · writes saves what you asked for · spends tokens a paid order · deletes removes a record.

Tool	What it does
`get_account`read	Your account: name, plan (null — no plan: generation answers 402 until the user picks one in the dashboard), balance in tokens, locale and share_requests (null — the agent has not asked yet; protocol start says how).
`get_balance`read	Token balance and the price of one token in USD.
`list_protocols`read	Index of protocols and prompt categories: names, versions, sha256 and keywords. Compare the hashes with the ones you saved and re-read what changed (protocol conventions, section 3).
`read_protocol`read	The text of a protocol or a prompt (markdown) by its name from list_protocols. Read 'start' first and run every task by its protocol.
`list_models`read	Public model catalog with the price in tokens per unit (per image, per second or clip, per song) and the parameters each model takes. Name the price to the user before ordering.
`list_projects`read	Your projects, newest first.
`create_project`writes	Create a project; the dashboard shows it at once and logs the action as the agent's.
`get_project`read	Project card and settings, with the number of records per section.
`update_project`writes	Change project settings: name, description, status (active \| archived), video_format (9:16 \| 16:9 \| 1:1), models {image, video, music: slug from list_models}, languages {content: [codes], work: code}, story_style (a prompt name of category story-styles). Send only the fields you change; get_section_fields('project') lists them with limits.
`get_section_fields`read	Field names, types and limits of a section's records (create and update), of the project settings, the strategy or the brief — straight from the models that validate the API.
`list_items`read	Records of a project section, oldest first. filters — the section's list filters as in the API reference (status, kind, section, category, series_id, published); get_section_fields names them.
`get_item`read	One record of a section by id — also how you poll a generation.
`create_item`writes	Create a record in a section with the fields of the API reference (get_section_fields shows them). The dashboard marks it as new from the agent.
`update_item`writes	Update the fields you send of one record; nested lists (versions, stages, media, links) are replaced whole — send the current list with your changes applied.
`delete_item`deletes	Delete one record of a section. Ask the user first.
`get_strategy`read	The project's strategy (product, audience, promise, proof, cta, demand_type, notes) with every matrix card.
`put_strategy`writes	Save the strategy fields (product, audience, promise, proof, cta, demand_type: hot \| created \| mixed, notes) — all of them, as in PUT /strategy.
`get_brief`read	The strategy brief: the questions with answers, sources and confirmations, plus the counters (count, answered, suggested, target, done).
`put_brief`writes	Replace the whole brief: every question {id, topic, q, a, source, confirmed, agent_a}; keep the ids of existing questions, send confirmed and agent_a back as you got them.
`generate_images`spends tokens	Draw the pictures of an image series with its saved model and settings; count — variants per order (1–4, empty — as saved). Answers the generation ids and the tokens held; the pictures land in section assets with this series_id in 1–2 minutes — poll list_items('assets', {'series_id': …}). Price per picture: list_models('image').
`generate_clip`spends tokens	Order a clip for a video session: prompt, model (slug from list_models('video'); empty — the project's model), start_url and end_url (frames: a project picture or your URL), duration in seconds (0 — the model's first option), resolution, audio, title. Answers the generation id and the tokens; the clip lands in the session's media and in the library — poll get_item('video-sessions', …).
`generate_song`spends tokens	Order a song or a cover by the track's saved title, style, lyrics and settings (a track with a source recording is generated as a cover). Answers the generation id, mode and the tokens held; the versions appear in the track in 2–4 minutes — poll get_item('tracks', …). Price: list_models('music').
`generate_cover`spends tokens	Draw an album cover: a square picture by the prompt (scene, mood, style; the service adds the album title and artist name itself — do not describe lettering). Tokens are held at once; in 1–2 minutes the album's cover_url holds the picture, cover_error names a failure.
`generate_character_photo`spends tokens	Draw a photo of a character: its existing photos go to the model as references with their angles; prompt adds pose, outfit, setting and light (empty — a neutral shot of the angle); view — the angle; aspect_ratio — 1:1, 3:4, 4:3, 9:16 or 16:9 (empty — the project's video format). The photo appears in the character's photos in 1–2 minutes, photo_error names a failure.
`report_request`writes	What the user asked you, in their own words, with your one-line English summary, the protocol you run as command and the project — only while share_requests is true (conventions, section 10). Never files, keys or contact details.
`report_mistake`writes	What stopped you from following a protocol and the fix you found, in your own words — never the user's text (conventions, section 12). Needs no permission from the user.

Agent2Agent soon

Not available yet. Agent2Agent (A2A) lets one agent hand a task to another agent and get the result back. Video Blade plans to publish an agent card — a description of what it can do at a standard address on this host, so other agents can find it — and to accept tasks with the same API key; the results will come back as links to the media in your project.

Today: connect over MCP (above) or use the REST API. Building on A2A and want Video Blade in your agent's roster sooner? Write to support@video-blade.com.

Security

The key is your account: whoever holds it can create projects and order generations charged to your balance. Keep it in .env, in the client's config and, for Codex, in your shell profile — nowhere else.
If the key leaks, regenerate it in Settings — the old one stops working at once. Then follow the 401 line of step 4: step 1 again with the new key and reconnect the clients.
Without a key the server answers 401. Errors of an operation come back inside the tool result with the same codes as the REST API: 402 — no plan or not enough tokens, 404 — unknown record, 422 — invalid fields.

For developers

Server: https://app.video-blade.com/mcp — MCP over Streamable HTTP with JSON responses and no sessions: every call stands on its own, like a REST request. Authentication is the API key as a bearer token; the server advertises no OAuth. Only POST is served; GET answers 405 with a pointer to this page. The tools are the same operations as the REST API and share its validation, activity log and token ledger.

Not in MCP yet — use the REST API with the same key: file uploads (a cover's source recording, character photos and voice samples, album covers, assets), comments and reference marks, publishing song versions to the site, reading a reference link, sending a script to production, album track lists, stock footage search.