[01]MCP + CLI + API

The ultimate hook-led video MCP for AI agents

Give Cursor, Claude, ChatGPT, internal automations, and custom AI agents a direct way to create viral-ready shorts with Viral Hooks. Use MCP for tool calling, or call the public API directly when you want full backend control.

Connect the MCP Get CLI Open API docs

Generate finished videos

Turn scripts, prompts, articles, audio, music, captions, avatars, and ads into hook-led short-form videos.

Built for autonomous agents

Expose the full Viral Hooks creation pipeline through MCP tools with clear resources and structured responses.

One endpoint, many workflows

Use the MCP wrapper for agent actions or call the same public API directly from your own backend.

[02]Connect

Your API key

API key placeholder

YOUR_VIRALHOOKS_API_KEY

Get your key

Keep this key secret. Requests made with it consume credits from your Viral Hooks account.

Claude Web / OAuth connector

Remote MCP

Remote MCP server URL:
https://api.viralhooks.org/mcp

Authentication:
OAuth 2.1 with PKCE

Use this for Claude Web and other hosted MCP clients.
Viral Hooks will show a login/consent screen and issue OAuth tokens for your active workspace.

API-key MCP config

Cursor / Claude Desktop

{
  "mcpServers": {
    "viralhooks": {
      "url": "https://api.viralhooks.org/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_VIRALHOOKS_API_KEY"
      }
    }
  }
}

Direct API render call

cURL

curl -X POST "https://api.viralhooks.org/v1/render" \
  -H "Content-Type: application/json" \
  -H "key: YOUR_VIRALHOOKS_API_KEY" \
  -d '{
    "workflow": "script-to-video",
    "source": {
      "text": "Create a 30-second short about 3 surprising AI productivity tips."
    },
    "hook": { "slug": "flip-on-head" },
    "media": {
      "type": "moving-image",
      "quality": "pro",
      "aspectRatio": "9:16"
    },
    "voice": {
      "enabled": true,
      "voiceId": "energetic-gen-z"
    },
    "captions": {
      "enabled": true,
      "preset": "punchy-wrap",
      "position": "bottom"
    }
  }'

Agent-readable reference

Markdown

# Viral Hooks MCP quick reference
endpoint: https://api.viralhooks.org/mcp
transport: Streamable HTTP
auth: OAuth 2.1 for hosted remote clients; Authorization Bearer, x-viralhooks-api-key, x-api-key, or key for API-key clients
primary flow: render_video -> get_project_status -> attach_hook -> export_video or publish_now
render docs resource: viralhooks://docs/render
mcp guide resource: viralhooks://docs/mcp
hook library resource: viralhooks://hooks/catalog
tools: generate_media, render_video, get_project_status, list_projects, calculate_credits, export_video, attach_hook, list_hooks, rename_project, schedule_publish, publish_now, buy_credit_pack

[03]Agent workflow

From prompt to published video

The MCP wraps Viral Hooks' public video API, so agents can generate, monitor, attach hooks, export, and publish projects without inventing their own pipeline.

Call `render_video`

Pass a workflow and source payload — script, prompt, URL, or file.

Store the `pid`

Use the returned project id as the handle for all follow-up calls.

Poll `get_project_status`

Wait until the response includes `videoUrl` (or your webhook fires).

Export or publish

Optionally call `export_video`, `attach_hook`, `schedule_publish`, or `publish_now`.

Supported video workflows

Agents pick the workflow that matches intent, then pass only the relevant source, media, voice, hook, caption, and render fields.

script-to-videoprompt-to-videoarticle-to-videoaudio-to-videomusic-to-videoavatar-to-videocaption-videoad-generatorstatic-background-videomotion-transfer

MCP tools exposed

Stable, descriptive tool names — easy for humans to scan and AI agents to parse.

generate_media

render_video

get_project_status

list_projects

calculate_credits

export_video

attach_hook

list_hooks

rename_project

schedule_publish

publish_now

buy_credit_pack

Build video agents that ship finished content

Viral Hooks handles scripting, visuals, voice, captions, hook pairing, rendering, exporting, and social publishing — your agent focuses on intent and iteration.

Create a video Get API key

[04]CLI

New: viralhooks-cli

npm

The fastest way to give shell-based agents, CI jobs, and local scripts access to Viral Hooks video creation. Supports exact API payloads, stable --json output, async waiting, hook library search, exports, credits, and project listing.

Open npm package Get API key

Install

npm install -g viralhooks-cli
export VIRALHOOKS_API_KEY="your_viralhooks_api_key"
viralhooks --help

Agent commands

Shell

viralhooks create --prompt "Street interview reaction, vertical 9:16" --hook flip-on-head --wait --json
viralhooks create --payload payload.json --wait --json
viralhooks hooks --search "rate" --json
viralhooks projects --limit 10 --json
viralhooks status <pid> --json
viralhooks export <pid> --json

[05]Examples

MCP workflows in action

Examples map directly to MCP and API workflows — from prompts and articles to motion transfer and music videos. Use them as a reference for what an agent can generate after calling render_video.

Turn simple ideas into hook-led videos

Prompt → auto script → scenes → viral hook → 9:16 export

Tool

Prompt to video

Hook

Rate This Dunk

Your prompt

Street interview rates a backflip 1–10, vertical 9:16, Gen Z energy

Script auto-generated

SCENE 1

Exterior, NYC street, golden hour. Host faces camera with a mic.

SCENE 2

Skater lands a backflip. Crowd reacts. Host points at camera.

SCENE 3

Close-up on host: "Rate that 1 to 10" — hook overlay from library.

Visual style

Cinematic realism

Format

9:16 MP4

Final video

Rate This Dunk

0:149:16

MCP server: https://api.viralhooks.org/mcp — same workflows and credits as the public API.