Docs

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.

View as Markdown

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.

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.