> ## Documentation Index
> Fetch the complete documentation index at: https://docs.videngineer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# The connector
> Give your agent read access to your own teardowns over MCP: twenty-one tools. Live on every paid plan — one-click hosted connect or a local API key.
**Connector status: LIVE on every paid plan.** The fastest path is the **one-click hosted connection** — press *Connect to Claude* on the [connector page](https://videngineer.com/mcp), 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](/agents/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](https://modelcontextprotocol.io) 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](/for-your-agent), 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](/billing/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.
On the [connector page](https://videngineer.com/mcp), 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`.)
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 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.
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.
One file plus its runtime.
```bash theme={null}
pip install "mcp[cli]"
curl -O https://videngineer.com/mcp/videngineer_mcp.py
```
Point your client at the file you just downloaded and put your key in `env`.
Edit `claude_desktop_config.json`, then fully quit and reopen the app.
```json theme={null}
{
"mcpServers": {
"videngineer": {
"command": "python",
"args": ["/absolute/path/to/videngineer_mcp.py"],
"env": { "VIDENGINEER_API_KEY": "" }
}
}
}
```
Add the same block to `.mcp.json` in your project root, then restart Claude Code.
```json theme={null}
{
"mcpServers": {
"videngineer": {
"command": "python",
"args": ["/absolute/path/to/videngineer_mcp.py"],
"env": { "VIDENGINEER_API_KEY": "" }
}
}
}
```
A ready-to-edit copy of that block is downloadable at [claude\_desktop\_config.example.json](https://videngineer.com/mcp/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](/agents/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](/agents/api-discovery#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](/layers/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](#connect-in-one-click-hosted) 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](/billing/plans-credits-topups) |
| 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](mailto:hi@videngineer.com) with the subject "MCP connector".
## Related pages
Real asks, the tools they trigger, and the shape of what comes back.
The copy-paste handoff, for when you are not running the connector.
What a cut is, how cuts are detected, and what Cut Blueprint contains.
What each plan includes and which actions use credits.