# Vidova MCP architecture

Localhost Streamable HTTP MCP at 127.0.0.1:17373, no HTTP auth, 1MB body, 5 minute timeout, 8000-character result windows, and grouped-tool passthrough.

## Endpoint

- Host: `127.0.0.1`
- Port: `17373` unless `VIDOVA_APP_MCP_PORT` is set
- Path: `/mcp`
- Protocol: Streamable HTTP, POST only
- Server name: `vidova-desktop`

The process binds localhost only. There is no HTTP authentication. Firebase is used only when a tool needs SFX search or image vectorize.

## Limits

- JSON body: at most 1,048,576 bytes
- Dispatch timeout: 5 minutes (300,000 ms)
- Result window: `resultStart` / `resultEnd`, at most 8000 characters per window

Sleep in the MCP server waits in-process. The renderer `sleep` tool is 1 to 60 seconds. Prefer the advertised MCP `seconds` field and keep waits short between `generate_asset` status polls.

## Grouped tools and passthrough

Several MCP tools are grouped. `listTools` advertises `action` or `kind` plus a small field set, then **passthrough**. Extra fields are not rejected at the MCP wrapper. The renderer validates the child schema for that action.

That is why `timeline_edit` `updateClip` accepts `vidovaSettings` even though the advertised schema does not list it. Authoritative child fields are on each [tool page](/docs/mcp/tools).

## Ask mode

Grouped mutating actions are rejected in Ask mode. Read actions still run. `project_history` allows `status` in Ask mode and rejects `undo` / `redo`.

## Locks

The editor serializes tool work with resource locks: timeline, components, assets, project, recipes, and an exclusive render lock for preview capture. Parallel MCP calls that write the same project wait. Do not assume two writes ran at once.

## Branch merge approval

`branch_action` `merge` and `mergeToMain` require approval. A rejected merge leaves the project unchanged.

## Editor must be open

Project tools talk to the local project store. Editor tools dispatch into the open renderer. If no editor is registered for the active project, the call fails with a message to open the project in Vidova.