> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magichour.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Magic Hour MCP

> Connect an AI assistant to Magic Hour to create and edit images, video, and audio.

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.

```text Hosted MCP endpoint theme={null}
https://mcp.magichour.ai/
```

<Card title="Get a Magic Hour API key" icon="key" href="https://magichour.ai/developer?tab=api-keys&ref=docs-mcp&utm_source=docs&utm_medium=referral&utm_campaign=mcp" horizontal>
  Create the key used to authorize MCP tool calls.
</Card>

<Note>
  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](/integration/api-docs-mcp).
</Note>

## 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](https://magichour.ai/developer?tab=api-keys\&ref=docs-mcp-requirements\&utm_source=docs\&utm_medium=referral\&utm_campaign=mcp)
* 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

<Tabs>
  <Tab title="Claude">
    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`.
  </Tab>

  <Tab title="Claude Code">
    Add the hosted server with your API key as a bearer token:

    ```bash theme={null}
    claude mcp add --scope user --transport http magic-hour https://mcp.magichour.ai/ --header "Authorization: Bearer YOUR_MAGIC_HOUR_API_KEY"
    ```

    Start a new Claude Code session and ask it to call the Magic Hour `ping` tool.
  </Tab>

  <Tab title="Codex CLI">
    Set your API key in the shell that will launch Codex:

    ```bash macOS and Linux theme={null}
    export MAGIC_HOUR_API_KEY="YOUR_MAGIC_HOUR_API_KEY"
    ```

    ```powershell PowerShell theme={null}
    $env:MAGIC_HOUR_API_KEY = "YOUR_MAGIC_HOUR_API_KEY"
    ```

    Add the hosted server:

    ```bash theme={null}
    codex mcp add magic-hour --url https://mcp.magichour.ai/ --bearer-token-env-var MAGIC_HOUR_API_KEY
    ```

    Start Codex from the same shell and ask it to call the Magic Hour `ping` tool.
  </Tab>

  <Tab title="ChatGPT">
    If custom connectors are available for your ChatGPT plan or workspace, add a connector using:

    ```text theme={null}
    https://mcp.magichour.ai/
    ```

    The server publishes OAuth discovery metadata and supports public client registration for ChatGPT
    connector redirect URLs. Complete the Magic Hour authorization screen with your API key, enable the
    connector, and ask ChatGPT to call the Magic Hour `ping` tool.

    ChatGPT controls connector availability and where its setup controls appear.
  </Tab>
</Tabs>

## 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](https://github.com/magichourhq/skills) adds workflows and published examples for
prompting, tool sequencing, output review, and recovery without duplicate paid jobs.

```bash theme={null}
npx skills add magichourhq/skills --skill '*'
```

Choose your agent in the installer. You can also install one workflow from the
[cookbook](https://github.com/magichourhq/skills). 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:

```text theme={null}
Create a square cinematic image of a neon ramen shop at night. Wait for the Magic Hour job to
finish and show me the result.
```

Other examples:

| Goal                 | Example request                                                                 |
| -------------------- | ------------------------------------------------------------------------------- |
| Edit an image        | `Add realistic sunglasses to this portrait and preserve the person's identity.` |
| Animate a still      | `Turn this image into a five-second video with gentle camera movement.`         |
| Swap faces           | `Swap this source face onto the person in this target image.`                   |
| Create speech        | `Generate speech saying “Welcome to Magic Hour” with a warm narrator voice.`    |
| Make a talking photo | `Make this portrait speak using my audio file.`                                 |

## 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`.

<CardGroup cols={2}>
  <Card title="Magic Hour MCP overview" icon="wand-magic-sparkles" href="https://magichour.ai/mcp?utm_source=docs&utm_medium=referral&utm_campaign=mcp">
    See product examples and the hosted connector URL.
  </Card>

  <Card title="Official MCP repository" icon="github" href="https://github.com/magichourhq/magic-hour-mcp">
    Inspect the implementation, policies, and tests used for this guide.
  </Card>
</CardGroup>