Skip to main content
Use PydanticAI’s native MCPToolset with Magic Hour’s hosted MCP. This walkthrough checks API authorization and retrieves an existing image without a model, provider API key, or new generation.

Install and configure

Requires Python 3.11+; native validation used Python 3.12 and these package versions:
Provide a Magic Hour API key through your secret manager as MAGIC_HOUR_API_KEY. Set MAGIC_HOUR_IMAGE_PROJECT_ID to an image project ID already saved from an accepted generation. Keep credentials, account details, and temporary download URLs private.

Verify access and recover an image

Save this as your application entry point and run it with Python. It disables FastMCP telemetry and update checks before importing the client, and closes the connection when its context exits.
Discovery is public; the account read checks actual Magic Hour authorization without printing private account fields. Tool errors raise instead of becoming model retries. BinaryImage.data already contains bytes, so it needs no base64 decoding. Both recovery calls reuse the saved ID without another creation or generation charge. A timeout does not cancel the accepted job: keep its ID and retry recovery. This example limits inline media to 1 MiB; larger outputs need the exact returned signed download URL, with query parameters intact.

Use with an agent

Attach the toolset to a PydanticAI agent with toolsets=[toolset] and keep its async context open during use. For an uninstrumented agent, set agent.instrument = False; instrument is not an Agent constructor argument in this release. Model-backed runs need their own provider configuration and may spend provider tokens and Magic Hour credits. Generation sends authorized prompts and media to Magic Hour. Persist each accepted project ID before waiting and recover it instead of repeating a paid creation. See Magic Hour MCP for upload and generation workflows, our privacy policy, and the released MCPToolset source. Native validation discovered 48 tools, authenticated the account read, checked the saved project’s completed status, and recovered its usable 640×640 PNG as a native BinaryImage. Full image decode and session teardown passed. An Agent retained the same toolset with instrumentation disabled. No schema conversion, model run, provider credentials, new generation, or additional credits were part of this validation.