The connector

Connector status: LIVE on every paid plan. The fastest path is the one-click hosted connection — press Connect to Claude on the connector page, authorize on your own account, done (no key, no config). 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 twenty-one tools for the analyses 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	Generate video, images, or audio
Hand one cut to your assistant at a time, so it reasons over a shot instead of a whole report	Edit, rename, move, or delete anything in your Library
Start a new analysis when you explicitly ask for one	Run anything on its own or on a schedule
Bundle up to ten of your analyses into one payload for your own generation tool	Reach any account but yours

The connector supplies context. The making happens in your tools: your editor, your image and video models, your 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.
A paid plan. API keys and the connector are included on every paid plan; the free plan shows a plan upsell on the API access card instead of a Create key button. 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 in one click (hosted)

The fastest path — no key, no file, no terminal.

Press Connect to Claude

On the connector page, press Connect to Claude. It deep-links into Claude’s Add custom connector modal with videngineer prefilled. (To add it by hand: Claude → Settings → Connectors → Add custom connector, name it videngineer, endpoint https://mcp.videngineer.com/mcp.)

Authorize on your own account

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

The twenty-one tools appear

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

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 twenty-one tools are wired, you get your library back, newest first.

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).

The twenty-one tools

Most tools only read. Two spend wallet credits or plan minutes. One builds the cut grid at 0 credits from your balance. The split is enforced server-side, not by prompt. Full signatures, param tables, and measured response excerpts: Connector API.

Read-only, always free

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`	`queued`, `running`, `complete`, or `error`, plus progress
`get_report(job_id, preset, fields, wait)`	`preset="lean"` (default) or `"full"`; or `fields=[...]`; `wait=True` (default) polls until done	Lean or full teardown read
`get_context_bundle(analysis_ids, preset)`	1–10 ids; `remix` / `synthesis` / `hooks_only`	Packaged payload for an external generation tool
`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

Spends or privileged plan actions

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)`	2 credits new; 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. Spend tools report the outcome in the payload. get_cut_brief returns charged and plain-language credit_status so the assistant does not guess.

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, and bundle tools never charge.
Two tools spend, and only on an explicit call: analyze_video (SPENDS CREDITS) and get_cut_brief (2 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.
Nothing is destructive. No tool edits, renames, moves, or deletes Library content.
The connector talks to videngineer only. Your key is sent as a bearer token to videngineer.com and nowhere else.

The hosted connection

Live on every paid plan. The one-click hosted connection (press Connect to Claude, authorize from your own account, no key or config) is switched on. See Connect in one click above, or add the endpoint https://mcp.videngineer.com/mcp as a custom connector by hand. The hosted surface exposes the same twenty-one tools, applies the same ownership rules, and scopes permissions (mcp:read, mcp:analyze, mcp:cut_brief, mcp:build_cuts) 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. It comes with every paid plan; 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 “Not finished yet”	The analysis is still running. Call it again, or leave `wait=True` and let it poll
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 in one click (hosted)

Install locally with an API key

The twenty-one tools

Read-only, always free

Spends or privileged plan actions

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 in one click (hosted)

​Install locally with an API key

​The twenty-one tools

​Read-only, always free

​Spends or privileged plan actions

​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 in one click (hosted)

Install locally with an API key

The twenty-one tools

Read-only, always free

Spends or privileged plan actions

Cut identity

Money and safety

The hosted connection

Troubleshooting

Related pages