Magic Hour MCP server

Magic Hour MCP Server

OpenAPI-backed MCP server for Magic Hour image, video, and audio generation.

At startup, this server reads docs/openapi.json and builds MCP tools with FastMCP.from_openapi(). The OpenAPI spec supplies endpoint coverage, while Magic Hour MCP policies add agent-facing guidance for async polling, uploads, and project downloads.

Docs:

• Magic Hour agent skills - media workflows, published examples, and recovery guidance
• user.md - hosted endpoint user guide
• integration-handoff.md - FastAPI mount checklist
• docs/detailed-step-by-step-integration.md - full backend integration guide
• docs/api-reference.md - generated API reference

Setup

pip install -e .

Run locally

python main.py

Local MCP endpoint:

http://127.0.0.1:8000/

This local dev server runs at /, not /mcp. The host app adds /mcp when it mounts the server.

By default, requests go to the production Magic Hour API:

https://api.magichour.ai

Tool discovery is public. Tool calls must include your Magic Hour API key:

Authorization: Bearer <magic_hour_api_key>

Agents can discover the hosted server card at:

https://mcp.magichour.ai/.well-known/mcp/server-card.json

Environment variables:

MAGIC_HOUR_API_BASE_URL=https://api.magichour.ai
MAGIC_HOUR_OPENAPI_PATH=docs/openapi.json
MCP_OAUTH_ISSUER_URL=https://mcp.magichour.ai
MCP_OAUTH_RESOURCE_URL=https://mcp.magichour.ai

Override MAGICHOURAPIBASEURL to use a mock or another API base:

MAGIC_HOUR_API_BASE_URL=https://api.sideko.dev/v1/mock/magichour/magic-hour/latest python main.py

OAuth

This server is an OAuth protected resource only. The authorization server is the Magic Hour web app (https://magichour.ai): users sign in and consent there, and it returns a Magic Hour API key as the access token, which this server passes through to the API. Production requires MCPOAUTHISSUERURL and MCPOAUTHRESOURCEURL. See docs/future-oauth-support.md.

Test with MCP Inspector

1. Start the server.
2. Run:

npx @modelcontextprotocol/inspector

1. In Inspector:

• Transport: Streamable HTTP
• URL: http://127.0.0.1:8000/
• Header: Authorization: Bearer

1. Call ping.
2. Call videoassetsgeneratepresignedurl or another generated tool.

Notes:

returned; never append expiration metadata.

• FastMCP generates endpoint tools from OpenAPI at startup.
• Creation tools return id and credits_charged immediately.
• OpenAPI operationId values are normalized to descriptive snake_case tool names.
• The shared /v1/files/upload-urls endpoint is named videoassetsgeneratepresignedurl. It accepts video, audio, and image items.
• Use waitforproject to poll jobs. Use exactdownloadurls exactly as

• Image and audio wait tools also return inline media when supported.

Rebuild and type-check the MCP App UI with cd web && npm ci && npm run build.

File uploads

Magic Hour does not accept raw file bytes inside tool arguments. The flow is:

1. Call the generated shared upload-URL tool, videoassetsgeneratepresignedurl
2. Upload the file bytes to the returned upload_url
3. Pass the returned file_path into the generated creation tool

Direct public media URLs may work, but uploaded file_path values are more reliable. Upload bytes from the caller or a dedicated upload bridge; the hosted MCP server never reads caller-supplied local filesystem paths. Browser chat needs a separate upload UI or bridge; see docs/future-chat-ui-handoff.md.