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.
POST https://videodownloadmcp.com/mcp
Authorization: Bearer vd_your_key
Content-Type: application/jsonClient setup
Remote HTTP is the shortest path. The local stdio package is available for clients that cannot make outbound HTTP calls with headers.
claude mcp add --transport http videodownload \
https://videodownloadmcp.com/mcp \
--header "Authorization: Bearer vd_your_key"- 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 videoResolve 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 formatsReturn 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 videoCreate 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 downloadGet 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 downloadCancel 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 audioCreate 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.
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": { "name": "cursor", "version": "1.0.0" }
}
}{
"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_URLThe URL is not a valid public http(s) link.
INVALID_ARGUMENTA required argument is missing or malformed.
UNSUPPORTED_PLATFORMThat host is not on the supported platform list.
PRIVATE_CONTENTThe post is private or followers-only.
DRM_PROTECTEDThe media is DRM protected and will not be decrypted.
LOGIN_REQUIREDThe platform requires a logged-in session for this post.
RATE_LIMITEDToo many requests. Retry after the window resets.
QUOTA_EXCEEDEDThe free daily quota for this network is used up.
INSUFFICIENT_CREDITSThe API key owner has no credits left.
EXTRACTOR_FAILEDThe extractor could not read this page.
FILE_TOO_LARGEThe file is larger than 500 MB.
DURATION_LIMIT_EXCEEDEDThe video is longer than 30 minutes.
LIVE_NOT_SUPPORTEDLive streams are not supported.
TIMEOUTThe request timed out. Retry once.
NOT_FOUNDThe job or media no longer exists.
JOB_NOT_READYThe job has no downloadable file yet.
UNAUTHORIZEDA valid Bearer API key is required.
INTERNALUnexpected 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.
Create a key, connect one client, and ask for a resolve. The quickstart covers the REST path if your client does not support MCP.