MCP server: generate video and images from your agent

Hook the Kadraris MCP server into an AI agent such as Claude Code, Codex or Cursor and the agent gains a toolbox: a priced model list, a cost estimate before anything runs, generation of video, images and music, task status and your balance. Ask for "a 9:16 reel about a bike repair shop" and the agent chooses a model, tells you the price and starts the job. Charges come from the same prepaid balance the API uses, and a failed generation is free.

MCP stands for Model Context Protocol, an open standard that lets agent apps use outside tools. You give the app a server address and a key one time; from then on the agent can see what tools exist and decides when to call them. You write no code and learn no endpoints.

Install with one click

• Add to Cursor: Cursor takes the key from the KADRARIS_API_KEY environment variable, so create that variable beforehand (the Codex CLI section shows how).
• Add to VS Code: VS Code prompts for the key the first time and saves it in its secure storage.

The dashboard has these buttons too, under API keys, together with copy-ready Claude Code and Codex commands that already contain the correct address. None of them include your key. The one exception: immediately after you create a key, the dashboard shows a Claude Code command with that key inserted, a single time.

API key

1. In the dashboard, go to API keys.
2. Give the key a name such as mcp-claude-code and a Monthly limit in dollars, say 15.
3. Click Create key and copy sk-kd-...; it is only displayed once.

Think of the monthly limit as a fuse. An agent that can make videos might, stuck in a loop, start clip after clip. Once the key reaches its limit, the API replies 403 and your balance stops going down. Details in Authentication.

In every example below, swap sk-kd-... for your own key.

Claude Code

Run one command in a terminal. It is the same on macOS, Linux and Windows PowerShell:

claude mcp add --transport http kadraris https://kadraris.com/mcp --header "Authorization: Bearer sk-kd-..."

Without extra options the server only exists in the folder you are in. Add --scope user to make it available in all your projects:

claude mcp add --transport http kadraris https://kadraris.com/mcp --scope user --header "Authorization: Bearer sk-kd-..."

Confirm it is there:

claude mcp list

Next to kadraris you should see Connected. During a session, /mcp shows the connection status and the tools.

Before each tool call, Claude Code asks for your permission. Leave that on for generate, because it lets you read the model and parameters the agent is about to send.

Claude Code may already be using Kadraris as its model provider through ANTHROPIC_BASE_URL (see Claude Code). MCP runs fine next to that, with the same key or a different one; either way the costs come out of one balance.

Codex CLI

Codex does not keep the key in its config. The key sits in an environment variable, and the config only records that variable's name.

macOS and Linux:

export KADRARIS_API_KEY="sk-kd-..."
codex mcp add kadraris --url https://kadraris.com/mcp --bearer-token-env-var KADRARIS_API_KEY

Windows PowerShell (this stores the variable permanently; open a new terminal afterwards):

[Environment]::SetEnvironmentVariable("KADRARIS_API_KEY", "sk-kd-...", "User")
codex mcp add kadraris --url https://kadraris.com/mcp --bearer-token-env-var KADRARIS_API_KEY

Running the command adds the following to ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml):

[mcp_servers.kadraris]
url = "https://kadraris.com/mcp"
bearer_token_env_var = "KADRARIS_API_KEY"

codex mcp list confirms the server. The complete guide, including the things Codex cannot do with Kadraris, is Codex CLI with Kadraris.

Cursor

Add .cursor/mcp.json to the project, or ~/.cursor/mcp.json to cover every project:

{
  "mcpServers": {
    "kadraris": {
      "url": "https://kadraris.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:KADRARIS_API_KEY}"
      }
    }
  }
}

At runtime Cursor swaps ${env:KADRARIS_API_KEY} for the value of the environment variable, which keeps the key out of the file. Create the variable as described under Codex CLI, then restart Cursor. You can also write the key straight in, "Authorization": "Bearer sk-kd-...", but in that case do not commit the file.

Once saved, kadraris appears among the MCP servers in Cursor's settings, where a toggle lets you disable it without removing it.

VS Code

GitHub Copilot's agent mode in VS Code loads .vscode/mcp.json. With the configuration below, VS Code asks for the key the first time the server starts and stores it in its secure storage instead of the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "kadraris-key",
      "description": "Kadraris key (sk-kd-...)",
      "password": true
    }
  ],
  "servers": {
    "kadraris": {
      "type": "http",
      "url": "https://kadraris.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:kadraris-key}"
      }
    }
  }
}

To check it, open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on a Mac), run MCP: List Servers, select kadraris and look at the status.

Cline

Open the Cline panel, click the MCP Servers icon and go to Remote Servers. Enter the name kadraris, the URL https://kadraris.com/mcp and the transport Streamable HTTP. The key header is added in the settings file, reached through Configure MCP Servers:

{
  "mcpServers": {
    "kadraris": {
      "type": "streamableHttp",
      "url": "https://kadraris.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-kd-..."
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Keep autoApprove as an empty list. That way Cline checks with you before each generation.

Claude Desktop

The Claude app and claude.ai add remote servers as custom connectors:

1. Open Customize and then Connectors.
2. Choose + Add, then Add custom connector.
3. Enter the name Kadraris and the URL https://kadraris.com/mcp.
4. Set Authentication to No sign in. Under Request headers, add Authorization with the value Bearer sk-kd-....

Anthropic's help center says custom connectors are available on Free (limited to one connector), Pro, Max, Team and Enterprise. On Team and Enterprise, an organization owner has to add the connector in the organization settings. Note that the connection is made from Anthropic's servers rather than from your own machine.

OpenCode

Add an mcp block to opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kadraris": {
      "type": "remote",
      "url": "https://kadraris.com/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer sk-kd-..."
      }
    }
  }
}

Other apps

Every app that can use a remote MCP server over Streamable HTTP needs just three values: the URL https://kadraris.com/mcp, a header named Authorization, and the value Bearer sk-kd-.... Field names vary between apps. Windsurf, for instance, expects serverUrl rather than url in mcp_config.json:

{
  "mcpServers": {
    "kadraris": {
      "serverUrl": "https://kadraris.com/mcp",
      "headers": { "Authorization": "Bearer sk-kd-..." }
    }
  }
}

Tools the server provides

An image is normally done inside 45 seconds. Video needs roughly 1-4 minutes. generate waits at most 240 seconds; if the job has not finished by then, the agent receives the task id and a suggestion to call wait_for_task. In apps that support MCP progress updates (progressToken), you see something like "running 40 s" while it waits.

Result links expire (see expires_at). Each result comes with a ready-made curl -o command, so you can simply tell the agent to "save the video in media/".

Spending guard: estimate, approve, run

Two mechanisms keep the agent from spending more than you agreed:

1. max_cost on generate. If the estimate comes out higher, the job never starts, and nothing is reserved or charged.
2. confirm_token from estimate_cost. The agent shows you the price, you approve, and it calls generate with the identical input and the token. If the model or any parameter is different from the estimate, or more than 15 minutes have gone by, the call is rejected at no cost.

The order to follow, which the built-in prompts below also use: search_models -> estimate_cost -> your approval -> generate with confirm_token and max_cost -> wait_for_task when needed.

A third guard is a dedicated key with a monthly limit (API key); get_balance tells you how much of that limit is gone.

Sending local files

Animating a photo, lip sync and reference audio all need the file as a URL. upload_file gets you one in three possible ways:

• data_base64 together with filename: the file travels inside the tool call, up to 8 MB.
• source_url: the server fetches a public link, up to 25 MB.
• request_upload_url: true: the server hands back a single-use address that stays valid for 10 minutes, and the agent uploads to it:

curl -T photo.png "https://kadraris.com/mcp/upload/..."

Invoke-WebRequest -Method Put -InFile .\photo.png -Uri "https://kadraris.com/mcp/upload/..."

All three return url, mime, bytes and expires_at. Accepted formats are PNG, JPG, WebP, MP4, MOV, MP3 and WAV, detected from the file contents rather than the file name. Uploaded files are removed after 30 days.

Built-in prompts

The server includes recipes that your app lists as prompts or slash commands (in Claude Code, for example /mcp__kadraris__reel_9x16). Each recipe takes the agent through finding a model, getting your cost approval, uploading files and generating:

Things to ask your agent

With the server connected, try requests like:

• "Create a 5-second 9:16 reel in Seedance 2.5 showing a florist opening her shop in the morning. Tell me the price and wait until I agree."
• "Make 3 header images for this README with GPT Image 2.5 at 16:9 and put them in docs/img/."
• "List the 5 lowest-priced video models that can do 1080p, with the per-second price."
• "What is my remaining balance?"
• "Get Gemini 3.6 Flash's opinion on this function and compare it with your own."

Prices of the models mentioned: Seedance 2.5 from $0.261 per second, GPT Image 2.5 $0.05 per image, Nano Banana Pro from $0.07 per image. Everything else is on Pricing.

Staying safe and in budget

• Give each agent its own key with a monthly limit. Beyond the limit the agent gets 403 and your account balance is not touched.
• Approve costs before generation. The agent calls estimate_cost, shows you the number, and then passes confirm_token and max_cost to generate (see Spending guard). Write that rule into AGENTS.md as well.
• Never auto-approve generate. The free tools are fine to auto-approve: search_models, list_models, get_model, estimate_cost, get_task, wait_for_task, list_tasks, get_balance and search_docs.
• A failed generation costs $0. The funds are only reserved while the task runs, and all of it comes back if the model returns an error.
• Do not commit your key. Project files should reference variables instead: ${env:...} in Cursor, ${input:...} in VS Code, bearer_token_env_var in Codex.

Troubleshooting

Other status codes: Errors.