# MCP tools

> Input schema, output and example call for each of the five Clipbeat MCP tools.

Source: https://docs.clipbeat.app/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](https://docs.clipbeat.app/errors/) in the same places.

The outputs are the same objects the REST API returns, so the [video object](https://docs.clipbeat.app/concepts/video-jobs/#the-video-object)
and [song object](https://docs.clipbeat.app/concepts/songs/#the-song-object) docs apply.

## `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:

```json
{
  "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](https://docs.clipbeat.app/concepts/video-jobs/#the-video-object) plus `song_id` and a `next` hint.

```json
{
  "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`

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`. |

```json
{ "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](https://docs.clipbeat.app/concepts/video-jobs/#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`

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`

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`](https://docs.clipbeat.app/pricing/#reading-prices-in-code): `currency`, `credits_per_usd`,
`tiers` (each with `tier`, `name`, `usd`, `credits`, `available`, `lip_sync`, `outcome`), `topup_url` and `note`.

## `get_balance`

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

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

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

Result:

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

## Discovering tools

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

```bash
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"}'
```
