The connector

Connector status: LIVE. The fastest path is the hosted connector at https://mcp.videngineer.com/mcp — live in Claude (claude.ai and the desktop app) and Claude Code. Add the URL, sign in to your own account, done (no key, no config). ChatGPT, Cursor, OpenClaw and Hermes are coming soon. Prefer to run it yourself? The API-key bearer local install is below. Full signatures: Connector API.

The connector answers: how do I let my assistant read my teardowns directly, instead of pasting a report into it? The videngineer connector is an MCP server. It gives your assistant eighty-three tools for the analyses and Canvas boards on your own account (plus public teardown discovery) — over the hosted endpoint, or run beside your tools with an API key. Like For your AI, this page names clients and tools because its purpose is setup; the rest of the docs stay product-side.

What it is, and what it is not

It does	It does not
Read the teardowns on your account: hook, scorecard, beats, blueprint, transcript, cuts	Edit or delete your analyses or saved Library files
Hand one cut to your assistant at a time, so it reasons over a shot instead of a whole report	Run anything on its own or on a schedule
Start a new analysis when you explicitly ask for one	Touch boards shared with you — only your own boards
Build and edit your own Canvas boards when you ask	Reach any account but yours
Bundle up to ten of your analyses into one payload for your own tools

The connector supplies context. The making happens in your own tools and workflow. Nothing about the connector changes what videngineer is for - you study the mechanism and bring your own footage, subject, and brand.

Before you start

An API key. In the app: Account → API access → Create key. Reveal and copy it there, regenerate it to replace it immediately, or revoke it outright. See Account & billing.
API access on your account. Access and allowances follow your account’s plan; if the API access card shows a plan upsell instead of a Create key button, your plan does not include API access. If your plan later drops the entitlement, an existing key is suspended rather than deleted, and upgrading reactivates the same key. (Only needed for the local API-key install — the one-click hosted connection needs no key.)
Python with the MCP runtime: pip install "mcp[cli]" (or uv add "mcp[cli]").

The key acts as your account, on your plan. What the connector can do is exactly what you can do in the app, and no more.

Connect the hosted connector

The fastest path — no key, no file. Connector URL: https://mcp.videngineer.com/mcp.

Platform	Status
Claude (claude.ai and the desktop app)	Live
Claude Code	Live
ChatGPT	Coming soon
Cursor, OpenClaw, Hermes	Coming soon

Claude (web and desktop)
Claude Code

Add a custom connector

In Claude, open Settings → Connectors → Add custom connector. Name it videngineer and paste https://mcp.videngineer.com/mcp.

You sign in to videngineer and approve the connection. The grant is scoped (mcp:read, mcp:analyze, mcp:cut_brief, mcp:build_cuts, mcp:canvas) — a read-only grant is a real option, and board editing is its own permission.

The eighty-three tools appear

The same tools listed below are now available in your chat. Nothing runs on its own; spend tools still charge only on an explicit call.

Add the connector

claude mcp add --transport http videngineer https://mcp.videngineer.com/mcp

In Claude Code, run /mcp, pick videngineer, and sign in. Approve access to your own account and the eighty-three tools are ready.

Install locally with an API key

Prefer to run the connector yourself? Three steps. Verified in Claude Desktop and Claude Code. Other MCP clients that launch a local stdio server, including Cursor, take the same command, args, and env values, but we have not verified them.

Create your key

In videngineer: Account → API access → Create key, then Reveal and Copy. One key per account. If it leaks, Regenerate from the same card and the old key stops working immediately.

Download the connector

One file plus its runtime.

pip install "mcp[cli]"
curl -O https://videngineer.com/mcp/videngineer_mcp.py

Add one config entry, then restart

Point your client at the file you just downloaded and put your key in env.

Claude Desktop
Claude Code

Edit claude_desktop_config.json, then fully quit and reopen the app.

{
  "mcpServers": {
    "videngineer": {
      "command": "python",
      "args": ["/absolute/path/to/videngineer_mcp.py"],
      "env": { "VIDENGINEER_API_KEY": "<your key>" }
    }
  }
}

Add the same block to .mcp.json in your project root, then restart Claude Code.

{
  "mcpServers": {
    "videngineer": {
      "command": "python",
      "args": ["/absolute/path/to/videngineer_mcp.py"],
      "env": { "VIDENGINEER_API_KEY": "<your key>" }
    }
  }
}

A ready-to-edit copy of that block is downloadable at claude_desktop_config.example.json.

Ask for something small first: “Use videngineer to list my analyses.” If the eighty-three tools are wired, you get your library back, newest first.

For the local connector, two optional environment variables: VIDENGINEER_BASE_URL overrides the API host (defaults to https://videngineer.com), and VIDENGINEER_WAIT_CAP caps how long get_report polls a running analysis, in seconds (defaults to 300). Local context requests retain a 90-second timeout, so the last request can finish after that polling cap. Hosted calls use a separate maximum 36-second budget; an operator can lower it with a positive integer VIDENGINEER_WAIT_CAP, but cannot raise it.

The eighty-three tools

Thirty-six tools only read. Two spend wallet credits or plan minutes. Forty-five build the cut grid, edit your own Canvas boards, or save a reference into your Library at 0 credits from your balance. Eighty-one of the eighty-three never spend credits. The split is enforced server-side, not by prompt. Full signatures, param tables, and measured response excerpts: Connector API.

Read-only, 0 credits (35)

The study library filters across seven tag dimensions — storytelling approach, opening hook, production style, techniques to study, job of the video, length, and platform. Browse the full tag schema (every tag and what it means), or call list_teardown_tags for the live vocabulary with per-tag counts. Filters combine with AND, so find_teardowns(format="ads", tags=["screen-capture","hook-cold-open"], quality="4k") narrows the shelf to exactly the reference you want to study.

Tool	Arguments	What comes back
`find_teardowns(goal, format, tags, hook_type, quality, limit, offset)`	all optional	Public study-library shortlist (≤25; compact above 5) with permalinks + `analyze.source_url`; tags AND across seven dimensions
`list_teardown_tags(dimension, include_counts)`	optional	The tag vocabulary for `find_teardowns` — dimensions, keys, definitions, published counts
`get_teardown(slug)`	`slug`	One public teardown’s study detail: card, tags by dimension, bounded study, related
`find_analyses(query, hook_type, format, intent, …)`	all optional	Your library search — refs only; `intent` = recommend mode (empty until labeler backfill)
`find_cuts(…)`	all optional	Cross-library cut index — empty until cut-index backfill
`list_analyses(limit, offset, query)`	optional	Your analyses, newest first, paged (default 25, max 60)
`get_status(job_id)`	`job_id`	One status snapshot plus progress; hosted pending work includes an estimate and an ask-again note
`get_report(job_id, preset, fields, wait)`	`preset="lean"` (default) or `"full"`; or `fields=[...]`; `wait=True` (default): hosted polls up to 36s; local polling cap defaults to 300s	Lean/full teardown, or pending progress to check again in a minute
`get_context_bundle(analysis_ids, preset)`	1–10 ids; `remix` / `synthesis` / `hooks_only`	One packaged payload across several of your analyses
`list_cuts(job_id)`	`job_id`	Cut menu: numbers, titles, durations, `brief_ready`
`get_cut(job_id, cut)`	cut number or `technique_id`	One cut: `clip_url` (short-lived), frames, timing, on-screen text
`list_scenes(job_id, limit, offset)`	default limit 25, max 60	Scene timeline, paged
`list_assets(job_id, limit, offset)`	pages byte-capped	Media assets with short-lived URLs
`get_sound(job_id)`	`job_id`	Sound & Music package (`sound-v1`, byte-capped)
`get_cast(job_id)`	`job_id`	Cast & World package (`cast-v1`, byte-capped)
`list_folders(query)`	`query` optional	Your saved Library folders
`find_folder(name)`	`name`	Find one saved folder by name, even half-remembered
`get_folder(id_or_name, limit, offset)`	`id_or_name`; paging optional	A folder’s saved items, each with a directly fetchable link
`list_canvases(query)`	`query` optional	Your Canvas boards — lean rows, never the layout
`get_canvas(id_or_name)`	id or name	One board’s cards + lean assets with fetchable links
`get_canvas_kb(canvas, bucket_id, kinds, limit, cursor)`	board id or name; rest optional	The notes and references on one board, grouped and paged
`get_canvas_bucket(canvas, bucket_id, recursive, kinds, limit, cursor)`	board + `bucket_id`	One folder on a board and the cards inside it
`get_canvas_node(canvas, node_id)`	board + `node_id`	One card or note on a board, in full
`search_canvas_kb(canvas, query, bucket_id, kinds, limit, cursor)`	board + `query`	Keyword search inside one board
`list_canvas_versions(canvas)`	board id or name	The latest 20 saved versions, newest first, with `current_revision`

Spends credits, or builds cuts (3)

Tool	Cost	What comes back
`analyze_video(url, label)`	SPENDS CREDITS — plan minutes/credits, same as a teardown in the app	A `job_id` immediately; ready in ~90s
`get_cut_brief(job_id, cut)`	Spends credits for a new brief (the response states the amount); 0 re-open / free_taste	Cut Blueprint build-spec for one cut
`build_cuts(job_id)`	0 CREDITS FROM YOUR BALANCE (Pro+; included plan compute)	Starts cut grid build; poll `list_cuts`

analyze_video accepts a YouTube, TikTok, Instagram, Vimeo, X, Google Drive, or direct MP4 URL; optional label names the teardown in your Library.

Canvas boards — edit, 0 credits (10)

Ten tools write to YOUR Canvas boards (the visual storyboards in the app’s Library) or save a reference into your Library. Like the board reads above, they charge nothing and writes stay in your own account — your own boards and your own Library; explicit full grants permit guarded native-card edits; team visibility alone never grants writes. Writes ride the mcp:canvas permission. Full grantees may edit existing visible section titles and bounds, delete visible section frames, and edit permitted native cards. Creating sections, changing a section slug, and caller-chosen card ids are owner-only. add_cards is owner-only; full grantees create permitted native cards with edit_cards, omitting card.id. To connect new cards, first create them, then use the returned created_ids in a second edit_cards call with the returned revision and a new idempotency_key. Both calls require the explicit board and owner ids. Refusals do not reveal hidden targets: 404 not_found covers section creation attempts through set_canvas_section and hidden/missing targets in section/card mutations. For visible sections, a slug change returns 403 forbidden regardless of the proposed slug’s existence. Creating any card with an explicit id, creating a section through edit_cards, or supplying a slug field there returns 403 forbidden without checking whether the proposed identity exists. Owners retain same-batch explicit ids and section create/rename behavior.

Tool	Arguments	What comes back
`create_canvas(name, team_visible)`	`name`; `team_visible` optional	The new empty board (id, name)
`add_cards(canvas, cards, expected_revision, idempotency_key)`	Your board id or name; 1–100 cards `{type, x, y, text?, asset_id?}`; supply the current revision and an idempotency key for safe retries	The created cards with server ids
`edit_cards(canvas, operations)`	1–100 ops: `create` / `update(id, changes)` / `delete(id)`	Updated card count
`update_canvas(canvas, expected_revision, layout, …)`	board + its current revision + the full layout	A new saved version; history is kept
`restore_canvas(canvas, revision, expected_revision)`	board + the version to restore	That version, saved as a new current version
`create_folder(canvas, name, x, y, collapsed)`	board + `name`	A new folder on the board
`set_folder(canvas, folder_id, collapsed, name, cover_asset_id)`	board + `folder_id`	The folder, renamed, re-covered, opened, or closed
`add_analysis_to_folder(canvas, folder_id, analysis_id, kinds)`	board + folder + one of your analyses	That analysis’s cut, frame, look, and sound assets placed in the folder
`add_asset_from_url(url, name, folder_id)`	a public image, video, or audio URL	A new asset in your private Library, ready for `add_cards`
`delete_canvas(canvas)`	board id or name	Confirmation — the board moves to Recently Deleted, restorable in the app

Boards hold up to 500 objects; asset cards reference items already saved in your Library (get_folder ids). One practical rule: close the board in the app while your assistant edits it — the app saves whole-board snapshots, and a browser tab left open can overwrite fresh agent work when it next saves. Spend tools report the outcome in the payload. get_cut_brief returns charged and plain-language credit_status so the assistant does not guess.

Canvas views, templates, access and recovery

Availability depends on current permissions and enabled features. Private uploads and sharing have independent checks. Permanent deletion requires explicit confirmation. Full grantees cannot manage boards, change access or spend. Upload limits. Private uploads count toward the account’s footage storage: 50 GB on Pro, 250 GB on Power, 500 GB on Studio and 5 GB during a trial (decimal units, so 1 GB is 1,000 MB). Each video can be up to 2 GB and 30 minutes (500 MB and 10 minutes during a trial), and each image or audio file up to 50 MB. Uploaded files are stored, not analyzed. Footage storage is separate from analysis, so uploads never use analysis minutes.

Tool	Outcome
`add_canvas_comment`	Add a comment with current board permission
`apply_canvas_label_preset`	Apply a preset to selected cards in one change
`apply_canvas_template`	Append a template to a board while keeping its existing cards
`cancel_library_upload`	Cancel a reserved upload
`canvas_view_link`	Prepare a precise board view, selection or comparison without changing the board
`create_canvas_share_link`	Create a board viewing link when sharing is available
`delete_canvas_label_preset`	Remove one of your label presets
`delete_canvas_permanently`	Permanently remove one deleted board after confirmation
`duplicate_canvas_cards`	Duplicate selected cards and preserve their internal references
`edit_canvas_layers`	Group, order, hide or favourite selected layers
`export_canvas(board_id, folder_id, job_id)`	Start a background export of your board or folder; pass the returned job id to check progress and get the download. Uses the same limits and reuse as the app; no credits spent
`finish_library_upload`	Validate and finish a reserved private upload
`get_canvas_draft`	Read your explicitly published recovery copy
`get_canvas_link`	Read the permitted view of a shared board link
`get_canvas_preferences`	Read your personal Canvas preferences
`grant_canvas_access`	Grant access to your board when available and explicitly authorized
`group_canvas_cards`	Group selected cards into a folder in one change
`library_upload_proxy`	Prepare an authenticated private file upload
`list_canvas_access`	Review access to your board when sharing is authorized
`list_canvas_label_presets`	Read your saved label presets
`list_canvas_sections`	List the named sections on a board
`list_canvas_templates`	Browse reusable layouts and sections
`list_deleted_canvases`	Browse your recently deleted boards
`move_canvas_cards`	Move cards into or out of a board folder
`order_canvas_folder`	Set the card order inside a board folder
`prepare_library_upload`	Reserve a private file upload when uploads are available
`publish_canvas_draft`	Publish an opted-in private recovery copy
`purge_deleted_canvases`	Permanently remove explicitly selected deleted boards after confirmation
`reset_canvas_preferences`	Reset selected personal Canvas preferences
`resolve_canvas_draft`	Resolve your published draft with a chosen policy
`restore_deleted_canvas`	Restore a board from Recently Deleted
`revert_canvas_change`	Revert a recorded change when its revision still matches
`revoke_canvas_access`	Revoke a person’s access to your board
`revoke_canvas_share_link`	Revoke a board viewing link
`save_analysis_reference`	Save an authorized analysis or extracted reference to your Library
`save_canvas_card`	Reuse an existing saved reference in your Library
`save_canvas_label_preset`	Save a named label preset
`save_canvas_template`	Save a board or selection as a reusable template
`set_canvas_preferences`	Update your personal preferences against their current version
`set_canvas_section`	Owners create sections and change link slugs; full-access collaborators edit existing titles and bounds
`delete_canvas_section`	Remove a section frame and keep its cards
`set_canvas_settings`	Rename your board or update its drawing defaults
`update_canvas_kb_node`	Update a card’s reference note or folder membership
`update_canvas_template`	Update a template’s name, description or category

Cut identity

Cuts are addressable two ways, and both work anywhere a cut is accepted:

cut_number - a stable 1-based number that matches the order of the grid in The Cuts tab. Cut 3 is cut 3.
technique_id - the stored id for that cut, such as cut-003. Use it when you want a reference that survives being written down.

Pass either as cut. A reference that does not resolve comes back with the valid set, so your assistant can correct itself without another round trip. Cuts have to exist before they can be read. If the analysis has not had its cuts built yet, the cut tools return cuts_built: false and name the recovery: call build_cuts(job_id) — 0 credits from your balance, plan-gated (Pro+), the build runs on compute included in the paid plan — then poll list_cuts(job_id) until cuts_built:true, usually 1–2 minutes. See The Cuts.

Money and safety

Reads are free. Discovery, status, report, cut browse, scenes, assets, sound, cast, bundle, folder, and board-read tools never charge.
Two tools spend, and only on an explicit call: analyze_video (SPENDS CREDITS) and get_cut_brief (spends credits new / 0 re-open).
build_cuts charges 0 credits from your balance. Included plan compute on paid plans (Pro+); free plans get the upgrade answer. Repeated failures trip a per-job circuit breaker.
Re-opening a brief is free. Server dedupe is on analysis + cut + engine version.
Ownership is checked server-side, per id. An analysis that is not yours comes back as a redacted preview with analyze-it-yourself — never auto-analyzed.
Writes are opt-in and bounded. Only the mcp:canvas tools write, writes stay in your own account (your own boards, plus new Library assets from add_asset_from_url), and only when called by name; delete_canvas moves a board to Recently Deleted (restorable in the app). Analyses, folders, and saved assets are never edited or deleted by any tool.
The connector talks to videngineer only. Your key is sent as a bearer token to videngineer.com and nowhere else.

The hosted connection

Live in Claude (claude.ai and the desktop app) and Claude Code. Add https://mcp.videngineer.com/mcp as a custom connector and sign in from your own account — no key or config. See Connect the hosted connector above. ChatGPT, Cursor, OpenClaw and Hermes are coming soon. The hosted surface exposes the same eighty-three tools, applies the same ownership rules, and scopes permissions (mcp:read, mcp:analyze, mcp:cut_brief, mcp:build_cuts, mcp:canvas) so a read-only grant is a real option.

Troubleshooting

Problem	Try this
The tools do not appear	Fully quit the client and reopen it. A reload or a new window is not enough; the config is read at startup
`VIDENGINEER_API_KEY is not set`	The key is missing from the `env` block, or the client is reading a different config file than the one you edited
The API access card offers no Create key button	Your plan does not include API access. See Plans & credits
Every call is unauthorized	The key was regenerated, revoked, or suspended by a plan change. Create or reveal the current key in Account → API access and update the config
A tool exists but a new one is missing	Your connector file is stale. Re-download `videngineer_mcp.py` and restart the client
An analysis you know you own reads as `owned: false`	The key belongs to a different videngineer account than the one holding that analysis
The cut tools say `cuts_built: false`	Open that analysis in videngineer and build Cuts, then try again
A cut number is rejected	The response carries `valid_cut_numbers` and `valid_technique_ids` for that analysis. Use one of those
`get_report` returns “Still processing” (hosted) or “Not finished yet” (local)	The analysis is still running. Hosted calls return successful progress in under a minute; ask again in a minute. `get_status` and hosted `wait=False` make one read bounded to 8s. Local `wait=True` keeps its configured polling cap (300s by default)
Absolute path errors on launch	`args` needs the full absolute path to `videngineer_mcp.py`, not a relative one

Still stuck: hi@videngineer.com with the subject “MCP connector”.

Connector recipes

Real asks, the tools they trigger, and the shape of what comes back.

For your AI

The copy-paste handoff, for when you are not running the connector.

The Cuts

What a cut is, how cuts are detected, and what Cut Blueprint contains.

Plans & credits

What each plan includes and which actions use credits.

Getting Started

Running Teardowns

The Analysis, Layer by Layer

Cast, Assets & Extractor

Your Library

Recipe & Workflow

Extension & Agents

Billing, Account & Legal

What it is, and what it is not

Before you start

Connect the hosted connector

Install locally with an API key

The eighty-three tools

Read-only, 0 credits (35)

Spends credits, or builds cuts (3)

Canvas boards — edit, 0 credits (10)

Canvas views, templates, access and recovery

Cut identity

Money and safety

The hosted connection

Troubleshooting

Connector recipes

For your AI

The Cuts

Plans & credits

​What it is, and what it is not

​Before you start

​Connect the hosted connector

​Install locally with an API key

​The eighty-three tools

​Read-only, 0 credits (35)

​Spends credits, or builds cuts (3)

​Canvas boards — edit, 0 credits (10)

​Canvas views, templates, access and recovery

​Cut identity

​Money and safety

​The hosted connection

​Troubleshooting

​Related pages

Connector recipes

For your AI

The Cuts

Plans & credits

What it is, and what it is not

Before you start

Connect the hosted connector

Install locally with an API key

The eighty-three tools

Read-only, 0 credits (35)

Spends credits, or builds cuts (3)

Canvas boards — edit, 0 credits (10)

Canvas views, templates, access and recovery

Cut identity

Money and safety

The hosted connection

Troubleshooting

Related pages