hedra-mcp-server

An MCP (Model Context Protocol) server for the Hedra v3 API — browse Hedra's model catalog (Seedance, Veo, Kling, GPT Image, Hedra Avatar, ElevenLabs, and more) and submit, poll, and manage generation jobs, all from an MCP client like Claude.

Built against Hedra's public OpenAPI spec (https://www.hedra.com/docs/openapi-v3.json) but not tested against the live API — the environment that built this had no network access to api.hedra.com. Test it against your real key before relying on it (see "Try it" below).

What it does

14 tools across 4 areas:

Models — hedra_list_models, hedra_get_model, hedra_get_model_input_schema, hedra_list_model_voices, hedra_estimate_cost Jobs — hedra_submit_job, hedra_get_job, hedra_get_job_status, hedra_wait_for_job, hedra_list_jobs, hedra_list_model_jobs Files — hedra_upload_file (from a local path, a remote URL, or inline base64) Billing — hedra_get_balance, hedra_get_usage

Not covered (can be added later if you need them): webhook management, log drains, API key rotation. These are account-admin operations rather than day-to-day generation workflow, so they were left out to keep the initial tool surface focused.

Setup

1. Get a Hedra API key. You need a paid Hedra plan. Go to https://www.hedra.com/develop/api-keys, generate a key (format <key_id>:<secret>), and fund the API wallet at https://www.hedra.com/develop/billing — it starts at $0.00 and is separate from Hedra Studio credits.

2. Install dependencies and build:

   npm install
   npm run build
   

3. Set your API key:

   export HEDRA_API_KEY="your_key_id:your_secret"
   

Try it locally (stdio)

This is the easiest way to test — no deployment needed. Works with Claude Code, Claude Desktop, or any MCP client that can launch a local process.

npm start

Claude Code / Claude Desktop config (add to your MCP servers config):

{
  "mcpServers": {
    "hedra": {
      "command": "node",
      "args": ["/absolute/path/to/hedra-mcp-server/dist/index.js"],
      "env": { "HEDRA_API_KEY": "your_key_id:your_secret" }
    }
  }
}

Sanity-check before anything else

Once connected, ask your MCP client to call hedra_get_balance. If that returns your real balance, auth is wired correctly. Then try hedra_list_models with modality: "VIDEO" to confirm the catalog loads.

Deploy remotely (for Claude.ai as a custom connector)

Claude.ai's web/mobile app needs a live HTTPS endpoint — it can't launch a local process. Deploy this server somewhere with a public URL, then add it as a custom connector.

1. Deploy to any Node host (Fly.io, Render, Railway, a VPS, etc.). Set the environment variables:

   • HEDRA_API_KEY=your_key_id:your_secret
   • TRANSPORT=http
   • PORT=3000 (or whatever your host expects)

   Start command: npm run build && npm run start:http

2. Verify it's up: curl https://your-deployed-host/health should return {"status":"ok","server":"hedra-mcp-server"}.

3. Add it in Claude.ai: Settings → Connectors → Add custom connector → enter https://your-deployed-host/mcp as the URL.

⚠️ Security note: this server has no built-in authentication on the /mcp endpoint beyond the Hedra key baked into its environment — anyone who can reach the URL can spend your Hedra balance. Put it behind your host's access controls (IP allowlist, a reverse-proxy auth layer, etc.) if it's reachable from the open internet, especially since it's tied to a real prepaid wallet.

Typical workflow

1. hedra_list_models(modality="VIDEO")           → find seedance-20's id
2. hedra_get_model_input_schema("seedance-20")   → see required fields, enums
3. hedra_upload_file(file_path="./start.jpg")    → get a handle url (if using image-to-video)
4. hedra_estimate_cost("seedance-20", {...})     → confirm price before spending
5. hedra_submit_job("seedance-20", {...})        → returns job_id
6. hedra_wait_for_job(job_id)                    → blocks until done, returns outputs[].url

Project structure

src/
  index.ts              # entry point, transport selection (stdio/http)
  constants.ts           # timeouts, page sizes, base URL
  types.ts                # TS types mirroring Hedra's API shapes + HedraApiError
  services/
    hedra-client.ts       # typed fetch wrapper: auth, requests, pagination, uploads
    format.ts              # error formatting, JSON truncation, tool response helpers
  schemas/
    common.ts               # shared Zod fragments (pagination, media refs, ids)
  tools/
    models.ts                 # catalog + schema + cost estimate tools
    jobs.ts                     # submit/get/status/wait/list tools
    files.ts                     # upload tool
    billing.ts                    # balance/usage tools
test/
  smoke.mjs             # connects via stdio, lists tools, sanity-checks error handling

Development

npm run dev     # tsx watch mode against src/index.ts (stdio)
npm run build    # tsc -> dist/
node test/smoke.mjs   # after building: verify tool registration + error handling