How do I use vidhook-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vidhook-mcp validate this movie definition for a slideshow with background music" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

vidhook-mcp

Official

by vidhook

Overview Schema Related Servers Score Discussions

TypeScript

Local

vidhook-mcp

An MCP (Model Context Protocol) server that lets agents generate videos through the vidhook render API. It is a thin wrapper over the existing HTTP API (POST /renders/validate, POST /renders, GET /renders/{renderId}) — it does not add a new contract, schema, or renderer.

The server speaks stdio only: an MCP client (Claude Desktop, Cursor, etc.) spawns it as a child process and communicates over stdin/stdout via JSON-RPC.

Tools

Tool	What it does
`validate`	Validate a Movie definition and estimate its credit cost. Starts no render and consumes no credits. `estimatedCredits` equals the credits `render` would reserve for the same body.
`render`	Start an asynchronous render. Reserves credits and returns `renderId`, `bucketName`, `reservedCredits`.
`get_status`	Poll a render's progress with `renderId` + `bucketName`. When `done` and not `fatalErrorEncountered`, `outputFile` holds the result video URL.
`get_usage`	Return the current credit balance (`paidAvailable`, `freeAvailable`, `reserved`) and recent render activity (newest first). Takes no arguments.

All asset references in the Movie (video/image/audio src) must be URLs — vidhook does not generate assets. Compose or upload them on the agent side first.

Related MCP server: popcorn

Skill: writing correct Movie JSON

This repo also ships a Claude skill (vidhook-movie) under skills/vidhook-movie/. The split is intentional:

MCP server = hands — it executes (validate, render, get_status, get_usage) against the API.
Skill = brain — it teaches an agent how to author a correct Movie JSON in the first place.

skills/vidhook-movie/SKILL.md carries the workflow (always validate first → draft with a vh_test_ key → poll get_status → finalize with vh_live_), the key/environment axes, and the schema's hard spots. skills/vidhook-movie/reference/schema-cheatsheet.md is the full field-by-field reference, and skills/vidhook-movie/examples/*.json are complete, valid Movie definitions (slideshow + BGM + title, Ken Burns, transitions, and a composite of all four element types). Every example is checked against the API's parseMovie in CI (skills/vidhook-movie/examples.test.ts), so the skill cannot drift from the live schema.

The skill is delivered through the Claude Code plugin below, not through the npm package — Claude loads skills from plugins (or ~/.claude/skills/), never from node_modules.

Configuration

The server is configured only through environment variables. There is no way to pass an API key as a tool argument.

Variable	Required	Default	Purpose
`VIDHOOK_API_KEY`	yes	—	Your vidhook API key. Missing/empty fails startup (fail-closed).
`VIDHOOK_API_BASE_URL`	no	`https://api.vidhook.app`	API base URL.

Two independent axes

Watermarking and the target environment are separate and must not be confused:

Key type (VIDHOOK_API_KEY prefix) → watermark & billing.
- vh_test_… → free tier, watermarked output (use for drafts/iteration).
- vh_live_… → paid, clean output (use for final renders).
Base URL (VIDHOOK_API_BASE_URL) → environment.
- e.g. https://api.vidhook.app (production) vs. a staging base URL.

A vh_test_ key against production still watermarks; the base URL only changes which environment you talk to, never whether the output is watermarked.

Installing in MCP clients

The server is published to npm and runs via npx, so most clients need no separate install step — just point them at npx -y vidhook-mcp and set VIDHOOK_API_KEY. Requires Node.js ≥ 20. Use a vh_test_… key while wiring things up (free, watermarked); swap in vh_live_… for clean output once it works.

Claude Code (recommended): skill + MCP in one

Claude Code can install this repo as a plugin, which bundles both the vidhook-movie skill (the brain) and the MCP server declaration (the hands) in a single step. This is the only way Claude auto-loads the skill — it is not picked up from node_modules.

/plugin marketplace add https://github.com/vidhook/vidhook-mcp
/plugin install vidhook@vidhook

The plugin prompts you for your vidhook API key when it's enabled (masked input, stored in your system keychain — never written to settings.json). Verify with /plugin (skill listed) and claude mcp list (server vidhook registered).

To add just the tools (no skill) from the CLI instead:

claude mcp add vidhook -e VIDHOOK_API_KEY=vh_test_your_key_here -- npx -y vidhook-mcp

(-e sets the env var, everything after -- is the launch command.) Scoped to the current project by default; add --scope user for all projects, or --scope project for a shared .mcp.json.

Other MCP clients

Most clients use the same mcpServers shape. Add this entry to the client's MCP config file, then restart the client:

{
  "mcpServers": {
    "vidhook": {
      "command": "npx",
      "args": ["-y", "vidhook-mcp"],
      "env": { "VIDHOOK_API_KEY": "vh_test_your_key_here" }
    }
  }
}

The config file location differs per client:

Client	Config file	Notes
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) · `%APPDATA%\Claude\claude_desktop_config.json` (Windows)	Settings → Developer → Edit Config
Cursor	`.cursor/mcp.json` (project) · `~/.cursor/mcp.json` (global)
Windsurf	`~/.codeium/windsurf/mcp_config.json`	Cascade → MCP settings → manage
VS Code (Copilot)	`.vscode/mcp.json` (workspace)	Top-level key is `servers`, not `mcpServers`

VS Code can also add it from the command line: code --add-mcp '{"name":"vidhook","command":"npx","args":["-y","vidhook-mcp"],"env":{"VIDHOOK_API_KEY":"vh_test_your_key_here"}}'

npx -y vidhook-mcp fetches and runs the published package. If you install it globally (npm i -g vidhook-mcp), set "command": "vidhook-mcp" with no args instead.

Local development

Clone this repo and run the server directly from source:

mise run setup        # install deps (or: pnpm install)
pnpm dev              # stdio server (tsx src/index.ts)
pnpm build            # bundle to dist/index.js (tsup)

Tests

pnpm test             # unit (HTTP boundary stubbed) + skill example structure
pnpm test:e2e         # validate every skill example against the live API (needs VIDHOOK_API_KEY)

The test:e2e run is the schema drift-check: each skills/vidhook-movie/examples/*.json is sent to the live /renders/validate, so the examples cannot go stale against the real Movie schema.

Local smoke test

e2e/smoke.ts runs validate → render → get_status → get_usage once against a real API to leave an end-to-end trace:

VIDHOOK_API_KEY=vh_test_... VIDHOOK_API_BASE_URL=https://staging-api.vidhook.app \
  pnpm exec tsx e2e/smoke.ts

It prints only the key prefix (never the full key).

Available Tools

3 tools

get_statusGet render statusA

Poll the progress of a render started with the render tool. When done is true and fatalErrorEncountered is false, outputFile holds the result video URL. Pass the renderId and bucketName returned by render.

ParametersJSON Schema

Name	Required	Description	Default
`renderId`	Yes	The render id returned by the render tool.
`bucketName`	Yes	The bucketName returned by the render tool (alongside renderId).

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description adequately explains behavior: polling for completion, conditions for success (done true, fatalErrorEncountered false), and outputFile URL. It implies repeated calls but does not discuss rate limits or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no wasted words. First sentence states purpose, second adds key behavioral details. Structure is efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple polling tool with 2 parameters and no output schema, the description fully explains input requirements, expected behavior, and output interpretation. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for both parameters. The description adds minimal value beyond stating they come from the render tool, which is already in the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (poll), resource (render progress), and context (started with render tool). It distinguishes from siblings render and validate by specifying it's a polling operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to use after render and to pass renderId and bucketName from render. It does not provide when-not-to-use guidelines, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

renderStart a renderA

Submit a Movie definition (and optional webhook) and start an asynchronous render. Reserves credits and returns renderId, bucketName, and reservedCredits. Poll progress with get_status using the returned renderId and bucketName. All asset references must be URLs (vidhook does not generate assets). Insufficient credits return an error (HTTP 402). Authentication and watermarking are set by the VIDHOOK_API_KEY environment variable only (never a tool argument): vh_test_… renders a free/watermarked draft, vh_live_… renders clean/paid. The target environment is selected independently by VIDHOOK_API_BASE_URL (base URL), not by the key type.

ParametersJSON Schema

Name	Required	Description	Default
`movie`	Yes	Movie definition (json2video-compatible). resolution/scenes/elements etc. All asset references (video/image/audio src) must be URLs — vidhook does not generate assets; compose them on the agent side. Validated by the vidhook API.
`webhook`	No	Optional completion-notification webhook (alongside the Movie fields).

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully covers behavioral traits: asynchronous behavior, credit reservation, return fields, polling mechanism, error handling (HTTP 402), authentication via environment variable, watermarking based on key prefix, and independence of API base URL. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that efficiently conveys multiple pieces of information. It is not overly verbose, but could benefit from slight structural organization (e.g., bullet points) for easier scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (asynchronous, nested parameters, authentication, credit system), the description is remarkably complete. It covers return values, error conditions, asset constraints, and polling instructions, leaving no major gaps despite lacking an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for each parameter. The description adds valuable context beyond the schema, such as the URL requirement for asset references and the authentication environment variable details, enhancing understanding for the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Submit a Movie definition... and start an asynchronous render.' It specifies the verb, resource, and outcome, and distinguishes from siblings like get_status (polling) and validate (validation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit context for use: when to start a render, requirements (credits, URLs, authentication via environment variables), and how to proceed (poll with get_status). It does not explicitly say 'when not to use' but implies alternatives via sibling tool mentions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validateValidate a render and estimate creditsA

Validate a Movie definition (and optional webhook) WITHOUT starting a render or consuming any credits, and return the estimated credit cost. Use this to preview cost and catch errors before calling render. estimatedCredits equals the credits render would reserve for the same body. Invalid Movies or SSRF-rejected webhook URLs are returned as errors (HTTP 400) from the API. Authentication and watermarking are set by the VIDHOOK_API_KEY environment variable only (never a tool argument): vh_test_… renders a free/watermarked draft, vh_live_… renders clean/paid. The target environment is selected independently by VIDHOOK_API_BASE_URL (base URL), not by the key type.

ParametersJSON Schema

Name	Required	Description	Default
`movie`	Yes	Movie definition (json2video-compatible). resolution/scenes/elements etc. All asset references (video/image/audio src) must be URLs — vidhook does not generate assets; compose them on the agent side. Validated by the vidhook API.
`webhook`	No	Optional completion-notification webhook (alongside the Movie fields).

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that no credits are consumed, no render started, and that errors are returned for invalid movies or webhooks. Mentions authentication and environment variable dependencies. Lacks detail on the exact response structure (e.g., if only estimatedCredits is returned), but overall well-covered for a validation tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph of four sentences, front-loaded with the core purpose. Includes necessary details on authentication and error handling without excessive verbosity. Could be slightly more structured, but efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's role as a pre-render validation, the description covers when to use, what it does, authentication, and error handling. No output schema exists, so lack of response detail is acceptable. Sufficient for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds valuable context: asset references must be URLs and the agent must compose assets. The webhook parameter's purpose as a completion notification is clarified, adding beyond the schema's basic property descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool validates a Movie definition, estimates credits without consuming them, and distinguishes from 'render' (which starts a render) and 'get_status' (status retrieval). The verb 'validate' and resource 'Movie definition' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to 'use this to preview cost and catch errors before calling render.' Also explains that authentication is via environment variables, guiding correct usage. Clear when-to-use and what not to expect (no render start).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0

Disambiguation5/5

Each tool has a distinct purpose: render starts an async render, get_status polls its progress, and validate checks definitions without consuming credits. No overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (get_status, render, validate), making them predictable and clear.

Tool Count5/5

Three tools is appropriate for the server's purpose—submitting renders, polling status, and validating definitions—without being too few or excessive.

Completeness5/5

The tools cover the essential workflow (validate, render, get_status) for the video rendering service. No obvious gaps given the API's scope.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp-veo
io.github.AceDataCloud
MCP server for Google Veo AI video generation
Multimedia Processing Image & Video Processing Entertainment & Media
23
clipkit A
dev.clipkit
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Multimedia Processing Image & Video Processing
15212
mcp-wan
io.github.AceDataCloud
MCP server for Wan AI video generation
AI & Machine Learning Image & Video Processing
21
mcp-kling
io.github.AceDataCloud
MCP server for Kling AI video generation
Image & Video Processing AI & Machine Learning
21

Related MCP Servers

Heygen MCP Server
AI & Machine Learning Multimedia Processing
dineshkumar181094
A
license
B
quality
D
maintenance
This MCP server enables any MCP client to generate avatars and videos using the HeyGen API, with tools for managing credits, voices, and avatar video generation.
Updated a year ago (2025-04-21 13:23 UTC)
7
MIT
popcorn
Multimedia Processing Image & Video Processing Speech Processing
haithamelmengad
A
license
A
quality
D
maintenance
An MCP server that enables AI agents to analyze videos locally by extracting transcripts, detecting scene changes, and returning key frames.
Updated 7 months ago (2026-02-05 12:49 UTC)
5
6
MIT
@vivideo/mcp
Image & Video Processing Multimedia Processing
egocen-vivideo
A
license
Not graded
quality
B
maintenance
MCP server providing 13 agent-friendly tools for video creation and management via the Vivideo API, with built-in rate limiting, retries, and secret redaction.
Updated a month ago (2026-07-28 13:42 UTC)
MIT
Cleya
Multimedia Processing Image & Video Processing
severment
A
license
Not graded
quality
A
maintenance
An MCP server for creative generation and video production, letting AI agents author declarative animations, render deterministic frames, and measure output quality with perception instruments for brand and accessibility conformance.
Updated a month ago (2026-08-05 07:21 UTC)
Apache 2.0

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vidhook/vidhook-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server