Skip to main content
This page is the technical reference — mostly read by agents and engineers. You don’t need it for everyday use; your agent already knows all of this. There are two ways to drive Rivet: the rivet CLI and a resident stdio MCP server (rivet mcp serve, registered under the name rivet). Both control the same thing and return the same JSON envelope, so everything below applies to agents and humans alike.

​
MCP tools

The MCP server exposes three tools.

​
rivet_status

Read-only session state for a project: server health, active work with workIds, and per-variant progress. Fast (~10ms) — poll it after starting work; there is no blocking wait. When a response carries a nextAction, follow its instructions. While variants.starting is true, a start is still provisioning — keep polling rather than retrying. Parameters:
  • project (string, optional) — project root path; defaults to the server for the current directory
  • include (array, optional) — "history" adds past variant sets; "auth" adds signed-in state

​
rivet_variants

Drives the variant lifecycle (“directions” in the UI). Parameters:
  • action (required) — start | complete | commit | cancel
  • project (string, optional) — project root path
For action: "start":
  • instruction (string) — what to vary and how
  • runLabel (string) — 1–3 word batch summary (required unless fresh)
  • briefs (array) — one per direction; length sets the count (required unless fresh). Each brief:
    • label — 1–5 word direction title (distinct across the batch)
    • body — subtitle of at most 10 words
    • notes (optional) — richer implementation intent (design tokens, motion specs, constraints), delivered verbatim to that direction’s worker
    • visualReferenceUrl (optional)
  • count (number) — number of variants
  • element (string) — CSS selector scoping the variation
  • files (array, max 12) — known project files for workers to inspect first
  • fresh (boolean) — zero-to-one run ignoring prior context; Rivet authors the directions server-side, so briefs/runLabel may be omitted
  • fidelity — low (fast sketch-grade) | medium (balanced default) | high (frontier-model authorship, up to a few minutes)
  • contextImages (array, 1–6) — local reference image paths (png/jpg/webp/gif/avif)
  • referencePages (array, 1–3, fresh only) — reference page URLs, rendered server-side
  • referenceVideos (array, 1–2, fresh only) — local video paths, sampled into keyframes server-side
  • target (string) — sessionId:variantId to refine an existing variant in place
For action: "complete" (host-executed work items): workId, status (succeeded | failed | cancelled), plus optional output, error, title, description, sessionId. For action: "commit": variantId, optional sessionId. For action: "cancel": sessionId (required).
Rivet normally implements directions with its own server-side workers — agents watch rivet_status until work is terminal. Only when a response carries nextAction.action: "complete_host_variant_work" does the host agent implement items itself, following the packet instructions exactly.

​
rivet_design_context

Gathers design context from a URL. Routing is automatic: Pinterest (pinterest.com / pin.it) and Are.na URLs return the connected account’s reference data (boards, pins, blocks); any other URL is rendered live and captured as visual evidence (screenshot plus rendered-page metadata). Slow — network/render bound. Parameters:
  • url (string, required)
  • screenshot (boolean, optional) — capture a screenshot (render path only)
  • width, height (numbers, optional) — viewport (render path only)
  • project (string, optional)

​
CLI commands

Useful flags on the interactive rivet command: --user-port (your dev server’s port, default 3000), --rivet-port (Rivet’s port, default 4000), --framework (override detection), --no-git, --no-browser, --debug, --no-telemetry.

​
JSON envelope & exit codes

Every control-plane subcommand prints exactly one JSON envelope on stdout and routes human-readable progress to stderr:
MCP tool results carry the same envelope verbatim, with ok: false mapped to an MCP error result.

​
Supported frameworks

Rivet auto-detects the framework and dev-server port when it opens a project, and you can override with --framework:
  • Next.js (nextjs)
  • Vite (vite)
  • Create React App (cra)
  • Remix (remix)
  • SvelteKit (svelte)
  • Static HTML (static — no dev server required; set the entry with --entry)

​
Questions

Message the founder directly at [email protected] anytime!