Magic Hour MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

video_projects_retrieve_details

Check video project status and retrieve download URLs when render completes. Poll after creation to monitor progress, surface errors, and provide signed links.

Instructions

Check the progress of a video project. The downloads field is populated after a successful render.

Statuses

queued — waiting to start
rendering — in progress
complete — ready; see downloads
error — a failure occurred (see error)
canceled — user canceled
draft — not used

MCP guidance:

Use this after a create tool to poll job status. When status is complete, surface the downloads URLs to the user; if status is error, surface the error message.
Each downloads[n].url is already the full signed download URL. Use it exactly as returned. Do not shorten it, strip query parameters, or append expires_at onto the URL string.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`id`	Yes	Unique ID of the video project. This value is returned by all of the POST APIs that create a video.

Output Schema

TableJSON Schema

Name	Required	Description
`id`	Yes	Unique ID of the video. Use it with the [Get video Project API](https://docs.magichour.ai/api-reference/video-projects/get-video-details) to fetch status and downloads.
`fps`	Yes	Frame rate of the video. If the status is not 'complete', the frame rate is an estimate and will be adjusted when the video completes.
`name`	Yes	The name of the video.
`type`	Yes	The type of the video project. Possible values are ANIMATION, AUTO_SUBTITLE, VIDEO_TO_VIDEO, FACE_SWAP, TEXT_TO_VIDEO, IMAGE_TO_VIDEO, LIP_SYNC, TALKING_PHOTO, AVATAR, VIDEO_UPSCALER, VIDEO_EDITOR, CHARACTER_REPLACE, VIDEO_COLORIZER, VIDEO_COLOR_GRADER, VIDEO_TRANSLATOR, MUSIC_VIDEO, EXTEND, AUDIO_TO_VIDEO, VIDEO_EXPANDER, UGC_AD
`error`	Yes	In the case of an error, this object will contain the error encountered during video render
`width`	Yes	The width of the final output video. A value of -1 indicates the width can be ignored.
`height`	Yes	The height of the final output video. A value of -1 indicates the height can be ignored.
`status`	Yes	The status of the video. - `draft` - the project was created but has not been submitted for rendering - `queued` - the job is waiting for an available server - `rendering` - the job is being processed; the `video.started` webhook event fires when rendering begins - `complete` - the job finished successfully; fires `video.completed` - `error` - the job failed during processing; fires `video.errored` - `canceled` - the job was manually canceled (for example from the Magic Hour web app) Note: `rendering`, `complete`, and `error` have matching webhook events; `canceled` does not - a canceled job emits no webhook event, so poll this endpoint to detect cancellation.
`enabled`	Yes	Whether this resource is active. If false, it is deleted.
`downloads`	Yes
`created_at`	Yes
`end_seconds`	Yes	End time of your clip (seconds). Must be greater than start_seconds.
`start_seconds`	Yes	Start time of your clip (seconds). Must be ≥ 0.
`credits_charged`	Yes	The amount of credits deducted from your account to generate the video. If the status is not 'complete', this value is an estimate and may be adjusted upon completion based on the actual FPS of the output video. If video generation fails, credits will be refunded, and this field will be updated to include the refund.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 23, 2026

TDQS

A4.1/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It thoroughly discloses the status lifecycle, when the downloads field is populated, and that URLs are already signed and must not be modified. This is substantive behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with statuses and MCP guidance, and every section adds useful context. Minor redundancy exists between 'downloads field is populated after a successful render' and the status descriptions, but overall it remains focused and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential operational flow: poll after creation, interpret statuses, surface downloads or errors, and preserve signed URLs. Since an output schema exists, return-value details are not necessary, though a brief mention that polling should continue until a terminal status is reached would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, and the single id parameter is documented there. The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks video project progress and maps to a specific resource and action. It distinguishes itself from create tools via 'use this after a create tool to poll job status,' but it does not explicitly differentiate itself from the sibling wait_for_video_project tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: it should be used after a create tool to poll job status, and it explains how to handle complete and error states. However, it does not provide explicit when-not-to-use guidance or mention alternatives such as wait_for_video_project.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server