Tools & SDKs

MCP server

The Vivideo MCP server plugs video generation into AI assistants (Claude Desktop, Cursor, and any MCP client) as tools the assistant can call for you. MCP is the open standard for connecting AI apps to external tools.

Remote server — no install

The fastest way to connect: point your client at the hosted server. Nothing to install, always the latest version, and your key stays in the client's config.

mcp config (remote)

{
  "mcpServers": {
    "vivideo": {
      "url": "https://api.vivideo.ai/mcp",
      "headers": { "Authorization": "Bearer vv_live_..." }
    }
  }
}

Claude Code

claude mcp add --transport http vivideo https://api.vivideo.ai/mcp \
  --header "Authorization: Bearer vv_live_..."

The remote server is stateless Streamable HTTP, exposes the same 13 tools as the npm package below, and forwards your key to the same public API — identical behavior, different transport. One transport-specific difference: wait_for_video waits up to ~20 seconds per call (HTTP requests are time-capped) and returns timed_out: true — agents simply call it again.

Local server (npx)

Prefer running it yourself (offline config review, pinned versions, CI)? Add this to your client's MCP config, with your API key in the env block:

mcp config (local)

{
  "mcpServers": {
    "vivideo": {
      "command": "npx",
      "args": ["-y", "@vivideo/mcp"],
      "env": { "VIVIDEO_API_KEY": "vv_live_..." }
    }
  }
}

Claude Desktop / Claude Code: add it to the MCP servers config. Cursor: the same shape in ~/.cursor/mcp.json (or a project .cursor/mcp.json). Any MCP client: run the command over stdio.

Keep your key in the client's env config — never in a tool argument, chat, or code. The server never asks for, logs, or returns your key. Get a key at app.vivideo.ai/account/api-keys.

Run it directly (optional)

terminal

export VIVIDEO_API_KEY="vv_live_..."
npx -y @vivideo/mcp        # starts the stdio server

It starts even without a key — the check_configuration tool reports that so an agent can tell you what to set.

Tools

All tools return structured JSON. Errors come back as structured objects with the API's code, retryable flag and next-step links — agents branch on those, never on prose.

Tool	Purpose
`check_configuration`	Is a key configured? Call first.
`check_account`	Plan, premium, credits, upgrade/buy links.
`list_models`	Manual models + the auto pipeline, with options & rates.
`list_avatars / list_voices / list_brand_kits`	Discover media for auto mode.
`estimate_credits`	Pre-flight cost estimate.
`create_auto_video`	Auto mode: full avatar video from a prompt.
`create_manual_video`	Manual mode: a specific model.
`get_video`	One video’s status/result.
`wait_for_video`	Bounded, safe wait to a terminal state.
`list_videos`	The account’s videos.
`render_preview`	Free accounts: render a preview after upgrading.

✓

Safe for agents. Creation returns immediately with a video id; wait_for_video is bounded and hands control back on timeout instead of blocking. The client rate-limits, retries only retryable errors, honors Retry-After, and sends idempotency keys — so an agent in a loop can't flood the API.

Pair the MCP server with the Agent Skills so the assistant uses these tools correctly.

← Previous

CLI

Agent Skills

Machine-readable: interactive reference · openapi.yaml · llms-api.txt. Base URL https://api.vivideo.ai.