MCP tools
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.
create_video_from_song_url
Section titled “create_video_from_song_url”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.
get_video_status
Section titled “get_video_status”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.
list_my_videos
Section titled “list_my_videos”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.
get_pricing
Section titled “get_pricing”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.
get_balance
Section titled “get_balance”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" }Discovering tools
Section titled “Discovering tools”tools/list returns the tools with their full JSON Schemas, titles and annotations. The list does not change while
connected (listChanged: false).
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"}'