Drive Cadre from your agent
Cadre exposes its editor as a local MCP server. An AI agent — Claude Code first, or any MCP-capable client — opens a project, inspects the timeline, adds cinematic zooms, cuts, captions, sets style and exports. You describe the result; the agent makes the precise edits.
Overview
Cadre's editor is fully data-driven — a project is a manifest plus timeline data,
and the app already speaks a typed command protocol internally. The Agent API wraps
that surface in a Model Context Protocol (MCP) server that runs inside
the app, bound to 127.0.0.1 on an ephemeral port.
Recording stays human-initiated by design: you record, the agent edits. Everything after the take — inspecting the timeline, zooming, cutting, captioning, styling and exporting — is available as tools your agent can call.
Connect an agent
When Cadre is running it writes a connection file to your app-support directory with the current port and a fresh bearer token:
{
"port": 51837,
"token": "a7Q2…base64url…",
"version": "1.0",
"pid": 4821
}
The file is written on boot with chmod 600 and removed on quit, so a stale token never lingers. Point Claude Code at it with one command:
$ claude mcp add --transport http cadre \ "http://127.0.0.1:$PORT/mcp" \ --header "Authorization: Bearer $TOKEN"
Or commit a project-local .mcp.json that reads the same values:
{
"mcpServers": {
"cadre": {
"transport": "http",
"url": "http://127.0.0.1:<port>/mcp",
"headers": { "Authorization": "Bearer <token>" }
}
}
}
Once connected, ask in natural language — the agent selects the tools below and reports back what it changed.
Auth & security
- Localhost only. The server binds to
127.0.0.1on an ephemeral port — never a public interface. - Bearer token on every request. A fresh 32-byte token is minted each boot; the compare is constant-time, so neither length nor content leaks through timing.
- No recording control. The API edits and exports; it cannot start a capture of your screen.
- The paywall still applies. Export is licence-gated server-side — an agent hits the same
LICENSE_REQUIREDgate the UI does, and cannot bypass it.
Tool reference (v1)
The v1 server exposes these tools. Every call validates its arguments and returns the post-mutation entity, so an agent can verify the effect of each edit.
| Tool | What it does |
|---|---|
| get_app_state | Current app + license status and whether a project is open. |
| list_projects | List indexed projects available to open. |
| open_project | Load a project and navigate the app to the editor. |
| get_timeline | Snapshot the timeline: durations, zooms, cuts, speeds, captions. |
| add_zoom / update_zoom / delete_zoom | Manage cinematic zoom keyframes with spring easing. |
| add_cut / update_cut / delete_cut | Ripple-delete or adjust cut regions to remove dead air. |
| set_speed | Set a speed segment (with ramp in/out) over a time range. |
| list_captions / add_caption / update_caption / delete_caption | Read and edit individual caption segments. |
| generate_captions | Transcribe the voiceover on-device with Whisper. |
| set_style | Update background, frame, cursor, keyboard, motion or webcam style. |
| set_music | Attach or update a background music track. |
| set_audio_gains | Balance system, mic and music levels. |
| undo / redo | Step the editor history backward or forward. |
| save_project | Persist the current edit state to disk. |
| export_video | Render the project to MP4 (licence-gated). |
| get_export_status | Poll progress of an in-flight export. |
| cancel_export | Cancel a running export. |
| get_license_status | Check subscription state before exporting. |
Example prompts
You talk to your agent the way you'd talk to an editor. A few that map cleanly onto the tools above:
Tighten this demo.
The agent calls get_timeline, finds silent gaps and slow stretches, then add_cut to ripple-delete dead air and set_speed to ramp through the slow parts — turning a rambling take into a tight one.
Zoom on the terminal whenever I type.
It reads typing activity from the timeline and places add_zoom keyframes over those moments, letting Cadre's spring physics push in and ease back out around each burst of input.
Caption it and export for X.
The agent runs generate_captions on-device, applies a caption style with set_style, then export_video and polls get_export_status until the MP4 is ready.
Errors
Failures come back as a structured { code, message, hint } object, so an agent can branch on the code rather than parse prose.
| Code | Meaning |
|---|---|
| EDITOR_NOT_AVAILABLE | No editor window is open to receive edit commands. |
| NO_PROJECT_OPEN | A project must be opened before editing. |
| LICENSE_REQUIRED | Export needs an active subscription — the paywall, applied to agents too. |
| EXPORT_IN_PROGRESS | An export is already running; cancel or wait. |
| INVALID_ARGS | Tool arguments failed validation. |
| NOT_FOUND | The referenced project or timeline item does not exist. |
| INTERNAL | An unexpected error inside the app. |