How to Give Your AI Agent Video Generation via MCP (2026 Guide)

What Makes an Agent Video-Capable?

An MCP-compatible agent becomes video-capable by connecting to an MCP server that exports video tools. MediaEngine provides video generation through both local (`npx`) and remote (https://mcp.mcpmediaengine.com/mcp) endpoints. Video generation requires a **Pro or higher plan** (video unavailable on Free and Starter).

The key difference from image generation: **videos take longer (usually 15-60 seconds) and cost more credits (2-3 per generation)**. This requires async polling or webhooks—no blocking calls.

Getting Started: Check Your Plan

First: **video generation requires Pro plan or higher**. Free tier has 25 credits (images only). Starter plan (400 credits/month) supports images only. Pro plan ($99/month, 1,400 credits) unlocks video.

If you're on Starter and want to test video, upgrade to Pro. If you need Pro features but already subscribed, video access activates immediately.

Setup: Local MCP (Claude Desktop)

Step 1: Get Your API Key

Verify your plan includes video: Log into https://app.mcpmediaengine.com, check your plan tier under Account Settings.

Step 2: Configure Claude Desktop

Open `~/.claude/claude.json` (macOS/Linux) or `%APPDATA%/Claude/claude.json` (Windows) and add:

{
  "mcpServers": {
    "mediaengine": {
      "command": "npx",
      "args": ["-y", "mcp-media-engine"],
      "env": {
        "MEDIAENGINE_API_KEY": "me_live_your_key_here"
      }
    }
  }
}

Step 3: Restart Claude

Quit and reopen Claude Desktop. The video tools are now available.

Step 4: Generate a Video

Simply ask Claude: "Generate a short video of a sunset over mountains, 5 seconds, 720p"

Claude will use the video generation tool and return the video URL inline.

Setup: Remote MCP (Production Agents)

For cloud agents or team deployments, use the remote endpoint:

{
  "mcpServers": {
    "mediaengine": {
      "url": "https://mcp.mcpmediaengine.com/mcp",
      "env": {
        "MEDIAENGINE_API_KEY": "me_live_your_key_here"
      }
    }
  }
}

The remote endpoint is identical to local—same tools, same syntax, no code changes needed.

Available Video Models

Query `https://api.mcpmediaengine.com/api/models` to see the live catalog. Current video models:

| Model | Resolution | Credits | Use Case | |-------|-----------|---------|----------| | **seedance-480p** | 480p | 2 | Quick clips, social media | | **seedance-720p** | 720p | 3 | Standard quality videos | | **seedance-1080p** | 1080p | 3 | Full HD videos | | **hailuo-720p** | 720p | 3 | Alternative HD model | | **hailuo-1080p** | 1080p | 3 | Alternative Full HD |

**Always use the live catalog.** New models ship regularly. Query the API before building; don't hardcode model IDs.

curl https://api.mcpmediaengine.com/api/models \
  -H "Authorization: Bearer me_live_..."

Response includes model ID, description, and credit cost. Use exactly what the API returns.

Video Generation: Async Pattern Required

**Unlike images, videos require async polling or webhooks.** Videos take 15-60 seconds; synchronous calls will timeout.

Async Polling (Simple)

async function generateVideo(prompt: string): Promise<string> {
  // 1. Submit the job
  const response = await fetch(
    'https://api.mcpmediaengine.com/api/jobs',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer me_live_...`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        type: 'video',
        model: 'seedance-720p',
        inputParams: {
          prompt: prompt,
          duration: 5
        },
        idempotencyKey: crypto.randomUUID()
      })
    }

const { data: job } = await response.json();

// 2. Poll for completion (every 2 seconds) let attempts = 0; while (attempts < 60) { const statusResponse = await fetch( `https://api.mcpmediaengine.com/api/jobs/${job.mediaJobId}`, { headers: { 'Authorization': `Bearer me_live_...` } } ); const result = await statusResponse.json();

if (result.data.status === 'done') { return result.data.outputs[0].url; } if (result.data.status === 'failed') { throw new Error(`Video job failed: ${result.data.errorMessage}`); }

await new Promise(r => setTimeout(r, 2000)); attempts++; }

throw new Error('Video generation timeout'); } ```

Webhooks (Production)

For high-volume workflows, use webhooks instead of polling:

const response = await fetch(
  'https://api.mcpmediaengine.com/api/jobs',
  {
    method: 'POST',
    headers: { 'Authorization': `Bearer me_live_...` },
    body: JSON.stringify({
      type: 'video',
      model: 'seedance-720p',
      inputParams: { prompt: 'A sunset over mountains', duration: 5 },
      webhookUrl: 'https://yourapp.com/webhooks/mediaengine'
    })
  }

// Your webhook endpoint app.post('/webhooks/mediaengine', (req, res) => { const { jobId, status, outputs } = req.body;

if (status === 'done') { updatePostWithVideo(jobId, outputs[0].url); }

res.json({ received: true }); }); ```

Realistic Latency & Timeouts

**Median generation time: 20-40 seconds** (varies by model and duration).

seedance-480p: ~15-25 seconds
seedance-720p: ~20-35 seconds
hailuo-1080p: ~25-40 seconds

Poll every 2 seconds (standard). If polling every 500ms, 40 videos in parallel = 80 requests over 40 seconds = acceptable load.

**HTTP timeout:** Most clients timeout at 30 seconds. Use async patterns, not blocking calls.

Aspect Ratios & Resolutions

Video generation is resolution-based (480p, 720p, 1080p), not aspect ratio-based. All models generate 16:9 landscape by default.

For different aspect ratios (vertical video, square), submit the prompt with aspect instruction: "Vertical video format, 9:16, TikTok style"

Actual support varies by model. Check the live docs for aspect ratio guarantees.

Pricing: Video Generation

**Video is 2-3 credits per generation** (not per second, but per job).

At Starter plan ($29/400cr): - 400 credits ÷ 3 credits/video = ~133 videos/month - Cost: **$0.218 per video** (~22 cents)

At Pro plan ($99/1400cr): - 1,400 credits ÷ 3 credits/video = ~466 videos/month - Cost: **$0.212 per video** (~21 cents)

**Free tier:** No video. 25 credits for images only.

**Starter plan:** No video (images only). Must upgrade to Pro.

Compare to stock video ($30-100 per clip) or video production ($500+). At 21 cents per generation, AI video is cost-effective for content workflows.

Idempotency Keys

Always include an idempotency key when submitting video jobs:

idempotencyKey: `video-${postId}-${timestamp}`

If your agent crashes mid-submission and retries, MediaEngine returns the original job instead of re-generating. Zero wasted credits.

Common Pitfalls

**"Tool not found"** — Restart Claude after editing claude.json.

**"Invalid API key"** — Verify it starts with `me_live_` and is copied exactly.

**"Video generation unavailable"** — You're on Free or Starter plan. Upgrade to Pro to unlock video.

**"Connection timeout"** — Polling took too long. Increase max attempts or reduce poll interval.

**"Model not found"** — You hardcoded a model ID that's changed. Query /api/models and use the live response.

**Slow generation** — First video takes 30-40s (model loading). Subsequent videos are faster. Parallel jobs speed up high-volume workflows.

Batch Video Generation

For 100s of videos, submit all jobs first, then poll in parallel:

// 1. Submit all jobs
const jobIds = await Promise.all(
  videos.map(v =>
    submitVideoJob(v.prompt, v.duration)
  )

// 2. Poll all in parallel const results = await Promise.all( jobIds.map(id => waitForJob(id)) );

// 3. Attach URLs to posts videos.forEach((v, i) => { v.videoUrl = results[i][0].url; }); ```

**Speedup:** 100 videos sequentially = 4000 seconds (~67 minutes). 100 videos parallel = ~60 seconds. **67x faster.**

Next Steps

Review [available models](/models) to see latest video options
Learn [async patterns](/blog/async-vs-streaming-ai-media-generation) for production
Check [pricing](/pricing) for Pro plan upgrade
Read [cost optimization](/blog/how-much-does-an-ai-image-cost-2026) for budget planning
Explore [docs](/docs) for API reference and webhook spec