MCP endpoint

Six video tools over one HTTP endpoint.

The MCP server speaks JSON-RPC 2.0 over streamable HTTP at/mcp. Point Claude Code, Claude Desktop, Cursor, or Codex at it and pass a vd_ API key.

endpoint
POST https://videodownloadmcp.com/mcp
Authorization: Bearer vd_your_key
Content-Type: application/json

Client setup

Remote HTTP is the shortest path. The local stdio package is available for clients that cannot make outbound HTTP calls with headers.

Claude Code
claude mcp add --transport http videodownload \
  https://videodownloadmcp.com/mcp \
  --header "Authorization: Bearer vd_your_key"
protocol
transport
Streamable HTTP, one JSON-RPC message per POST.
version
2025-06-18, falling back to 2025-03-26 or 2024-11-05 when a client asks for an older revision.
auth
Bearer vd_ key. Missing or invalid keys get HTTP 401 before JSON-RPC runs.
session
Stateless. Every request can land on a different instance.

The tool contract

Input schemas are small on purpose. Agents pick a URL, a format, and a quality; the server owns the extractor details.

resolve_videoResolve video

Resolve a public video URL into title, duration, thumbnail, platform, uploader, and available formats. Use this before download_video when the user wants to choose a quality.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Public video URL. http(s) only. Private, DRM protected, and live streams are rejected."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
list_formatsList formats

Return the MP4, MP3, and GIF formats available for a public URL, with dimensions, file size estimates, and whether a video format already includes audio.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Public video URL. http(s) only. Private, DRM protected, and live streams are rejected."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
download_videoDownload video

Create an asynchronous download job for a public video URL. Returns a job_id and status. Poll get_download for progress and a signed download URL. Costs 1 credit.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Public video URL. http(s) only. Private, DRM protected, and live streams are rejected."
    },
    "format": {
      "type": "string",
      "enum": [
        "mp4",
        "audio",
        "gif"
      ],
      "description": "Output type. `mp4` downloads video, `audio` extracts MP3, `gif` recodes a short clip."
    },
    "quality": {
      "type": "string",
      "description": "Requested quality such as `1080p`, `720p`, `480p`, `360p`, or `audio`. The worker picks the best available format at or below this height."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}
get_downloadGet download

Get the status, progress, metadata, and signed file URL for a download job. The file URL expires 15 minutes after the job becomes ready.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job_id returned by download_video."
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}
cancel_downloadCancel download

Cancel a queued or running download job and refund its credit when one was charged.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job_id returned by download_video."
    }
  },
  "required": [
    "job_id"
  ],
  "additionalProperties": false
}
extract_audioExtract audio

Create an asynchronous MP3 extraction job for a public video URL. Costs 1 credit. Same job lifecycle as download_video.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Public video URL. http(s) only. Private, DRM protected, and live streams are rejected."
    },
    "quality": {
      "type": "string",
      "enum": [
        "mp3"
      ],
      "description": "Audio output format. Only mp3 is supported today."
    }
  },
  "required": [
    "url"
  ],
  "additionalProperties": false
}

A full exchange

Initialize once, list the tools, then call one. The response below is the actual JSON-RPC envelope, not an SDK abstraction.

initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "cursor", "version": "1.0.0" }
  }
}
tools/call
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "resolve_video",
    "arguments": {
      "url": "https://www.youtube.com/watch?v=aqz-KE-bpKQ"
    }
  }
}

resolve rate limit

20/min

download rate limit

8/min

max duration

30 min

file TTL

15 min

Errors an agent can branch on

Every tool failure is returned as isError with a stable code. The HTTP status matches the class of failure when the whole request fails.

INVALID_URL

The URL is not a valid public http(s) link.

INVALID_ARGUMENT

A required argument is missing or malformed.

UNSUPPORTED_PLATFORM

That host is not on the supported platform list.

PRIVATE_CONTENT

The post is private or followers-only.

DRM_PROTECTED

The media is DRM protected and will not be decrypted.

LOGIN_REQUIRED

The platform requires a logged-in session for this post.

RATE_LIMITED

Too many requests. Retry after the window resets.

QUOTA_EXCEEDED

The free daily quota for this network is used up.

INSUFFICIENT_CREDITS

The API key owner has no credits left.

EXTRACTOR_FAILED

The extractor could not read this page.

FILE_TOO_LARGE

The file is larger than 500 MB.

DURATION_LIMIT_EXCEEDED

The video is longer than 30 minutes.

LIVE_NOT_SUPPORTED

Live streams are not supported.

TIMEOUT

The request timed out. Retry once.

NOT_FOUND

The job or media no longer exists.

JOB_NOT_READY

The job has no downloadable file yet.

UNAUTHORIZED

A valid Bearer API key is required.

INTERNAL

Unexpected server error. The request id is in the logs.

Full HTTP request and response examples are in the API reference.

MCP questions

The endpoint is intentionally narrow. It downloads public video and audio, and nothing else.

Is the endpoint stateful?+

No. Each POST is a complete JSON-RPC exchange, so any Worker instance can answer it. Do not rely on an Mcp-Session-Id.

Does GET /mcp speak SSE?+

GET on /mcp returns this page, not an event stream. The server only sends server-initiated messages inside a tool call, so streamable HTTP POST with JSON responses is enough.

Which tools cost credits?+

resolve_video and list_formats are free inside the rate limit. download_video and extract_audio cost one credit each. A failed job refunds the credit.

Can agents call it without a person watching?+

Yes, but the key is still scoped to an account and rate limited. Use a dedicated key per agent, watch /v1/me, and rotate the key if it leaks.

start here

Create a key, connect one client, and ask for a resolve. The quickstart covers the REST path if your client does not support MCP.