Skip to main content
Model Context Protocol (MCP) lets AI assistants call external tools. Magic Hour MCP lets compatible assistants create and edit media through Magic Hour’s API-backed tools. Connect the hosted server once, then ask for an image, video, or audio result in plain English. The assistant selects tools, starts jobs, waits for renders, and returns the finished files.
Hosted MCP endpoint

Get a Magic Hour API key

Create the key used to authorize MCP tool calls.
This is the creation MCP, which can call Magic Hour tools. If you only want an assistant to search these API docs while you write code, use the API Docs MCP.

​
What the server exposes

The current server builds tools from its bundled Magic Hour OpenAPI specification and adds helpers for the media workflow:
  • Video: talking photo, video editing, animation, audio-to-video, subtitles, character replace, face swap, image-to-video, lip sync, text-to-video, and video-to-video
  • Image: generation and editing, clothes and face editing, GIFs, headshots, upscaling, memes, QR codes, body/face/head swaps, background removal, and photo colorization
  • Audio: voice generation and voice cloning
  • Workflow: server health, file-upload URLs, face detection, project status and deletion, render waiting, and secure retrieval of completed image, audio, and video files
Magic Hour MCP reflects the API-backed tool catalog. It does not claim to expose every tool in the Magic Hour web app.

​
Before you connect

You need:
  • A Magic Hour API key
  • A client that supports remote Streamable HTTP MCP servers
  • Enough Magic Hour credits for the generations you request
Tool discovery is public, but every tool call requires authentication. Real generation requests spend Magic Hour credits, and creation tools return the credits charged with the project ID. Keep your API key private and never commit it to source control.

​
Connect a client

  1. Open Settings → Connectors in Claude and add a custom connector.
  2. Name it Magic Hour and use https://mcp.magichour.ai/ as the connector URL.
  3. If Claude asks for an OAuth client ID in Advanced settings, enter magic-hour-mcp.
  4. Select Connect. On the Magic Hour authorization page, paste your API key and continue.
  5. Enable the connector and ask Claude: Call the Magic Hour ping tool.
The expected response is pong.

​
Verify API access before generating

After ping, ask the agent to call account_retrieve and check eligibility for the intended generation. Tool discovery can work without credentials, and an invalid API key can still receive pong; the account read checks actual API authorization. Authentication required means the bearer token is missing. An account 401 means authorization failed. Check the key and the environment that launched the agent before reinstalling anything. Keep account details private.

​
Add media generation workflows

The MCP gives your assistant access to Magic Hour tools. The Magic Hour skills cookbook adds workflows and published examples for prompting, tool sequencing, output review, and recovery without duplicate paid jobs.
Choose your agent in the installer. You can also install one workflow from the cookbook. Published examples record their validation limits; tool availability alone does not establish output quality.

​
Try a first request

Start with a prompt that does not require an uploaded file:
Other examples:

​
How render jobs work

Image, video, and audio creation is asynchronous:
  1. A creation tool starts the job and immediately returns a project id and credits_charged.
  2. The assistant calls the matching wait_for_image_project, wait_for_video_project, or wait_for_audio_project helper.
  3. The wait helper stops when the project is complete, has an error, is canceled, or times out.
  4. Completed projects return exact_download_urls. Those signed URLs must be used exactly as returned without removing query parameters or appending expiration metadata.
Compatible clients can also receive completed media inline from the wait and download helpers.

​
Using input files

The hosted server deliberately does not read a path on your computer. For local media, the complete flow is:
  1. Call video_assets_generate_presigned_url. Despite its name, it accepts image, audio, and video items.
  2. Have the client or an upload bridge send the raw bytes to the returned upload_url.
  3. Pass the matching returned file_path to the creation tool.
Direct public media URLs may work when they return stable raw file bytes, but uploaded Magic Hour file_path values are more reliable. A browser attachment only works when the MCP client provides the required upload bridge; the hosted server cannot fetch a caller-supplied local filesystem path.

​
Built-in video guidance

When the user does not give different instructions, the current server tells the assistant to:
  • Prefer AI Image Editor followed by Image-to-Video for multi-step video creation
  • Reuse reference images and preserve identity, style, color, lighting, and aspect ratio across scenes
  • Prefer nano-banana-2-lite for image creation/editing and ltx-2.3 for Image-to-Video
  • Add an appropriate AI Voice Generator narration when it suits the video and let sentences finish
  • Use Text-to-Video when visual consistency is not important
User instructions take precedence over these defaults.

​
Troubleshooting

  • Tools do not appear: Restart the client after adding the server, then call ping.
  • Authentication fails: Confirm the full API key is active and bearer authentication uses Authorization: Bearer YOUR_MAGIC_HOUR_API_KEY.
  • Codex cannot see the server: Launch Codex from the shell where MAGIC_HOUR_API_KEY is set.
  • You only received a project ID: Ask the assistant to call the matching wait_for_*_project helper and return the finished result.
  • A signed link fails: Ask for the exact download URL again. Do not shorten it, strip its query parameters, or append expires_at.
  • A local attachment cannot be used: Use a client with an upload bridge or upload the file first and provide its Magic Hour file_path.

Magic Hour MCP overview

See product examples and the hosted connector URL.

Official MCP repository

Inspect the implementation, policies, and tests used for this guide.