all posts

Video Download MCP: Add a Download Tool to Your Agent

A practical guide to the video download MCP server: what the six tools return, how the async job model works, and how to connect Claude Code, Cursor, or Codex.

Videodownload team

The short answer

A video download MCP server gives an AI agent the same capability a person has in a browser: paste a public link, choose a format, and save the file. The Videodownload server exposes six tools over streamable HTTP, runs yt-dlp and ffmpeg on a hosted worker, and returns a signed URL that expires after 15 minutes.

The agent never installs Python, never bundles an extractor, and never sees a platform cookie. It calls a tool, polls a job, and hands the user a link.

Why not put yt-dlp inside the agent?

A local wrapper is tempting. yt-dlp is Unlicense, covers more sites than any alternative, and updates quickly. But an agent that runs on a user's machine has three problems a hosted tool does not:

  1. Install surface. Python, the binary, and ffmpeg have to exist on every machine. A remote MCP client or a web agent has no shell to install them.
  2. Update drift. Platforms change their pages constantly. Every user can end up on a different yt-dlp version, and the agent has no way to know which one works.
  3. Resource control. A loop that downloads a two-hour video can fill a disk. A hosted worker can cap duration, file size, and concurrency before the download starts.

The hosted model moves those concerns to one place. The tradeoff is that the URL and job metadata leave the machine, and the worker is a shared service. For a team agent or a product feature, that is usually the right trade.

The six tools

  • resolve_video: title, duration, thumbnail, platform, formats. Free.
  • list_formats: the format list only. Free.
  • download_video: create an MP4, audio, or GIF job. One credit.
  • get_download: status, progress, and the signed file URL. Free.
  • cancel_download: stop a job and refund the credit. Free.
  • extract_audio: create an MP3 job. One credit.

The split matters. An agent should resolve first, show the user what it found, and only then spend a credit. A resolve call is also the cheapest way to check whether a platform is currently readable.

The job model

download_video does not return a file. It returns a job id:

{
  "code": 0,
  "data": {
    "job_id": "job_810d06575caa26661070579d",
    "status": "queued",
    "credits_charged": 1
  }
}

Poll get_download every two seconds. The status moves through queued, resolving, downloading, processing, and then ready, failed, canceled, or expired. When it is ready, the response contains a signed URL, a MIME type, a size, and an expiry time.

That design is deliberate. An HTTP request cannot hold a connection open for a 10 minute download, and a client that retries a create call should not create two files. One job id, one charge, one file.

Connect Claude Code

claude mcp add --transport http videodownload \
  https://videodownloadmcp.com/mcp \
  --header "Authorization: Bearer vd_your_key"

Run claude mcp list to confirm the connection. Then ask Claude to resolve a public URL. The first tool call is free, so you can test the schema before buying credits.

Connect Cursor

Create .cursor/mcp.json in the project:

{
  "mcpServers": {
    "videodownload": {
      "url": "https://videodownloadmcp.com/mcp",
      "headers": {
        "Authorization": "Bearer vd_your_key"
      }
    }
  }
}

Restart Cursor and enable the server in the agent panel. Cursor decides when to call it; you can still ask for resolve_video explicitly when you want the metadata first.

For Codex and generic stdio clients, the npm package wraps the same API:

[mcp_servers.videodownload]
command = "npx"
args = ["-y", "@videodownload/mcp"]
env = { VIDEODOWNLOAD_API_KEY = "vd_your_key" }

What the server refuses

The safe default is part of the product, not an afterthought:

  • Private accounts, follower-only posts, and age-restricted media return PRIVATE_CONTENT or LOGIN_REQUIRED.
  • DRM protected streams return DRM_PROTECTED.
  • Live streams are not supported.
  • Videos over 30 minutes and files over 500 MB are refused before the worker spends bandwidth.
  • Hosts outside the platform allowlist are rejected, and the worker resolves DNS before it fetches a page.

If you need a different policy for a private deployment, run the worker yourself and keep the MCP schema. The hosted service will not accept cookies or bypass a login wall.

A good agent prompt

The skill file does the heavy lifting, but a clear request helps:

Resolve this public TikTok link, show me the available MP4 qualities, and download the 1080p version if it exists. Give me the signed URL and tell me when it expires.

That prompt maps cleanly to resolve_video, a short confirmation, download_video, and get_download. Vague prompts like "download this" work too, but the agent has to guess at a quality.

Limits worth knowing

  • Resolve is limited to 20 calls per minute per key.
  • New jobs are limited to 8 per minute per key.
  • Files expire 15 minutes after they are ready.
  • Anonymous web downloads are limited to 3 per network per day.

The limits are per key, not per account, so a noisy agent can be isolated with its own key. Usage is visible at /v1/me and in the dashboard.

Further reading

more posts