> ## 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. # Connector API > Nineteen MCP tools for your teardowns. Live on every paid plan — one-click hosted connect or local API key. Signatures match production TOOL_SPECS. **Connector status: LIVE on every paid plan.** Connect two ways: **one-click hosted** (press *Connect to Claude* on the [connector page](https://videngineer.com/mcp), 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](/agents/mcp-connector) | \| Recipes | [Connector recipes](/agents/mcp-worked-examples) | ## Tool map (19) | Group | Tools | | ---------------------------------- | ----------------------------------------------------------------------------------------------------- | | [Analyses](/agents/api-analyses) | `list_analyses`, `find_analyses`, `analyze_video`, `get_status`, `get_report`, `get_context_bundle` | | [Cuts](/agents/api-cuts) | `list_cuts`, `get_cut`, `get_cut_brief`, `build_cuts`, `find_cuts`, `list_scenes` | | [Discovery](/agents/api-discovery) | `find_teardowns`, `find_analyses` with `intent` (recommend mode) | | [Media](/agents/api-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. ```text theme={null} 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](https://videngineer.com/mcp), 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):** ```text theme={null} find_analyses → list_cuts (once) → get_cut → get_cut_brief ``` **Cold start (no library yet):** ```text theme={null} 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. ## Next pages 1. [Analyses](/agents/api-analyses) — library list, search, analyze, status, report, bundle 2. [Cuts](/agents/api-cuts) — cut menu, one cut, brief, build, find, scenes 3. [Discovery](/agents/api-discovery) — public teardowns + recommend intent 4. [Media](/agents/api-media) — sound, cast, assets