@zvid/mcp

Official Zvid agent and MCP server. Creator follows a quality-first workflow: plan the brief, adapt designed examples or library assets, validate exact project JSON, save a reviewable draft, then render only after approval. Automation and Developer add trusted direct operations.

Authentication

There are exactly two ways to authenticate. Every setup below uses one of them:

Method 1 — OAuth sign-in. Add https://mcp.zvid.io/mcp to your MCP client and sign in when prompted. The endpoint publishes OAuth discovery metadata, uses authorization code + PKCE with the single scope zvid:mcp, and issues short-lived access tokens with rotating refresh tokens (revocable per RFC 7009). This is what the client-specific instructions below use.

Method 2 — API key. Create a key at app.zvid.io/api-keys, then either:

• Hosted: send it in the X-Api-Key header on https://mcp.zvid.io/mcp — for programmatic clients that cannot run an OAuth flow, or legacy access.
• Local stdio / self-hosted: pass it via ZVID_API_KEY / --api-key as shown in Local stdio / self-hosted setup. The stdio transport is API-key only, because MCP OAuth is defined for HTTP transports.

Hosted setup (recommended)

The hosted endpoint is https://mcp.zvid.io/mcp. It accepts both authentication methods: OAuth sign-in (method 1 — used by the client instructions below) and an API key in the X-Api-Key header (method 2).

Claude Code

claude mcp add --transport http zvid https://mcp.zvid.io/mcp
claude mcp login zvid

You can also open /mcp inside Claude Code and authenticate there.

OpenAI Codex

Add this to ~/.codex/config.toml, then authenticate from MCP settings or run codex mcp login zvid:

[mcp_servers.zvid]
url = "https://mcp.zvid.io/mcp"
auth = "oauth"
scopes = ["zvid:mcp"]
oauth_resource = "https://mcp.zvid.io/mcp"

The dashboard stores the default tool profile and maximum credits per render for MCP clients. A client may connect with concrete values in the endpoint, for example https://mcp.zvid.io/mcp?profile=creator&maxRenderCredits=60; this is connection configuration and cannot be changed by the model during a conversation. The default per-render credit limit is 120, and the dashboard limit, when set, is a hard ceiling: the effective limit is the lower of the dashboard value and the value requested in the endpoint.

The official n8n workflow copies both dashboard defaults into its workflow JSON when downloaded. Each workflow can then choose another concrete profile and credit ceiling locally without updating the dashboard or any other workflow.

Local stdio / self-hosted setup

The npm/stdio entry point uses an API key (authentication method 2). Configuration resolution is CLI flags, then environment, then ~/.zvid-mcp.json:

npx -y @zvid/mcp --api-key zvid_your_key_here --api-url http://localhost:4000

For a self-hosted OAuth deployment, keep the resource and issuer identical on both services:

The orchestrator also accepts OAUTH_ACCESS_TOKEN_TTL_SECONDS and OAUTH_REFRESH_TOKEN_TTL_SECONDS; their defaults are one hour and 30 days.

From a checkout:

cd mcp && npm install && npm run build
claude mcp add zvid --env ZVID_API_KEY=zvid_your_key_here -- node /absolute/path/to/mcp/dist/index.js

Default Creator workflow

The default creator profile is the former Advanced authoring surface. It exposes planning, designed examples, creative-library search, stock media, schema/docs, repair, validation, projects and templates alongside approval-aware draft tools.

Creator deliberately rejects create_media and revise_media calls that omit the complete project payload. This prevents a weak model from improvising a poor layout from a brief. The agent must plan, adapt or assemble an exact payload, validate it remotely, fix every error and layout warning, and only then save the draft. create_media remains non-spending; render_media still requires the user-approved signed quote.

When the user asks for a reusable template rather than a one-off video or image, create_media_template saves a parameterized project — a top-level variables object of safe defaults referenced via {{name}} placeholders — as a persistent tpl_… template. It returns the declared variables, a credit estimate for rendering the untouched defaults, and an editor deep link (https://editor.zvid.io/?template=<id>). create_media_from_template then instantiates the template with new variable values as an approval-gated draft with a signed quote. Neither call spends credits. In the creator profile create_media_template requires the complete parameterized payload, mirroring create_media.

Rendering is deliberately separate from drafting. Quote tokens are HMAC-signed, expire after 15 minutes, bind the draft ID, project version, canonical payload hash, media type and estimated credits, and are revalidated immediately before submission. An idempotency UUID prevents retry duplication.

Capability profiles

Update and delete tools remain disabled in every profile. Stored webhook secrets are redacted by get_webhook; only create_webhook returns a new secret. Bulk calls default to 25 items even though the underlying API can accept more.

The server also publishes four user-invoked workflow prompts (product promo, social reel, thumbnail and square post) and safe MCP resources at zvid://authoring/guidelines and zvid://account/summary.

Creator, Automation and Developer tools

The following low-level capabilities are available only in the profiles described above:

Schema-aware authoring

The server doesn't just forward payloads — it knows the Zvid project schema. The schema tools are backed by a shared module (../schema, vendored as src/zvidSchema.ts) that is derived from the live backend validation (orch/middleware/validation.js) and parity-tested against it, so tool answers never drift from what the API actually accepts. When public docs and these tools disagree, the tools (backend) win.

The server also advertises this workflow as MCP instructions, so compliant clients receive it at initialize time. The example-first flow for an AI client authoring a video:

1. plan_creative_video with the brief, format, duration, brand and variation mode. The response includes ranked libraryCandidates and a decision.
2. Decision adapt-example: start_from_example with the top slug to see its variables and adaptation map, then the easiest premium path — pick new variable VALUES (copy, media URLs, brand colors) and call render_from_example { slug, variables }; the server keeps the designed layout/animations intact. Edit the payload manually only when variables cannot express the change (keep the layout skeleton; never simplify a complex example into plain text). Manual template route: create_template → preview_template → create_render { template, variables } — variables are inert on direct payload renders.
3. Decision assemble-similar (or nothing close on inspection): assemble the planned scene recipes from the returned design-templates, canvas-presets and shapes modules (or search_creative_library). Never force an unrelated full-video template.
4. Use search_stock_media for topic-specific visuals and music for each scene — full-quality src URLs, natural size ≥ the canvas.
5. When composing, call get_project_schema / list_supported_elements / get_element_docs for the exact shape.
6. Run validate_project_json (add remote: true to check against the caller's real plan) and fix every error and layout warning. Use repair_project_json only for mechanical mistakes.
7. create_render / create_image_render, inspect a draft, revise if needed, then poll get_render for the final output.

For stills or quick "make something like X" requests without a full plan, start at find_matching_examples (type: "image" for stills).

Variation behavior:

• consistent derives a stable seed from the brief (or accepts variationSeed) for reproducible automations.
• fresh produces one new direction and expects recent library assets to be excluded.
• explore returns 2-5 materially different style/layout/storyboard directions, not recolors of one payload.

For a reusable template, replace the final render with create_template. Later use get_template to inspect it, preview_template before rendering, and duplicate_template for a safe editable copy. Update and delete mutations are intentionally not exposed as MCP tools.

Example prompts

• "Create a valid Zvid JSON payload for a 10-second promo video with a headline and background music."
• "Plan three genuinely different 9:16 creative directions for this product launch, avoid these recently used example slugs, then build the strongest one."
• "Validate this payload before rendering and explain anything that's wrong."
• "Show me the required fields for a TEXT visual."
• "What subtitle animation modes does Zvid support?"
• "This payload fails — repair it and tell me what you changed."
• "Render a 1080p video from template tpl_… with title 'Summer Sale' and give me the link when it's done."
• "Preview template tpl_… with these variables and tell me if anything fails validation."
• "Create a webhook pointing at https://example.com/hooks/zvid for completed and failed renders."
• "How many credits do I have left, and what did I spend this month?"

Webhook signature verification

Deliveries are signed: X-Zvid-Signature: sha256=HMAC_SHA256(secret, "<X-Zvid-Timestamp>.<raw body>"). The secret (whsec_…) is returned once by create_webhook; get_webhook redacts it.

Development

npm install
npm run build     # tsc → dist/
npm test          # unit + in-memory MCP round-trip tests
# real E2E against a local orchestrator:
ZVID_API_KEY=zvid_… ZVID_API_URL=http://localhost:4000 node scripts/e2e-local.mjs

Publishing (manual)

Not published yet.

npm. Bump version in package.json, then npm publish from mcp/ (public access is set via publishConfig). The prepublishOnly hook builds dist/.

Official MCP Registry (registry.modelcontextprotocol.io) — lists the server for discovery in MCP-aware clients. It reads server.json; ownership of the io.zvid/* namespace is proven with a DNS TXT record on zvid.io (or switch the mcpName/server.json name to io.github.Zvid-io/zvid-mcp to verify via GitHub instead). After npm publish:

# one-time: install the publisher CLI, then log in (DNS or GitHub)
mcp-publisher login dns --domain zvid.io      # or: mcp-publisher login github
mcp-publisher publish                          # reads ./server.json

Keep versions in sync on every release — a mismatch blocks the registry publish. Update all three together: package.json version, server.json version, and server.json packages[0].version. The server name must match in both files: package.json mcpName == server.json name.