Connector API

Connector status: LIVE on every paid plan. Connect two ways: one-click hosted (press Connect to Claude on the connector page, authorize on your own account — no key, no config) or API-key bearer (local stdio connector). Both surfaces expose the same twenty-one tools.

The connector API answers: what can my agent call, what does each call cost, and what shape comes back? This is the public contract for the twenty-one tools registered in mcp/videngineer_mcp.py (TOOL_SPECS on origin/main). Where an older draft and the code disagree, the code wins. | Setup | The connector | | Recipes | Connector recipes |

Tool map (19)

Group	Tools
Analyses	`list_analyses`, `find_analyses`, `analyze_video`, `get_status`, `get_report`, `get_context_bundle`
Cuts	`list_cuts`, `get_cut`, `get_cut_brief`, `build_cuts`, `find_cuts`, `list_scenes`
Discovery	`find_teardowns`, `find_analyses` with `intent` (recommend mode)
Media	`get_sound`, `get_cast`, `list_assets`
Library folders	`list_folders`, `find_folder`, `get_folder` — your saved Library folders and their items (free reads)

Auth surfaces

Both surfaces register the same twenty-one tool bodies. Auth is the only difference.

 Your agent (hosted client)          Your agent (local MCP client)
            │                                   │
     OAuth login to you                   API key in env
            │                                   │
            ▼                                   ▼
   hosted MCP service                  videngineer_mcp.py (local file)
            │                                   │
            └────────────────┬──────────────────┘
                             ▼
                  videngineer.com REST API
              ownership · credits · plan gates

API-key bearer (live today)

Create a key in Account → API access. Put it in VIDENGINEER_API_KEY.
Plan entitlements (API access, minutes, credits) apply exactly as in the app.
Local keys carry no OAuth scopes. Plan gates are the only gate.
Optional env: VIDENGINEER_BASE_URL (default https://videngineer.com), VIDENGINEER_WAIT_CAP (seconds get_report polls; default 300).

Hosted OAuth (live)

Live on every paid plan. Press Connect to Claude on the connector page, or add the endpoint https://mcp.videngineer.com/mcp as a custom connector, then authorize on your own account — no key, no config file.
Scopes: mcp:read, mcp:analyze, mcp:cut_brief, mcp:build_cuts. A read-only grant is a real option.
Missing scope returns a clean refusal with the scopes already granted.

The connector is included on plans that include API access. There is no separate agent meter and no extra connector fee. Spend tools draw on the same plan minutes and credits as the app.

Charges (quote from tool surfaces)

Tool	Charges
All read tools (discovery, status, report, scenes, assets, cuts browse, sound, cast, bundle, Library folders)	read-only, 0 credits
`analyze_video`	SPENDS CREDITS — plan minutes/credits, same as a teardown in the app
`get_cut_brief`	2 credits for a new brief; 0 on re-open (dedupe on analysis + cut + engine version) or when `free_taste` applies. Response reports `charged` / `credit_status`.
`build_cuts`	0 CREDITS FROM YOUR BALANCE — paid plans only (Pro+); included plan compute

Reads never charge. Spend tools only charge on an explicit call. Nothing is destructive — there is no tool that edits, renames, moves, or deletes Library content.

Known empty surfaces (honest)

find_cuts returns empty until its cut-index backfill runs (Mark-gated).
find_analyses with intent (recommend mode) returns an empty recommendation envelope until the labeler / reference_index backfill runs (Mark-gated). Keyword filters still work.

Efficient sequences

Remake one cut (your library):

find_analyses  →  list_cuts (once)  →  get_cut  →  get_cut_brief

Cold start (no library yet):

find_teardowns(goal, quality)  →  analyze_video(teardowns[i].analyze.source_url)

Sound or cast only: call get_sound / get_cast, not get_report(fields=[...]). Media URLs stay on list_assets.

Ownership

Every analysis id is ownership-checked server-side. An id you do not own comes back as a redacted preview (title, thumbnail, hook type, duration) with an analyze-it-yourself option and the credit cost stated — never auto-analyzed for you.

Byte budgets (measured)

Wire = hosted MCP HTTP body; compact = structured tool JSON re-encoded compact UTF-8. From wave-2 founder E2E + L3/L4 package specs:

Call	Compact / package	Cap notes
`find_teardowns` (5 items)	~3.6 KB compact / ~5.2 KB wire	item ≤650 B, response ≤4,096 B compact
`find_analyses` (5 rows)	~1.4 KB compact / ~2.2 KB wire	keyword path
`find_analyses(intent=…)` empty	58 B compact	until backfill
`get_cut`	~2.6–3.0 KB wire	free one-cut read
`get_sound`	package ≤4,608 B (`sound-v1`)	measured worst ~4.3 KB compact
`get_cast`	package ≤6,656 B (`cast-v1`)	measured ~6.0 KB wire / ~4.4 KB compact

Prefer lean discovery over full dumps. Prefer get_sound / get_cast over field-sliced full reports.

Analyses — library list, search, analyze, status, report, bundle
Cuts — cut menu, one cut, brief, build, find, scenes
Discovery — public teardowns + recommend intent
Media — sound, cast, assets

Getting Started

Running Teardowns

The Analysis, Layer by Layer

Cast, Assets & Extractor

Your Library

Recipe & Workflow

Extension & Agents

Billing, Account & Legal

Tool map (19)

Auth surfaces

API-key bearer (live today)

Hosted OAuth (live)

Charges (quote from tool surfaces)

Known empty surfaces (honest)

Efficient sequences

Ownership

Byte budgets (measured)

Next pages

​Tool map (19)

​Auth surfaces

​API-key bearer (live today)

​Hosted OAuth (live)

​Charges (quote from tool surfaces)

​Known empty surfaces (honest)

​Efficient sequences

​Ownership

​Byte budgets (measured)

​Next pages

Tool map (19)

Auth surfaces

API-key bearer (live today)

Hosted OAuth (live)

Charges (quote from tool surfaces)

Known empty surfaces (honest)

Efficient sequences

Ownership

Byte budgets (measured)

Next pages