# hedra-mcp-server

An MCP (Model Context Protocol) server for the [Hedra v3 API](https://www.hedra.com/docs/pages/developer/getting_started/quickstart) — 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:**
   ```bash
   npm install
   npm run build
   ```

3. **Set your API key:**
   ```bash
   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.

```bash
npm start
```

**Claude Code / Claude Desktop config** (add to your MCP servers config):
```json
{
  "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

```bash
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
```