Connector API

Connector status: LIVE. Connect two ways: hosted (add https://mcp.videngineer.com/mcp in a supported app and sign in on your own account — no key, no config) or API-key bearer (local stdio connector). Both surfaces register 83 base tools; each connection sees only currently authorized tools. An API-key connection currently sees 74: four upload-recovery and five share/access tools require approved OAuth claims.

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 eighty-three 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 | Owned analyses and Canvas boards include app_url when ownership is confirmed. Offer that link to open the item in videngineer; media download links are separate and short-lived. Shared boards and public study records do not receive private app links.

Tool map (83)

Group	Tools
Totals	35 read-only · 2 spend credits on request (`analyze_video`, `get_cut_brief`) · 46 build or board edits at 0 credits — 81 of 83 never spend credits
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`, `list_teardown_tags`, `get_teardown`, `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)
Canvas boards	`list_canvases`, `get_canvas`, `get_canvas_kb`, `get_canvas_bucket`, `get_canvas_node`, `search_canvas_kb`, `list_canvas_versions`, `create_canvas`, `add_cards`, `edit_cards`, `update_canvas`, `restore_canvas`, `create_folder`, `set_folder`, `add_analysis_to_folder`, `add_asset_from_url`, `delete_canvas` — your own storyboards: seven free reads, ten zero-credit writes (foreign card edits require a current full grant and explicit revision; full tables on the connector page)

| Canvas views, templates, access and recovery | add_canvas_comment, apply_canvas_label_preset, apply_canvas_template, cancel_library_upload, canvas_view_link, create_canvas_share_link, delete_canvas_label_preset, delete_canvas_permanently, delete_canvas_template, duplicate_canvas_cards, edit_canvas_layers, export_canvas, finish_library_upload, get_canvas_draft, get_canvas_link, get_canvas_preferences, grant_canvas_access, group_canvas_cards, library_upload_proxy, list_canvas_access, list_canvas_label_presets, list_canvas_sections, list_canvas_templates, list_deleted_canvases, move_canvas_cards, order_canvas_folder, prepare_library_upload, publish_canvas_draft, purge_deleted_canvases, reset_canvas_preferences, resolve_canvas_draft, restore_deleted_canvas, revert_canvas_change, revoke_canvas_access, revoke_canvas_share_link, save_analysis_reference, save_canvas_card, save_canvas_label_preset, save_canvas_template, set_canvas_preferences, set_canvas_section, delete_canvas_section, set_canvas_settings, update_canvas_kb_node, update_canvas_template | 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.

Auth surfaces

Both surfaces register the same eighty-three tool bodies. Hosted listing and direct invocation also enforce rollout claims and scopes.

 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 local get_report polls; default 300). Local context requests keep their 90-second timeout; a final request can extend beyond the polling cap.

Hosted OAuth (live)

Live in Claude (claude.ai and the desktop app: Settings → Connectors → Add custom connector) and Claude Code (claude mcp add --transport http videngineer https://mcp.videngineer.com/mcp, then /mcp to sign in). Endpoint: https://mcp.videngineer.com/mcp. Authorize on your own account — no key, no config file. ChatGPT, Cursor, OpenClaw and Hermes: coming soon.
Scopes: mcp:read, mcp:analyze, mcp:cut_brief, mcp:build_cuts, mcp:canvas. A read-only grant is a real option; board editing is its own consent line.
Missing scope returns a clean refusal with the scopes already granted.
Hosted get_report(wait=True) polls for at most 36 seconds. Including cold sign-in verification, a pending call normally returns in about 44 seconds plus small transport overhead. An operator may lower the tool budget with a positive integer VIDENGINEER_WAIT_CAP; invalid or larger values use 36 seconds.
Hosted get_status stays a single snapshot. Hosted wait=False also makes one read. Each context request is bounded to the smaller of 8 seconds or the remaining tool budget.
An owned analysis still running returns an ordinary successful result: original job_id, status, raw progress, integer or null progress_percent, and note: Still processing — about N% done. Ask again in a minute. When an estimate is unavailable, the note says so. Call again in a minute; do not start another analysis.
Progress estimates prefer a finite number, then a progress object’s percent value, a whole percentage string, or an exact done/total string with positive total. Fractions truncate to whole percentages and pending estimates stay within 0–99. Otherwise known stages use approximate estimates: waiting/queued 5, processing 10, extracting frames 20, extracting audio 35, transcribing 45, analyzing 60, blueprint preparation 80, settling 90, and index pending 95. Unknown stages with unparseable progress return null. Actual errors remain errors.

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 35 read tools (discovery, status, report, scenes, assets, cuts browse, sound, cast, bundle, Library folders, Canvas reads)	read-only, 0 credits
`analyze_video`	SPENDS CREDITS — plan minutes/credits, same as a teardown in the app
`get_cut_brief`	Spends credits for a new brief (the response reports the configured amount); 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
The 10 Canvas write tools (`create_canvas`, `add_cards`, `edit_cards`, `update_canvas`, `restore_canvas`, `create_folder`, `set_folder`, `add_analysis_to_folder`, `add_asset_from_url`, `delete_canvas`)	0 credits — writes stay in your own account

Reads never charge. Spend tools only charge on an explicit call. Writes stay in your own account: your own Canvas boards, plus new Library assets from add_asset_from_url. delete_canvas moves a board to Recently Deleted (restorable in the app). No tool edits or deletes your analyses or saved Library files.

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.

Upload limits

Private Library uploads (prepare_library_upload, library_upload_proxy, finish_library_upload) 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.

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 (83)

Auth surfaces

API-key bearer (live today)

Hosted OAuth (live)

Charges (quote from tool surfaces)

Known empty surfaces (honest)

Efficient sequences

Upload limits

Ownership

Byte budgets (measured)

Next pages

​Tool map (83)

​Auth surfaces

​API-key bearer (live today)

​Hosted OAuth (live)

​Charges (quote from tool surfaces)

​Known empty surfaces (honest)

​Efficient sequences

​Upload limits

​Ownership

​Byte budgets (measured)

​Next pages

Tool map (83)

Auth surfaces

API-key bearer (live today)

Hosted OAuth (live)

Charges (quote from tool surfaces)

Known empty surfaces (honest)

Efficient sequences

Upload limits

Ownership

Byte budgets (measured)

Next pages