Compeller

Compeller MCP endpoint (/api/mcp)

The Compeller MCP endpoint implements the Model Context Protocol as a thin JSON-RPC 2.0 wrapper over the existing v1 REST API. It is intended for agent integrators (Claude Desktop, Cursor, custom MCP clients, DigiRAMP) that speak MCP natively rather than raw HTTP.

• Transport: Streamable HTTP (single JSON-RPC message per HTTP POST).

• URL: POST https://compeller.ai/api/mcp

• Protocol version: 2024-11-05

• Server name / version: compeller-mcp / see initialize result.

• Tool contract: The tool list below is the public integration contract. Use tools/list for the runtime-advertised set on the deployed server.

• Directory listings: Official MCP Registry · Smithery · Glama

Authentication

Anonymous (discovery) methods: initialize, tools/list, ping, notifications/initialized, plus the anonymous tools get_capabilities, get_pricing, list_styles.

Every other tool requires a Compeller API token passed on the HTTP request itself, not inside the JSON-RPC body. Either header works:

Authorization: Bearer 
X-API-Token: 

Tokens are issued per Compeller User (same tokens used by /api/v1/*). Agents can obtain one in either of two ways:

• Ask the user to log in, open Account → API Access, reveal the token, and paste it into the agent's secret store.

• Use the existing login endpoint and send access_token as the bearer token. No Cookie header is needed or expected:

curl -s -X POST https://compeller.ai/api/login \
 -H 'Content-Type: application/json' \
 -d '{"username":"[email protected]","password":"..."}'

Normal users receive username and access_token. roles appears only for accounts with roles beyond baseline ROLE_COMPELLER; refresh_token and expires_in appear only when non-empty.

• Or exchange credentials through the v1 auth helper, which returns the persistent API token:

curl -s -X POST https://compeller.ai/api/v1/auth/token \
 -H 'Content-Type: application/json' \
 -d '{"email":"[email protected]","password":"..."}'

A missing or invalid token surfaces as a tool error (isError: true) with message "API token required." / "Invalid API token.", not as a JSON-RPC error, so MCP clients can prompt the user for credentials.

JSON-RPC methods

Method Purpose HTTP result initialize Capability handshake. Returns protocolVersion, serverInfo, capabilities. 200 JSON-RPC result notifications/initialized Client acknowledgement. No response body. 204 tools/list List every tool with schema + description. 200 JSON-RPC result tools/call Invoke a tool. params = {name, arguments}. 200 JSON-RPC result (tool errors come back as {isError: true, content: [...]}) ping No-op keepalive. 200 JSON-RPC result: {}

Unknown methods return JSON-RPC error -32601 Method not found. Unknown tool names return -32602 Unknown tool. A malformed JSON body returns -32700 Parse error. A missing / wrong jsonrpc or missing method returns -32600 Invalid Request.

Tools

All tools return a single content entry of type: text whose text field is JSON-formatted structured output. On failure, the same response shape is returned with isError: true and a human-readable error message in content[0].text — never as a JSON-RPC error.

Discovery (no auth)

Tool Inputs Returns get_capabilities — productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits get_pricing — plans[] with id, name, monthlyUsd, features[] list_styles — styles[] with id, name (the id is the exact value create_compel / create_compel_from_music accept for style)

Media and music (auth required unless noted)

Tool Required Optional Returns search_music query limit Public music search results suitable for create_compel_from_music. No auth required. upload_media — name, mime_type, type Upload instructions pointing at POST /api/v1/media search_media — type (audio/image/video/text), limit (≤100, default 20), offset media[], paging

Compels (auth required)

Tool Required Optional Returns create_compel_from_music track_id title, style, target_platform, aspect_ratio, artist_context compel_id, status, next_action create_compel title, primary_media_id style, target_platform, aspect_ratio, artist_context compel_id, status: QUEUED get_compel compel_id — compel_id, title, status, progress_percent, stage, rendering_id, created_at, human_url, next_action start_render compel_id — Starts final rendering when the compel is ready; returns status and next action. cancel_compel compel_id — Cancels an in-progress compel (idempotent — already-CANCELLED succeeds); returns compel_id, status: CANCELLED, stage. list_compels — limit (≤100), offset compels[], paging search_compels query limit compels[], count

style, target_platform, and aspect_ratio are constrained by enum in the tool schemas (see get_capabilities.enums); style values come straight from list_styles.

Account (auth required)

Tool Inputs Returns get_account_credits — plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — call before an expensive render to make cost-aware decisions.

Renderings (auth required)

Tool Required Returns list_renderings compel_id compel_id, renderings[] with rendering_id, status, download_url get_rendering rendering_id rendering_id, compel_id, status, download_url

download_url points at GET /api/v1/renderings/{id}/download (supports HTTP Range). Completed compel/rendering responses also include a react handoff with the free REACT download (https://compeller.ai/download/desktop) and learn-more URL (https://compeller.ai/react) so agents can tell users how to experience the compel as a live performance system.

Webhooks (auth required)

Agents that integrate with Compeller can self-register for signed push notifications of compel lifecycle events instead of polling get_compel. Subscribe to compel.ready to learn the moment a compel is renderable (then call start_render) without polling; compel.completed / compel.failed are the terminal events.

Tool Required Optional Returns register_webhook url (HTTPS, ≤2048 chars) events[] — defaults to ["*"]; known values: *, compel.ready, compel.completed, compel.failed webhook_id, url, events, secret (returned exactly once), active, created_at list_webhooks — — webhooks[] — webhook_id, url, events, active, created_at, updated_at. Secrets are never returned by this tool. update_webhook webhook_id url, events[], active — at least one webhook_id, url, events, active, created_at, updated_at. Secrets are never returned; use rotate_webhook_secret for that. delete_webhook webhook_id — webhook_id, deleted: true test_webhook_delivery webhook_id — webhook_id, event_id, event_type: "webhook.test", delivered, response_status?, response_body_preview?, latency_ms, error?. Synchronous — the tool waits for the integrator's endpoint to respond (max 5s). Secrets are never returned. rotate_webhook_secret webhook_id — webhook_id, url, events, active, secret (new — returned exactly once), created_at, updated_at. Old secret is invalidated immediately.

Unknown event names collapse silently to the wildcard *; this mirrors POST /api/v1/webhooks so an agent never creates a no-op subscription.

Delivery is at-least-once. Each event is attempted immediately and, if your endpoint is unreachable or returns a non-2xx, retried with backoff — up to 6 attempts total (immediately, then after 1m, 5m, 30m, 2h, 6h). Every attempt carries the same X-Compeller-Event-Id and a byte-identical signed body, so dedupe on that id. If all attempts are exhausted the event is dropped; reconcile via get_compel.

register_webhook rejects destinations that point at internal infrastructure with a tool error: loopback, RFC1918 private ranges, link-local (including cloud metadata IPs like 169.254.169.254), IPv6 ULA, CGNAT, multicast, the unspecified address, and hostnames ending in .local / .internal / .localhost. The same check re-runs at delivery time against resolved DNS on every attempt, so a hostname that rebinds to a blocked IP after registration is skipped for that attempt (logged); if it stays blocked it simply consumes its retry budget and is then dropped.

test_webhook_delivery sends a synthetic webhook.test event with an HMAC-SHA256 signature and waits synchronously for the endpoint's response. It ignores the endpoint's subscribed events (always delivered) and applies the same URL safety check as real deliveries. A non-2xx response is surfaced as delivered: false but the MCP call itself still returns successfully — the result is the payload.

update_webhook accepts any of url, events, active (at least one). URL validation mirrors register_webhook. Secrets are never returned by this tool.

rotate_webhook_secret mints a fresh 64-char hex signing secret, returns it exactly once, and invalidates the previous secret immediately. Store the new secret on receipt before the next real delivery.

Every delivery is signed exactly like the REST path — see openapi.yaml 's Webhooks section for the full envelope and header contract.

Example session

# 1. Handshake
curl -s https://compeller.ai/api/mcp \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# 2. List tools
curl -s https://compeller.ai/api/mcp \
 -H 'Content-Type: application/json' \
 -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. Register a webhook (auth required)
curl -s https://compeller.ai/api/mcp \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer ' \
 -d '{
 "jsonrpc":"2.0",
 "id":3,
 "method":"tools/call",
 "params":{
 "name":"register_webhook",
 "arguments":{
 "url":"https://hooks.my-agent.io/compeller",
 "events":["compel.completed","compel.failed"]
 }
 }
 }'

The response to step 3 is a JSON-RPC result containing content[0].text — itself a JSON document with webhook_id, secret, etc. Store secret immediately; the server will not return it again.

Error codes

Code Meaning Cause -32700 Parse error Body is not valid JSON -32600 Invalid Request Missing/wrong jsonrpc, missing method, empty body -32601 Method not found Unknown JSON-RPC method -32602 Invalid params Unknown tool, missing tool name, bad params shape -32603 Internal error Unhandled exception (logged server-side)

Tool-level failures (validation, auth, not-found) are returned inside a successful JSON-RPC response as {result: {isError: true, content: [{type: "text", text: "..."}]}}. This is by MCP convention — it lets the LLM see and surface the failure verbatim.

Agent audio decision tree: if the user provides MP3/WAV/FLAC, use upload_media then create_compel; if the user provides only a song/artist string, use search_music then create_compel_from_music; do not synthesize a tone unless explicitly asked for generated test audio.