{
  "markdown": "# Magic Hour MCP Server\n\n[![smithery badge](https://smithery.ai/badge/magichourhq/magic-hour)](https://smithery.ai/servers/magichourhq/magic-hour)\n\nOpenAPI-backed MCP server for Magic Hour image, video, and audio generation.\n\nAt startup, this server reads `docs/openapi.json` and builds MCP tools with\n`FastMCP.from_openapi()`. The OpenAPI spec supplies endpoint coverage, while\nMagic Hour MCP policies add agent-facing guidance for async polling, uploads,\nand project downloads.\n\nDocs:\n\n- `user.md` - hosted endpoint user guide\n- `integration-handoff.md` - FastAPI mount checklist\n- `docs/detailed-step-by-step-integration.md` - full backend integration guide\n- `docs/api-reference.md` - generated API reference\n\n## Setup\n\n```sh\npip install -e .\n```\n\n## Run locally\n\n```sh\npython main.py\n```\n\nLocal MCP endpoint:\n\n```text\nhttp://127.0.0.1:8000/\n```\n\nThis local dev server runs at `/`, not `/mcp`. The host app adds `/mcp` when it mounts the server.\n\nBy default, requests go to the production Magic Hour API:\n\n```text\nhttps://api.magichour.ai\n```\n\nTool discovery is public. Tool calls must include your Magic Hour API key:\n\n```text\nAuthorization: Bearer <magic_hour_api_key>\n```\n\nAgents can discover the hosted server card at:\n\n```text\nhttps://mcp.magichour.ai/.well-known/mcp/server-card.json\n```\n\nEnvironment variables:\n\n```sh\nMAGIC_HOUR_API_BASE_URL=https://api.magichour.ai\nMAGIC_HOUR_OPENAPI_PATH=docs/openapi.json\nMCP_OAUTH_ISSUER_URL=https://mcp.magichour.ai\nMCP_OAUTH_RESOURCE_URL=https://mcp.magichour.ai\n```\n\nOverride `MAGIC_HOUR_API_BASE_URL` to use a mock or another API base:\n\n```sh\nMAGIC_HOUR_API_BASE_URL=https://api.sideko.dev/v1/mock/magichour/magic-hour/latest python main.py\n```\n\n## OAuth compatibility\n\nThe optional OAuth shim validates a Magic Hour API key and uses that key as the\naccess token. Production requires `MCP_OAUTH_ISSUER_URL` and\n`MCP_OAUTH_RESOURCE_URL`. See `docs/future-oauth-support.md` for deployment\nlimits.\n\nPublic OAuth clients can use the stateless `POST /register` compatibility endpoint.\n\n## Test with MCP Inspector\n\n1. Start the server.\n2. Run:\n   ```sh\n   npx @modelcontextprotocol/inspector\n   ```\n3. In Inspector:\n   - Transport: `Streamable HTTP`\n   - URL: `http://127.0.0.1:8000/`\n   - Header: `Authorization: Bearer <magic_hour_api_key>`\n4. Call `ping`.\n5. Call `video_assets_generate_presigned_url` or another generated tool.\n\nNotes:\n\n- FastMCP generates endpoint tools from OpenAPI at startup.\n- Creation tools return `id` and `credits_charged` immediately.\n- OpenAPI `operationId` values are normalized to descriptive snake_case tool names.\n- The shared `/v1/files/upload-urls` endpoint is named `video_assets_generate_presigned_url`. It accepts `video`, `audio`, and `image` items.\n- Use `wait_for_*_project` to poll jobs. Use `exact_download_urls` exactly as\n  returned; never append expiration metadata.\n- Image and audio wait tools also return inline media when supported.\n\nRebuild and type-check the MCP App UI with `cd web && npm ci && npm run build`.\n\n## File uploads\n\nMagic Hour does not accept raw file bytes inside tool arguments. The flow is:\n\n1. Call the generated shared upload-URL tool, `video_assets_generate_presigned_url`\n2. Upload the file bytes to the returned `upload_url`\n3. Pass the returned `file_path` into the generated creation tool\n\nDirect public media URLs may work, but uploaded `file_path` values are more\nreliable. Upload bytes from the caller or a dedicated upload bridge; the hosted\nMCP server never reads caller-supplied local filesystem paths. Browser chat needs\na separate upload UI or bridge; see `docs/future-chat-ui-handoff.md`.\n",
  "bytes": 3623,
  "sha": "a925b383a4ee227754cea88b2aad20d9f8b495aeeab420184e1a8fc31c4a4de4",
  "repo_slug": "magichourhq/magic-hour-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_magichourhq_magic_hour_a619f8a9/readme"
}