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

# VoltAgent

> Recover an existing Magic Hour image with VoltAgent's native MCP client, without a model call or another generation.

Use VoltAgent's `MCPClient` to discover Magic Hour tools, check API authorization,
and recover a saved image project. This example calls native `Tool.execute` methods
directly. It requires no model-provider key or VoltOps account.

## Install and configure

Requires Node.js 24+. The example pins `@voltagent/core` to 2.11.0, `ai` to 6.0.3,
`@ai-sdk/provider-utils` to 4.0.1, and `zod` to 4.6.7.

Download [recover-image.mjs](https://raw.githubusercontent.com/magichourhq/docs/main/examples/voltagent/recover-image.mjs)
and [package.json](https://raw.githubusercontent.com/magichourhq/docs/main/examples/voltagent/package.json)
into the same directory, then install:

```bash theme={null}
npm install
```

Provide a [Magic Hour API key](https://magichour.ai/developer?tab=api-keys) through your
server-side secret manager as `MAGIC_HOUR_API_KEY`. Set `MAGIC_HOUR_IMAGE_PROJECT_ID`
to the saved ID of an existing image project. Keep keys, account details, and temporary
download URLs private.

## Recover the saved project

```bash theme={null}
node recover-image.mjs
```

The example connects to `https://mcp.magichour.ai/` with explicit Streamable HTTP
and bearer authorization. `getAgentTools()` prefixes each tool name with the client
name, so it calls `magic_hour_account_retrieve` and
`magic_hour_wait_for_image_project`. Discovery alone does not validate your key;
the separate account call checks field types before reporting authorization.

The wait tool may poll the same saved ID for up to 30 seconds. If the project is still
pending, retain its ID and run recovery later. No generation call or retry loop is present.

To save the first completed PNG image locally:

```bash theme={null}
MAGIC_HOUR_SAVE_IMAGE=1 node recover-image.mjs
```

The same wait call requests at most one inline image with an 8 MiB limit. It writes
`magic-hour-image.png` in the current directory, replacing that filename if present.
This example supports PNG output only. Retrieval does not start another generation.

## Verified behavior

Native validation with Node.js 24.21.0 and VoltAgent 2.11.0 discovered 48 executable
tools, verified account field types, and recovered a completed image project using its
saved ID. The exact example saved its 640×640 PNG, matching the existing 287,872-byte
image byte for byte. A full image decode passed. The client disconnected and the process
exited with no stderr. No model or creation call was made; discovery does not mean all
48 tools were executed.

The image below was recovered from an existing project, not generated by this example:

![Existing Magic Hour image recovered through VoltAgent](https://github.com/magichourhq/docs/releases/download/docs-render-proof-20261023/node-red-px622-output.png)

## Results and connection lifecycle

Native `Tool.execute` returns the MCP result directly, including `isError`, structured
metadata, and inline image content. The example checks errors and the saved project ID
before reading results, then disconnects in `finally`. Its output reports the executable
tool count, authorization confirmation, project status, and saved filename rather than
account values or private download URLs.

This standalone process instantiates no `Agent`, `VoltAgent`, VoltOps client, reflection
server, or model provider. It sets `OTEL_SDK_DISABLED=true` before importing the SDK and
restricts the framework's console logging to its supported `fatal` level. Its own failures
report only the current operation and an optional numeric MCP error code.

Generation tools spend Magic Hour credits. If you add creation to your application,
persist each accepted project ID before waiting and never automatically repeat a paid
request after a timeout. Model-driven agents require separate provider configuration
and are outside this direct-tool example.

See [Magic Hour MCP](https://docs.magichour.ai/integration/model-context-protocol.md), our
[privacy policy](https://magichour.ai/privacy-policy), and
[VoltAgent's official MCP documentation](https://voltagent.dev/docs/agents/mcp/).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.