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 music 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 a key for clients that use manual bearer authentication, such as the Claude Code, Codex CLI, and Manus setup below. Claude and ChatGPT OAuth connector users sign in and authorize the connection instead.
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

These examples use the verb-first MCP tool names. Refresh cached tool inventories after a server update and use the exact names your client exposes, including any client prefix. Dated validation receipts retain the tool names that were actually tested at the time. The current server builds tools from its bundled Magic Hour OpenAPI specification and adds helpers for the media workflow:
  • Video: talking photo, UGC ads from a prepared image and script, video editing, translation and upscaling, 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: generate music from a description, with optional custom lyrics or instrumental output. Use audio files with talking-photo and other tools that accept audio. Voice generation and voice cloning are not currently exposed by the hosted MCP.
  • Workflow: server health, account details, saved items, 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 account for the Claude or ChatGPT OAuth connector sign-in flow
  • For the Claude Code, Codex CLI, and Manus bearer-token setup below, 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. The same account credits fund API and MCP generations. For prepaid Kling 3.0 use, compare the annual subscription example for Creator, Pro and Business, with upfront payments and full-use cost assumptions. 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, sign in to Magic Hour if asked, and select Allow on the authorization page. A Claude connector API key is created automatically in your Developer Hub; delete that key there to disconnect.
  5. Enable the connector and ask Claude: Call Magic Hour get_account_info and confirm API access without generating media.
A returned credit balance confirms API authorization. Keep account details private.

​
Verify API access before generating

Use get_account_info to confirm API access, then 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 and video creation is asynchronous. Audio status, waiting, and download helpers can also retrieve existing API audio projects:
  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 get_upload_urls for image, audio, or 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. Unless the user gives different instructions, guide the assistant to:
  • Use Image-to-Video directly when the user already has an approved image to animate
  • Use AI Image Editor first only when the requested appearance must change or the source needs editing
  • Reuse reference images and preserve identity, style, color, lighting, and aspect ratio across scenes
  • Omit optional model and resolution only when their defaults are compatible with the account
  • For an image model recommendation, prefer nano-banana-2-lite only when account support is known; otherwise check account access and tool model metadata before choosing a model
  • For an Image-to-Video model recommendation, prefer ltx-2.5
  • Use Text-to-Video when visual consistency is not important
User instructions take precedence over these defaults. For AI Image Editor, omitted model or model="default" currently selects nano-banana, which requires a paid plan. On Free, explicitly request model="flux-2-klein", resolution="640px", and image_count=1. Available credits alone do not unlock paid-only models or larger resolutions. If a request returns plan_upgrade_required, choose a model and resolution supported by the account or upgrade; do not retry the unchanged request. Do not silently change a user-selected model.

​
Troubleshooting

  • Tools do not appear: Restart the client after adding the server, then call get_account_info.
  • Authentication fails: For Claude or ChatGPT OAuth connections, reconnect, sign in to Magic Hour, and select Allow. For manual bearer-token clients, confirm the full API key is active and authentication uses Authorization: Bearer YOUR_MAGIC_HOUR_API_KEY. Then call get_account_info to verify API access.
  • 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.