Compeller

Compeller MCP-Endpunkt (/api/mcp)

Der Compeller MCP-Endpunkt implementiert das Model Context Protocol als dünnen JSON-RPC-2.0-Wrapper über die bestehende v1-REST-API. Er richtet sich an Agent-Integratoren (Claude Desktop, Cursor, benutzerdefinierte MCP-Clients, DigiRAMP), die nativ MCP statt rohem HTTP sprechen.

• Transport: Streamable HTTP (eine JSON-RPC-Nachricht pro HTTP-POST).
• URL: POST https://compeller.ai/api/mcp
• Protokollversion: 2024-11-05
• Servername / -version: compeller-mcp / siehe initialize-Ergebnis.
• Tool-Vertrag: Die folgende Tool-Liste ist der öffentliche Integrationsvertrag. Verwenden Sie tools/list für den zur Laufzeit beworbenen Satz auf dem bereitgestellten Server.
• Verzeichnislisten: Offizielles MCP-Registry · Smithery · Glama

Authentifizierung

Anonyme (Discovery-)Methoden: initialize, tools/list, ping, notifications/initialized, plus die anonymen Tools get_capabilities, get_pricing, list_styles.

Jedes andere Tool erfordert ein Compeller-API-Token, das direkt in der HTTP-Anfrage übergeben wird, nicht im JSON-RPC-Body. Beide Header funktionieren:

Authorization: Bearer <api-token>
X-API-Token: <api-token>

Tokens werden pro Compeller User ausgestellt (dieselben Tokens, die auch von /api/v1/* verwendet werden). Agenten können eines auf zwei Arten erhalten:

1. Den Benutzer bitten, sich anzumelden, Konto → API-Zugriff zu öffnen, das Token anzuzeigen und es in den Secret-Store des Agenten einzufügen.
2. Den bestehenden Login-Endpunkt verwenden und access_token als Bearer-Token senden. Kein Cookie-Header ist erforderlich oder zu erwarten:

curl -s -X POST https://compeller.ai/api/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"artist@example.com","password":"..."}'

Normale Benutzer erhalten username und access_token. roles erscheint nur für Konten mit Rollen über der Basis-ROLE_COMPELLER; refresh_token und expires_in erscheinen nur, wenn sie nicht leer sind.

3. Oder Anmeldedaten über den v1-Auth-Helper austauschen, der das persistente API-Token zurückgibt:

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

Ein fehlendes oder ungültiges Token erscheint als Tool-Fehler (isError: true) mit der Meldung "API token required." / "Invalid API token.", nicht als JSON-RPC-Fehler, sodass MCP-Clients den Benutzer zur Eingabe von Anmeldedaten auffordern können.

JSON-RPC-Methoden

Methode	Zweck	HTTP-Ergebnis
initialize	Fähigkeits-Handshake. Gibt protocolVersion, serverInfo, capabilities zurück.	200 JSON-RPC-Ergebnis
notifications/initialized	Client-Bestätigung. Kein Antwort-Body.	204
tools/list	Alle Tools mit Schema + Beschreibung auflisten.	200 JSON-RPC-Ergebnis
tools/call	Ein Tool aufrufen. params = {name, arguments}.	200 JSON-RPC-Ergebnis (Tool-Fehler kommen als {isError: true, content: [...]} zurück)
ping	No-op-Keepalive.	200 JSON-RPC result: {}

Unbekannte Methoden geben den JSON-RPC-Fehler -32601 Method not found zurück. Unbekannte Tool-Namen geben -32602 Unknown tool zurück. Ein fehlerhafter JSON-Body gibt -32700 Parse error zurück. Ein fehlender / falscher jsonrpc oder fehlender method gibt -32600 Invalid Request zurück.

Tools

Alle Tools geben einen einzelnen content-Eintrag von type: text zurück, dessen text-Feld eine JSON-formatierte strukturierte Ausgabe ist. Bei einem Fehler wird dieselbe Antwortform mit isError: true und einer menschenlesbaren Fehlermeldung in content[0].text zurückgegeben — niemals als JSON-RPC-error.

Discovery (keine Authentifizierung)

Tool	Eingaben	Rückgaben
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	plans[] mit id, name, monthlyUsd, features[]
list_styles	—	styles[] mit id, name (der id ist der genaue Wert, den create_compel / create_compel_from_music für style akzeptieren)

Medien und Musik (Authentifizierung erforderlich, sofern nicht anders angegeben)

Tool	Erforderlich	Optional	Rückgaben
search_music	query	limit	Öffentliche Musiksuchergebnisse, geeignet für create_compel_from_music. Keine Authentifizierung erforderlich.
upload_media	—	name, mime_type, type	Upload-Anweisungen, die auf POST /api/v1/media verweisen
search_media	—	type (audio/image/video/text), limit (≤100, Standard 20), offset	media[], paging

Compels (Authentifizierung erforderlich)

Tool	Erforderlich	Optional	Rückgaben
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	—	Startet das finale Rendering, wenn der Compel bereit ist; gibt Status und nächste Aktion zurück.
cancel_compel	compel_id	—	Bricht einen laufenden Compel ab (idempotent — bereits-CANCELLED ist erfolgreich); gibt compel_id, status: CANCELLED, stage zurück.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform und aspect_ratio sind durch enum in den Tool-Schemas eingeschränkt (siehe get_capabilities.enums); style-Werte stammen direkt aus list_styles.

Konto (Authentifizierung erforderlich)

Tool	Eingaben	Rückgaben
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — vor einem teuren Rendering aufrufen, um kostenbewusste Entscheidungen zu treffen.

Renderings (Authentifizierung erforderlich)

Tool	Erforderlich	Rückgaben
list_renderings	compel_id	compel_id, renderings[] mit rendering_id, status, download_url
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url zeigt auf GET /api/v1/renderings/{id}/download (unterstützt HTTP Range). Abgeschlossene Compel-/Rendering-Antworten enthalten außerdem eine react-Übergabe mit dem kostenlosen REACT-Download (https://compeller.ai/download/desktop) und einer Learn-more-URL (https://compeller.ai/react), damit Agenten Benutzern mitteilen können, wie sie den Compel als Live-Performance-System erleben können.

Webhooks (Authentifizierung erforderlich)

Agenten, die mit Compeller integrieren, können sich selbst für signierte Push-Benachrichtigungen über Compel-Lebenszyklusereignisse registrieren, anstatt get_compel abzufragen. Abonnieren Sie compel.ready, um den Moment zu erfahren, in dem ein Compel renderbar ist (dann start_render aufrufen), ohne zu pollen; compel.completed / compel.failed sind die terminalen Ereignisse.

Tool	Erforderlich	Optional	Rückgaben
register_webhook	url (HTTPS, ≤2048 Zeichen)	events[] — Standard ist ["*"]; bekannte Werte: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (genau einmal zurückgegeben), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Geheimnisse werden von diesem Tool niemals zurückgegeben.
update_webhook	webhook_id	url, events[], active — mindestens eines	webhook_id, url, events, active, created_at, updated_at. Geheimnisse werden niemals zurückgegeben; verwenden Sie dafür rotate_webhook_secret.
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?. Synchron — das Tool wartet auf die Antwort des Integrator-Endpunkts (max. 5 s). Geheimnisse werden niemals zurückgegeben.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (neu — genau einmal zurückgegeben), created_at, updated_at. Das alte Geheimnis wird sofort ungültig.

Unbekannte Ereignisnamen fallen stillschweigend auf den Wildcard * zurück; dies spiegelt POST /api/v1/webhooks wider, sodass ein Agent niemals ein No-op-Abonnement erstellt.

Die Zustellung erfolgt mindestens einmal. Jedes Ereignis wird sofort versucht und, falls Ihr Endpunkt nicht erreichbar ist oder einen Nicht-2xx-Status zurückgibt, mit Backoff erneut versucht — bis zu 6 Versuche insgesamt (sofort, dann nach 1 Min., 5 Min., 30 Min., 2 Std., 6 Std.). Jeder Versuch trägt dieselbe X-Compeller-Event-Id und einen byte-identischen signierten Body, sodass anhand dieser ID dedupliziert werden kann. Wenn alle Versuche erschöpft sind, wird das Ereignis verworfen; Abgleich über get_compel.

register_webhook lehnt Ziele ab, die auf interne Infrastruktur zeigen, mit einem Tool-Fehler: Loopback, RFC1918-Privatbereiche, Link-Local (einschließlich Cloud-Metadaten-IPs wie 169.254.169.254), IPv6-ULA, CGNAT, Multicast, die nicht spezifizierte Adresse und Hostnamen, die auf .local / .internal / .localhost enden. Dieselbe Prüfung wird bei der Zustellung bei jedem Versuch gegen aufgelöstes DNS erneut ausgeführt. Wenn ein Hostname nach der Registrierung auf eine blockierte IP umbindet, wird dieser Versuch übersprungen (protokolliert); wenn er blockiert bleibt, verbraucht er einfach sein Wiederholungsbudget und wird dann verworfen.

test_webhook_delivery sendet ein synthetisches webhook.test-Ereignis mit einer HMAC-SHA256-Signatur und wartet synchron auf die Antwort des Endpunkts. Es ignoriert das abonnierte events des Endpunkts (wird immer zugestellt) und wendet dieselbe URL-Sicherheitsprüfung wie bei echten Zustellungen an. Eine Nicht-2xx-Antwort wird als delivered: false angezeigt, aber der MCP-Aufruf selbst wird trotzdem erfolgreich zurückgegeben — das Ergebnis ist die Nutzlast.

update_webhook akzeptiert beliebige von url, events, active (mindestens eines). Die URL-Validierung spiegelt register_webhook wider. Geheimnisse werden von diesem Tool niemals zurückgegeben.

rotate_webhook_secret erstellt ein neues 64-Zeichen-Hex-Signaturgeheimnis, gibt es genau einmal zurück und macht das vorherige Geheimnis sofort ungültig. Speichern Sie das neue Geheimnis beim Empfang, bevor die nächste echte Zustellung erfolgt.

Jede Zustellung ist genau wie der REST-Pfad signiert — siehe den Abschnitt Webhooks von openapi.yaml für den vollständigen Envelope- und Header-Vertrag.

Beispielsitzung

# 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 <api-token>' \
  -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"]
          }
        }
      }'

Die Antwort auf Schritt 3 ist ein JSON-RPC-result, das content[0].text enthält — selbst ein JSON-Dokument mit webhook_id, secret usw. Speichern Sie secret sofort; der Server wird es nicht erneut zurückgeben.

Fehlercodes

Code	Bedeutung	Ursache
-32700	Parse-Fehler	Body ist kein gültiges JSON
-32600	Ungültige Anfrage	Fehlender/falscher jsonrpc, fehlender method, leerer Body
-32601	Methode nicht gefunden	Unbekannte JSON-RPC-Methode
-32602	Ungültige Parameter	Unbekanntes Tool, fehlende Tool-name, falsche params-Form
-32603	Interner Fehler	Unbehandelte Ausnahme (serverseitig protokolliert)

Tool-Ebene-Fehler (Validierung, Authentifizierung, nicht gefunden) werden innerhalb einer erfolgreichen JSON-RPC-Antwort als {result: {isError: true, content: [{type: "text", text: "..."}]}} zurückgegeben. Dies entspricht der MCP-Konvention — es ermöglicht dem LLM, den Fehler wörtlich zu sehen und anzuzeigen. Agent-Audio-Entscheidungsbaum: Wenn der Benutzer MP3/WAV/FLAC bereitstellt, verwende upload_media und dann create_compel; wenn der Benutzer nur eine Song-/Künstler-Zeichenkette bereitstellt, verwende search_music und dann create_compel_from_music; synthetisiere keinen Ton, es sei denn, ausdrücklich um generiertes Testaudio gebeten wird.