Use Hedra MCP or CLI from your AI agent

MCP exposes Hedra tools to a compatible client. The CLI is a terminal client for Hedra API v3; it is not documented as an MCP wrapper. The Developer API lets your application own the interaction. Choose by the task, not a speed or quality ranking. CLI identity · Hedra’s comparison.

The comparison below describes Hedra’s published behavior. We have not verified a generation on any of these paths. The plan and wallet details need checking for the account you will actually use.

You need access to the intended Hedra account or workspace, a client that can connect to remote MCP or run the CLI, and permission to use the input media. For the npm installation route, you also need Node.js and npm. Use a synthetic image or another sample asset you are authorized to upload.

Account eligibility is not the billing source. Hedra’s MCP/CLI article currently requires a Hedra account and subscription for both paths, while its landing pages use broader subscription-or-pay-as-you-go language. Do not interpret that broader wording as proof that every account can generate through every transport. Confirm access and the billing source before the first submission.

For CLI or API generation, check the USD wallet. The v3 quickstart distinguishes it from Studio credits and documents 402 INSUFFICIENT_BALANCE before funding. This guide does not authorize a purchase, top-up or generation.

Use the published endpoint:

https://mcp.hedra.com

Add it through your client’s remote MCP or connector setup, then finish Hedra’s browser sign-in. Select the intended account and workspace. After connection, inspect the tools and their inputs before asking for a render. A connected server does not prove that a media job has run. Official MCP setup.

If the client requires a key, Hedra directs users to Create MCP key in its developer console. The documented scopes are jobs:read, jobs:write, models:read and files:write. This key covers model lookup, reference uploads and job submission/status; it does not grant key administration, webhook management or usage access. Browser sign-in and this scoped-key fallback are different setup paths. MCP authentication FAQ.

The following clients are listed by Hedra as supported integrations / agent workflows. These are vendor setup directions, not six independent AgentSkillsHub tests. A client’s plan, admin policy, shell access and exposed tool set still matter.

The official executable is hedra-cli, distributed through @hedra/cli. These are documentation-based commands; we did not install or authenticate the CLI in this review. Installation and authentication.

npm install --global @hedra/cli
hedra-cli auth login
hedra-cli auth status

Browser login exchanges the session for a durable API key in the OS keyring. hedra-cli auth login --with-token is the documented alternative for putting an existing key into that keyring. Do not paste that key into a chat prompt.

Credential precedence: HEDRA_API_KEY overrides the stored keyring credential. The CLI also loads a working-directory .env. If the wrong workspace is being used after login or workspace selection, inspect auth status and the environment source before changing credentials or submitting a job.

The default target is the production API, https://api.hedra.com/v3. A help command, login, or successful credential check is not a sandbox generation and is not a delivery test.

Use the credential expected by the selected interface:

• MCP browser sign-in: complete the client’s Hedra authorization flow.
• MCP scoped key: use the dedicated four-scope fallback when that client needs a key.
• CLI keyring credential: managed by auth login; check the active source with auth status.
• HEDRA_API_KEY: an environment-provided CLI credential that shadows the keyring; it is not a new permission tier.
• Developer API key: belongs to its documented account/workspace and scope; it need not have the same grants as an MCP key.

There is a visible documentation inconsistency: the CLI README describes Authorization: Bearer <credential>, while the v3 quickstart uses Authorization: Key <key_id>:<secret>. The Get Job reference itself shows a Bearer example and identifies Key as the primary scheme. This review did not test their interchangeability. Let the documented CLI manage its own authentication; follow the selected endpoint’s current instructions for direct API code instead of copying headers across examples.

Hedra advertises visual understanding and image, video, music and voice generation. That is a capability description, not a promise that every MCP client exposes identical tools or parameters. Inspect the connected MCP tool descriptions or use CLI model discovery. Advertised capabilities · CLI model commands.

hedra-cli models list
hedra-cli models get --model PLACEHOLDER_MODEL
hedra-cli models get-openapi --model PLACEHOLDER_MODEL
hedra-cli jobs submit --help

Replace PLACEHOLDER_MODEL with an ID returned by the catalog. Build input from that model’s schema: one model’s image field, duration, quality or resolution is not a universal option. If a reference upload is needed, the documented command is hedra-cli files upload --file INPUT_FILE; replace INPUT_FILE with an authorized sample file and use the returned reference as that model permits.

These next commands are templates, not copy-and-run examples. Replace MODEL_INPUT_JSON with a valid JSON object matching the selected model. Keep the shell quoting appropriate to your terminal.

hedra-cli models estimate --model PLACEHOLDER_MODEL --input 'MODEL_INPUT_JSON'
hedra-cli jobs submit --model PLACEHOLDER_MODEL --input 'MODEL_INPUT_JSON' --dry-run --no-retry

The README documents --dry-run as local validation/request printing without sending the request. An estimate is a separate API request that creates no generation job. The current progress guide clarifies that /estimate returns a price, not a completion time, despite the README’s broader “Cost/ETA” label. Inspect the actual estimate; do not invent a fixed fee or ETA.

Only move to this step after approving the real task and its spend. Removing --dry-run sends a generation request. The following syntax is documented, uses placeholders and was not run here. CLI jobs reference.

hedra-cli jobs submit --model PLACEHOLDER_MODEL --input 'MODEL_INPUT_JSON' --no-retry

Save the returned job_id before doing anything else. Replace JOB_ID below with that exact value:

hedra-cli jobs get-status --job-id JOB_ID
hedra-cli jobs get --job-id JOB_ID --format json

The API job reference distinguishes IN_QUEUE, IN_PROGRESS, COMPLETED and FAILED. Submission acceptance is not completion. Poll the existing ID at a reasonable interval until a terminal state; inspect the error if it fails. jobs get retrieves a result envelope, not automatically a downloaded media file.

The status endpoint can report progress and estimated_completion_at. These are estimates; some models return no completion estimate. A null ETA is not evidence of failure, and an ETA is not a deadline. Progress semantics.

Inspect every relevant entry in outputs[], not just the job’s top-level status. The result reference provides output URLs and fields such as content_type, width, height, duration_ms, fps and per-output errors. Use the fields that actually exist for the selected output; absent values mean unmeasured or unavailable, not zero.

The API output guide distinguishes COMPLETED, FAILED and EXPIRED output items. It documents a 48-hour v3 media retention window after completion; expired items retain metadata but lose their media URL and asset reference. Download required files promptly. This API retention rule is not a claim that the MCP’s Hedra library has the same retention policy. For a later API job, read outputs[].asset_id; do not derive it from the job ID.

AgentSkillsHub editorial acceptance checklist — not a Hedra guarantee:

1. Record the job ID and its terminal state.
2. Confirm the intended output item succeeded and has a usable reference.
3. Download from the returned location and confirm the HTTP request succeeds.
4. Compare the file’s actual format, MIME type and extension; reject an HTML error saved as media.
5. Open the media and check dimensions or duration against the approved task.
6. Confirm it shows the requested subject, not an unrelated or earlier asset.
7. Check for unexpected duplicate jobs or repeated spend before declaring delivery complete.

COMPLETED is service-side success. Delivery passes only after the intended file can be retrieved and inspected.

The MCP/CLI storage and billing distinction in the comparison table comes from Hedra’s transport-specific article: MCP adds a library item and returns a file link; CLI returns a download link without adding a library item. A link alone does not mean the bytes are saved on your computer.

For the API path, the quickstart uses a prepaid USD balance separate from Studio credits. The balance reference describes the balance associated with the credential’s billing identity and reports amounts in USD. CLI users can inspect the documented hedra-cli billing get-balance command with an appropriately permitted credential; the limited MCP key is not a general billing-admin key.

Check the wallet and account shown before submission. An empty or missing balance is not a reason for an agent to buy credits automatically. The general pricing page describes plans, but does not make the CLI free or guarantee that every MCP generation is included in a subscription. No fixed model prices are reproduced here.

If a request times out or the agent loses its connection, start with the known job ID. Query its status, then retrieve its current result or error. Do not treat a missing chat message as proof that Hedra did not accept the job.

The CLI README documents an optional --idempotency-key for replaying the original acknowledgement rather than enqueueing a duplicate. It also documents --no-retry to disable an operation’s declared retries, including network retries. Neither statement establishes an unlimited deduplication window or exactly-once billing.

Editorial retry rule: record the original request and any idempotency key, reconcile the existing job, and inspect any returned retryable / retry_after error fields before making a new decision. Do not rotate the key or blindly resubmit to escape an unknown result. Exactly-once generation and billing guarantees remain unverified in this review.

EDITORIAL EXAMPLE — NOT RUN. A fictional lamp brand needs a short product motion clip, with a target duration of five seconds if the selected model supports it.

• Input: a synthetic lamp image, cleared for upload.
• Plan: choose MCP for the conversation or CLI for a shell workflow; inspect the available model and reference-image input.
• Before submission: identify the credential and billing source, inspect an available estimate, and approve exactly one job.
• Execution design: submit once, retain the job ID, follow its status and retrieve the intended output.
• Acceptance: the output opens as a video, has an appropriate duration and MIME type, shows the lamp, and has no unexplained duplicate job or repeat charge.

Five seconds is this example’s target, not a universal Hedra parameter. Model options must come from the current schema. Nothing in this example was uploaded or generated during our review.

AgentSkillsHub editorial precautions: keep credentials out of prompts, repositories and shared logs. Do not expose an API key while copying debug output or a printed request. Use sample assets rather than private customer media, confirm the upload destination, and review how the external service handles that data.

Grant only the needed scopes and remove credentials you no longer use. The key reference says omitted scopes mean full access. It distinguishes personal keys from workspace service keys managed by an owner/admin; a service key can survive a member’s departure. Review that ownership and revocation boundary before attaching credentials to a shared agent.

Each user should authenticate through the supported account flow. Sharing a connector configuration is not permission to share its secret or spend another workspace’s balance. Keep TLS verification enabled. Our MCP server security checklist covers broader permission review; MCP agent skills explains how to turn a tool into a bounded workflow.

• CLI not found / npm permissions: check the installation and PATH. The npm route needs Node.js; use the supported package-manager setup rather than changing system permissions blindly.
• Login succeeded, wrong identity used: inspect auth status, HEDRA_API_KEY and the selected workspace. Environment shadowing can defeat the keyring selection.
• Connected MCP but a tool is missing: inspect the actual tool list, client/admin restrictions and Hedra account access. A marketing capability is not a client-specific schema.
• Invalid input: read the selected model’s schema and CLI --help; keep the returned field error rather than repeatedly submitting variants.
• 402 INSUFFICIENT_BALANCE: check the relevant USD wallet and obtain a spending decision; Studio credits are a separate balance.
• Job still running: query the existing ID. A rough ETA or a null progress estimate is not a terminal result.
• Job completed but no usable file: inspect each output status, URL and error, then test the download. An expired output cannot be recovered by polling its metadata again.
• Lost response: reconcile the original job before considering another submission.

Sources: CLI behavior, wallet prerequisite, job status, output expiry.