UnificAlly MCP

UnificAlly MCP server

An MCP server for the UnificAlly API. It lets an AI assistant generate video, images, music, speech and sound effects, transcribe audio and upscale media through 100+ models (Veo 3.1, Kling, Seedance, Hailuo, Grok Imagine, Nano Banana, Flux, GPT Image, Suno, ElevenLabs, Topaz) with one API key.

It works in any MCP client: Cursor, Claude Desktop, Claude Code, Cline, Windsurf, Zed, ChatGPT Desktop, Goose, n8n and your own code.

Install

1. Create an API key at https://unifically.com/api-keys. A new account starts with $0.50 of balance to test with.
2. Add the server to your client config:

{
  "mcpServers": {
    "unifically": {
      "command": "npx",
      "args": ["-y", "@unifically/mcp-server"],
      "env": { "UNIFICALLY_API_KEY": "sk-..." }
    }
  }
}

That block works as is for Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), Cline and Windsurf (~/.codeium/windsurf/mcp_config.json). Restart the client after saving.

Claude Code:

claude mcp add unifically -e UNIFICALLY_API_KEY=sk-... -- npx -y @unifically/mcp-server

{
  "context_servers": {
    "unifically": {
      "command": { "path": "npx", "args": ["-y", "@unifically/mcp-server"] },
      "env": { "UNIFICALLY_API_KEY": "sk-..." }
    }
  }
}

UNIFICALLY_API_KEY=sk-... npx -y @unifically/mcp-server

There is also a hosted server at https://mcp.unifically.com/mcp for clients that take a URL. See Remote server.

Example

Ask the assistant for something:

Make a 16:9 image of a lighthouse at dusk, then a 6 second video that starts from it.

It calls the tools in order:

{ "name": "generate_image", "arguments": { "prompt": "a lighthouse at dusk, waves, warm light", "aspect_ratio": "16:9" } }

Generated image with google/nano-banana-pro. Result: https://files.unifically.com/image/....png [task_id: 7f3c...]

{ "name": "generate_video", "arguments": { "prompt": "slow push in, waves rolling", "image_url": "https://files.unifically.com/image/....png", "duration": 6 } }

Each generation tool waits for the job and returns the media URL. The structured result looks like this:

{
  task_id: string,
  status: "completed" | "pending" | "processing",
  output: { video_url?, image_url?, audio_url?, image_urls?, audio_urls?, text? },  // when completed
  model: string,
  cost_usd?: number
}

Under the hood each call is one request to the UnificAlly API (POST /v1/tasks with { model, input }, then GET /v1/tasks/{id}), the same one shown in the API docs.

Tools

Every tool sets all four MCP hints. The seven tools that spend balance are marked destructiveHint: true and idempotentHint: false, so a client that auto-approves read-only tools still asks before a paid run. Failed generations are not charged.

Supported models, each with its parameters, id and a browser playground:

• Video: Veo 3.1, Kling, Seedance, MiniMax Hailuo, Grok Imagine, Wan 3.0, Gemini Omni Flash 1.1
• Image: Nano Banana, GPT Image 2, Flux.2 Pro, Qwen Image, SeeDream
• Music and audio: Suno, ElevenLabs
• Upscaling: Topaz Labs

list_models returns the full live catalog.

How it behaves

• Every generation tool works from a prompt alone. model is optional and takes short aliases (veo, kling, flux, nano-banana-2, seedance, tts, sfx, stt) or full ids such as google/veo-3.1-fast.
• Media fields (image_url, image_urls, end_image_url, reference_image_urls, audio_url, video_url) take public https URLs only. A local path or base64 string gets an error that says to upload first.
• Field names differ between models (Kling's start_frame_url, Veo's start_image_url, Seedance's first_frame_url). You pass image_url and the server renames it. Any field the server has no parameter for goes in provider_options, which also overrides the mapping.
• The server keeps no copy of each model's allowed durations, resolutions or aspect ratios. The API checks values and returns a 422 that names the fix, at no cost. The server instructions tell the assistant to read the model's page in docs.unifically.com/llms.txt before running a model.
• Every generation tool also accepts wait, callback_url, provider_options and confirm_cost.
• Errors come back as one sentence: 401 for a missing or wrong key, 402 for low balance (with a top-up link), 422 with the API's validation message, and a timeout message that tells the assistant to resume with get_task. 429, 5xx and network errors are retried with backoff.

Uploads

Models only read public URLs, so a local file goes to the UnificAlly CDN first.

1. upload_file { content_type: "image/png" } returns a one-time upload_url and the final file_url. The assistant sends the bytes with curl, without any API key in the shell:

   curl -X PUT '<upload_url>' --data-binary @photo.png
   

   The URL is signed, single use and expires in about 5 minutes. The file keeps full quality.

2. upload_file { url } imports a file that is already online.

3. upload_file { file_path } reads the file from disk, only when the server runs locally over stdio.

There is no base64 upload, and the instructions tell the assistant never to send a user's file to another host. Both rules come from real failures: with a base64 size limit, agents shrank users' images to fit, and one agent without a key in its shell uploaded a private photo to a public file host.

Long jobs

High quality video and full songs can take minutes.

• wait: false returns { task_id, status: "pending" } at once. Poll get_task until status is "completed".
• callback_url returns at once too, and the API POSTs the result to your webhook.

Any task can be picked up later with get_task.

Spend limits

All off by default. Set them per deployment:

• UNIFICALLY_CONFIRM_COST_ABOVE=<usd>: a call priced above this returns a quote, and runs only when the assistant retries with confirm_cost: true.
• UNIFICALLY_MAX_COST_PER_TASK=<usd>: a call priced above this is rejected. confirm_cost does not override it.
• UNIFICALLY_BLOCKED_MODELS=veo-quality,suno or UNIFICALLY_ALLOWED_MODELS=nano-banana-2,flux,tts: restrict which models can run.
• UNIFICALLY_DISABLE_GENERATION=true: read-only mode. Browsing, dry_run_cost and check_balance still work.

Environment variables

Remote server

MCP_TRANSPORT=http serves Streamable HTTP on /mcp and legacy SSE on GET /sse + POST /messages. The hosted copy runs at https://mcp.unifically.com/mcp.

Each caller sends their own key, so one deployment serves many users and bills each one's own balance:

1. Authorization: Bearer <key> (recommended)
2. X-API-Key: <key>
3. ?api_key=<key> for clients that only take a URL. Query strings can end up in proxy logs, so use a header when you can.

{
  "mcpServers": {
    "unifically": {
      "url": "https://mcp.unifically.com/mcp",
      "headers": { "Authorization": "Bearer sk-..." }
    }
  }
}

For claude.ai (Settings, Connectors, Add custom connector) put the key in the URL: https://mcp.unifically.com/mcp?api_key=sk-.... For stdio-only clients, bridge with mcp-remote:

{
  "mcpServers": {
    "unifically": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.unifically.com/mcp", "--header", "Authorization: Bearer sk-..."]
    }
  }
}

Details of the HTTP mode:

• Streamable HTTP is stateless, so it scales behind any reverse proxy without sticky sessions.
• A caller without a key can run initialize, tools/list, resources/list, prompts/list and ping, so registries can read the tool list. Everything else returns 401. Keyless traffic is rate limited per IP and capped at 16 concurrent messages. GET /.well-known/mcp-config returns a JSON Schema for the one required setting (api_key), and GET /.well-known/mcp/server-card.json returns the tool list.
• Keys are checked against the API, with the result cached, and a per-IP budget limits failed checks. Rate limits apply per key and per account, so extra keys do not raise one account's limit. Batches are capped at 16 messages and bodies at 512 KB.
• Browser Origin headers are validated against DNS rebinding. MCP clients send none and are unaffected.
• X-Forwarded-For is trusted only from UNIFICALLY_TRUSTED_PROXIES. The shipped Compose file sets private for its isolated network; do not use that on a shared LAN.
• A key with zero balance can still check the balance, list and fetch tasks and price a job. It cannot start one (402).
• GET / returns connect instructions and GET /health is an unauthenticated health check.

Self-hosting

The repo ships a Dockerfile and docker-compose.yml that run the HTTP transport with per-request keys. Put the container behind an HTTPS reverse proxy, point a domain at it and use /health as the health check. Nothing is required in the environment. UNIFICALLY_CONFIRM_COST_ABOVE=1.00 is a sensible default for a shared deployment.

Development

git clone https://github.com/unifically-dev/unifically-mcp.git
cd unifically-mcp
npm install
cp .env.example .env       # add your UNIFICALLY_API_KEY
npm run dev

Inspect the tools interactively:

npx @modelcontextprotocol/inspector npx -y tsx src/index.ts

Tests:

npm test               # build + smoke test
npm run test:vitest    # full suite

Troubleshooting

Links

• API docs: https://docs.unifically.com
• API keys: https://unifically.com/api-keys
• Models: https://unifically.com/models
• MCP page: https://unifically.com/mcp
• Support: [email protected], Discord

License

MIT