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

Other clients

Zed (~/.config/zed/settings.json):

{

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

ChatGPT Desktop: Settings, Connectors, Add MCP server. Command npx -y @unifically/mcp-server, plus the UNIFICALLY_API_KEY variable.

Goose, n8n or anything else that speaks stdio:

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

On Windows, if the client says npx not found, use "command": "cmd", "args": ["/c", "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.

1. upload_file { url } imports a file that is already online.
2. 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= : a call priced above this returns a quote, and runs only when the assistant retries with confirm_cost: true.
• UNIFICALLY_MAX_COST_PER_TASK= : 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 (recommended)
2. X-API-Key:
3. ?api_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 stat