Agent mode (Claude / Cursor / MCP)

Agent mode

Varosity ships an MCP server at https://varosity.ai/api/mcp. Any MCP host (Claude Desktop, Cursor, custom clients via the official SDK) can drive every important capability without a browser.

Quick setup

No key yet? Hosts that sign in with OAuth need none. In Claude Code:

claude mcp add --transport http varosity https://varosity.ai/api/mcp

then run /mcp, pick varosity and choose Authenticate. You sign in once in the browser and the host gets a token with a $5 daily cap (29 tools; an API key gets all 46).

Cursor and Windsurf: add the server with no headers and the host offers to sign you in:

{ "mcpServers": { "varosity": { "url": "https://varosity.ai/api/mcp" } } }

Gemini CLI: put { "mcpServers": { "varosity": { "httpUrl": "https://varosity.ai/api/mcp" } } } in ~/.gemini/settings.json, then run /mcp auth varosity.

For a key instead:

1. Get a key in one click at /agent/key (or issue one with chosen scopes at /app/keys/api-keys, labelled for the host). 2. Add the server to your host. Hosts that take a remote server (Claude Code, Cursor, Windsurf) use the URL and a header:

{
  "mcpServers": {
    "varosity": {
      "type": "http",
      "url": "https://varosity.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer vsk_<paste-here>"
      }
    }
  }
}

Claude Desktop runs local servers from its config file, so use the npm package there:

{
  "mcpServers": {
    "varosity": {
      "command": "npx",
      "args": ["-y", "@varosity/mcp-server"],
      "env": {
        "VAROSITY_API_KEY": "vsk_<paste-here>"
      }
    }
  }
}

The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). Or skip the file: in Claude Desktop or Claude.ai, go to Customize → Connectors, add https://varosity.ai/api/mcp and sign in (see OAuth below).

3. Restart the host. 4. The agent now has access to the Varosity tool surface.

Copy-paste setup for each host (Claude Code, Cursor, Gemini CLI, and more) lives at varosity.ai/connect.

Sign in instead of pasting a key (OAuth)

Hosts that connect with a sign-in — Claude.ai connectors, ChatGPT apps and similar — can use OAuth 2.1 instead of an API key. Add https://varosity.ai/api/mcp as a custom connector (remote MCP server); the host opens a Varosity page where you sign in and approve.

• The consent screen shows which app is asking, where you'll be sent back,
• and exactly what it can do.
• Each connected app gets its own daily spend cap (default $5), which you can
• change or disconnect under API Keys.
• A connected app can generate media and read/write your projects. It can't
• see your password, payment details or provider keys.

API keys keep working exactly as before — use whichever your agent supports. Per-agent setup: varosity.ai/connect.

Tools exposed

The MCP surface is curated, not a wrapper around the entire API — 46 tools. Call tools/list for the live set with full input schemas; the ones you'll reach for most:

Skills for multi-shot production

Varosity publishes agent playbooks ("skills") as plain markdown. Call the refresh_skills tool to pull them, or fetch one directly from https://varosity.ai/api/v1/skills/<slug> — for example varosity-video-orchestration or custom-video-generation. Browse the library at varosity.ai/skills.

For multi-shot work (music videos, product reels, brand campaigns), follow the two-phase workflow — lock one reference image, then generate every shot against it — in Multi-shot consistency with locked references.

Other agent-readable surfaces

• llms.txt — site overview
• llms-full.txt — registry + guides + skills
• agents.json — capability manifest
• openapi.json — full REST spec

A typical agent flow

User: "Make a 15-second product reel for our new espresso machine. 3 shots."

1. Agent calls suggest_model for the establishing wide → ranks Kling 3.0. 2. Agent calls create_project({title: "espresso reel"}) → projectId. 3. Agent calls generate_video 3 times across Kling/Veo/Seedance, passing project_id + shot_index so every shot lands in that one project; each call returns a jobId. 4. Polls get_job until each reports status: "succeeded". 5. Optional: generate_music for backing track, generate_voice for VO. 6. render_project for the final stitch. 7. Returns the MP4 URL to the user.

All of that, no browser.

Limits + safeguards

• Bearer tokens act as you, within the scopes you granted. Treat them
• like passwords. Revoke at /app/keys/api-keys.
• Every tool filters by your account — an agent with your token only
• sees and changes your data, never another user's.
• Rate limits. API keys are rate limited per minute; an over-limit
• REST call returns 429 with code: "rate_limited" and a Retry-After
• header — wait that long and retry.
• Daily spend cap. Each API key has its own daily spend cap, set per
• key at /app/keys/api-keys; the day resets at 00:00 UTC. Each call
• reserves its estimated cost. Media-driven models (OmniHuman, lip-sync,
• LivePortrait, Wan Animate, HeyGen, D-ID) bill the real length of the
• supplied audio or video, and so do transcription, dubbing and the voice
• changer; on Varosity Credits that real charge is added
• when the job finishes, so the next call can be refused. Pay-per-call
• (POST /api/v1/pay/generate) is paid request by request and doesn't count
• toward the cap. Over the cap, MCP tools fail
• saying the daily cap is exceeded (a result with isError: true for current
• MCP hosts, a JSON-RPC error for plain JSON-RPC callers), and REST calls
• return 429 with code: "daily_cap_exceeded" (video, voice and music
• responses also carry spent_today_cents and daily_cap_cents) and no
• Retry-After. This is not retryable: it keeps failing until the
• reset or until you raise the cap. If the cap can't be checked, REST calls
• return 503 with code: "spend_guard_error".
• Held renders. On Varosity Credits, a render that finishes when the
• balance can't cover it is held: get_job keeps reporting it as running
• with code: "insufficient_credits" and an error message. Top up at
• /app/credits and poll again to release it (kept for 24 hours).