# MCP server

> Clipbeat's remote Model Context Protocol server lets an AI assistant make a music video for its user.

Source: https://docs.clipbeat.app/mcp/

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard that lets AI assistants call
tools. Clipbeat runs a **remote MCP server**, so an assistant that supports MCP can import a song, check prices, start a
video and hand back the download link, all inside the conversation.

## Server

| | |
| --- | --- |
| URL | `https://api.clipbeat.app/mcp` |
| Transport | Streamable HTTP. Each message is a `POST`; responses are plain JSON (no server-sent event stream). |
| Sessions | Stateless. No `Mcp-Session-Id`, nothing to clean up. `GET` and `DELETE` return `405`. |
| Protocol versions | `2025-06-18` (preferred), `2025-03-26`, `2024-11-05` |
| Auth today | `Authorization: Bearer cb_live_...` API key. See [MCP authentication](https://docs.clipbeat.app/mcp/authentication/). |
| Capabilities | `tools`. No resources or prompts (`resources/list` and `prompts/list` return empty lists). |
| Batching | JSON-RPC batches (arrays) are accepted. |

## Tools

| Tool | Read only | What it does |
| --- | --- | --- |
| [`create_video_from_song_url`](https://docs.clipbeat.app/mcp/tools/#create_video_from_song_url) | no | Import a song (or reuse one) and start a video. Costs credits. |
| [`get_video_status`](https://docs.clipbeat.app/mcp/tools/#get_video_status) | yes | Status, progress, cost and the download link when done. |
| [`list_my_videos`](https://docs.clipbeat.app/mcp/tools/#list_my_videos) | yes | The account's latest videos. |
| [`get_pricing`](https://docs.clipbeat.app/mcp/tools/#get_pricing) | yes | Price per tier, optionally for a specific song. |
| [`get_balance`](https://docs.clipbeat.app/mcp/tools/#get_balance) | yes | Credit balance and the link to add credits. |

## How an assistant uses it

The server sends these instructions to the client when it connects:

> Clipbeat turns a song into a music video for the signed-in account. Typical flow: get_pricing, then
> create_video_from_song_url (start with tier preview), then poll get_video_status every 30 to 60 seconds until status
> is completed and share result.video_url. Payment comes from the account's credit balance; on insufficient_credits
> give the user topup_url (never ask for card details). The lead is always an original AI character; do not describe
> real or famous people.

A typical conversation:

1. The user shares a song link and asks for a video.
2. The assistant calls `get_pricing` and tells the user the price.
3. The user confirms they own the song. The assistant calls `create_video_from_song_url` with
   `rights_attestation: true` and `tier: "preview"`.
4. The assistant calls `get_video_status` every 30 to 60 seconds and shares `result.video_url` when the status is
   `completed`.

## MCP or REST?

| | MCP server | REST API |
| --- | --- | --- |
| Best for | AI assistants and agent frameworks | Your own code, automations, backends |
| Song import and video start | One tool call | Two requests (`POST /v1/songs`, then `POST /v1/videos`) |
| Same prices, limits and rules | yes | yes |

Both use the same account, credits, [rate limits](https://docs.clipbeat.app/rate-limits/) and [content policy](https://docs.clipbeat.app/content-policy/).

## Next

- [Tools reference](https://docs.clipbeat.app/mcp/tools/): inputs, outputs and example calls.
- [Connect a client](https://docs.clipbeat.app/mcp/clients/): Claude, Cursor, VS Code, ChatGPT, n8n and others.
