MCP Server

Coverr provides a Model Context Protocol (MCP) server that enables AI assistants and agents to interact with the Coverr API using structured tools.

Endpoint

POST https://mcp.coverr.co/mcp

The MCP server is available at the https://mcp.coverr.co/mcp URL and follows the Streamable HTTP transport specification.

Authentication

Every call needs your Coverr API key. The server accepts it three ways — pick whichever your MCP client supports.

Method 1: x-api-key header

The standard API key header, and the one most MCP clients offer out of the box:

x-api-key: {api_key}

Method 2: x-coverr-api-key header

An explicitly namespaced alias, useful when your client already sends an x-api-key for another service:

x-coverr-api-key: {api_key}

Method 3: OAuth 2.0 (Bearer token)

The server implements an OAuth 2.0 flow for MCP clients. When configuring your client:

• Client ID: Any value (can be "coverr-client")
• Client Secret: Use your Coverr API Key as the secret.

The OAuth metadata is available at:

GET /.well-known/oauth-authorization-server

If more than one is present, x-coverr-api-key wins, then x-api-key, then the Authorization: Bearer token.

Available Tools

Videos

get_videos

Fetch a list of videos from the Coverr API. Supports search, filtering, and pagination.

get_video

Fetch a single video by ID. Returns video details including URLs.

Collections

get_collections

Fetch a paginated list of curated video collections.

get_collection

Fetch a single collection by ID.

get_collection_videos

Fetch videos from a specific collection. Supports search and pagination.

Categories

get_categories

Fetch a paginated list of video categories.

get_category

Fetch a single category by ID or slug.

get_category_videos

Fetch videos from a specific category. Supports search and pagination.

Audios

get_audios

Fetch a list of audio tracks. Supports search, filtering, and pagination.

get_audio

Fetch a single audio track by ID.

Video Scenes

get_video_scenes

Fetch a paginated list of video scenes. Each scene includes up to 4 preview videos.

get_video_scene

Fetch a single video scene by slug or ID. Returns up to 8 preview videos sorted by popularity.

get_video_scene_videos

Fetch videos from a specific video scene.

AI Models

These tools describe what the account can generate, and what each model accepts. Call them before generating.

list_ai_models

List the AI models available for generation. Only active models are returned.

Each model carries:

• key — the value to pass as model when generating.
• config — what the model can do and which values it allows (textToVideo, imageToVideo, durations, aspectRatios, resolutions, …).
• inputFields — the exact keys to send those values under, inside the generation tool's config. Anything not listed here is ignored and silently falls back to the model's default.
• modes — if non-empty, the model has variants. A mode's own config and inputFields replace the model-level ones, and a mode may override price and generation time too.
• pricePerUnit, generationTime, isFeatured — for weighing cost against speed. Video is charged per second of duration, so a long clip multiplies the price.

get_ai_model

Get a single AI model. Returns the same details as list_ai_models for one model.

Generations

Requires an active Coverr subscription with available credits — generation is not part of the free API tier. See coverr.co/pricing; get_account_status reports what the account currently has.

Generation is asynchronous, so the flow is always the same:

1. list_ai_models — choose a model key and read its inputFields.
2. create_<type>_generation — returns a task id immediately, plus estimatedSeconds.
3. wait_<type>_generation — call repeatedly with that id until it reports done: true.

<type> is one of video, image or audio, giving nine tools in total.

create_video_generation / create_image_generation / create_audio_generation

Start a generation. Spends credits.

If the model has modes, pass the chosen mode key inside config as well.

Returns the created task, including its id and estimatedSeconds. Identical calls made within 2 minutes of each other are deduplicated and return the original task, so an immediate retry after a network error will not double-charge.

Two failures are worth handling explicitly:

• "Not enough credits or free generations" — the account has no active subscription, or not enough credits for this generation. Retrying will not help. Check get_account_status, then subscribe or top up at coverr.co/pricing.
• HTTP 429 — too many generations already running in parallel for this plan. Wait for one to finish; get_account_status reports the plan's parallel limit.

wait_video_generation / wait_image_generation / wait_audio_generation

Wait up to 45 seconds for a generation to finish, then report done.

While done is false the generation is still running and nothing has been lost — call again with the same id. The 45-second ceiling is the MCP client's tool-call timeout, not the model's pace, so expect several calls in a row.

get_video_generation / get_image_generation / get_audio_generation

Read the current status of a generation task once, without waiting.

list_generations

List the account's own generations of one type, newest first, with their results attached. Reading costs no credits.

Returns the standard paged envelope — page, pages, pageSize, total, hits — where each hit is a generation task with its result. Deleted generations are excluded. If any listed task is still running, the response also carries a nextAction naming those ids so they can be followed up with wait_<type>_generation.

Account

get_account_status

Check the account's remaining generation credits, plan tier and parallel generation limit. Useful before generating, or after a generation fails for lack of credits.

Returns tier, subscription status, a credits breakdown (free, plan, extra, total — charged in that order), parallelLimit and an upgradeUrl.

Already have an API key? Configure your MCP client and start fetching videos!