Skip to content

MCP tools

View as Markdown

Every tool returns its result twice: as structuredContent (a JSON object) and as content[0].text (the same object as a JSON string) for clients that only read text. Errors come back with isError: true and the error body in the same places.

The outputs are the same objects the REST API returns, so the video object and song object docs apply.

Imports a song and starts a music video in one call, or starts a video from a song imported earlier. Costs credits.

Scopes: videos:write, plus songs:write when song_url is used. Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true.

Argument Type Required Description
rights_attestation boolean yes Must be true: the user owns the song or has the rights to use it.
song_url string one of Link to the audio: direct .mp3, .m4a, .wav, or a Google Drive or Dropbox share link. Suno links are not supported.
song_id string one of Song id from an earlier call, instead of song_url.
tier preview, standard, plus, premium no Default preview.
style string no World, place and look of the video.
character string no The original AI lead singer.
aspect 16:9, 9:16 no Frame shape.
title string no Title of the video.

The server sends the current rights_version for you.

Example call:

{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "create_video_from_song_url",
"arguments": {
"song_url": "https://example.com/my-song.mp3",
"rights_attestation": true,
"tier": "preview",
"aspect": "9:16",
"style": "desert highway at golden hour"
}
}
}

Result (structuredContent): the video object plus song_id and a next hint.

{
"id": "f1e2d3c4-b5a6-4789-8abc-def012345678",
"status": "queued",
"tier": "preview",
"title": "My Song",
"aspect": "9:16",
"created_at": "2026-11-22T09:16:40.000Z",
"progress": null,
"cost": { "credits_reserved": 100, "credits_charged": 0, "credits_refunded": 0, "usd": 5 },
"result": null,
"studio_url": "https://studio.clipbeat.app/",
"song_id": "8c5d2f9e-2a51-4f0e-9a43-1f4f3b0d6a21",
"next": "Poll get_video_status every 30 to 60 seconds."
}

If the song was imported but is still being processed, the result is an error with error: "song_processing", the song_id, and next: "Call create_video_from_song_url again with this song_id in about 30 seconds." Call again with song_id (not song_url) so the song is not imported twice.

Status, progress, cost and, when completed, the download link of a video.

Scope: videos:read. Annotations: readOnlyHint: true.

Argument Type Required Description
video_id string yes The id returned by create_video_from_song_url.
{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "get_video_status", "arguments": { "video_id": "f1e2d3c4-b5a6-4789-8abc-def012345678" } } }

Result: the video object. When status is completed, share result.video_url with the user. The link expires after result.expires_in_sec seconds; call the tool again for a fresh one.

The account’s latest videos with their status, newest first.

Scope: videos:read. Annotations: readOnlyHint: true.

Argument Type Required Description
limit integer, 1 to 50 no Default 20.

Result: { "videos": [ ... ] }, an array of video objects.

Price per tier in USD and credits. Pass song_id for prices by song length.

Scope: account:read. Annotations: readOnlyHint: true.

Argument Type Required Description
song_id string no A song of this account.

Result: the same object as GET /v1/pricing: currency, credits_per_usd, tiers (each with tier, name, usd, credits, available, lip_sync, outcome), topup_url and note.

The account’s credit balance and the link to add credits.

Scope: account:read. Annotations: readOnlyHint: true. No arguments.

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "get_balance", "arguments": {} } }

Result:

{ "credits": 400, "usd": 20, "credits_per_usd": 20, "topup_url": "https://studio.clipbeat.app/credits" }

tools/list returns the tools with their full JSON Schemas, titles and annotations. The list does not change while connected (listChanged: false).

Terminal window
curl -s https://api.clipbeat.app/mcp \
-H "Authorization: Bearer $CLIPBEAT_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'