Compeller MCP Server

Compeller MCP-Endpunkt (/api/mcp)

Der Compeller MCP-Endpunkt implementiert das Model Context Protocol als dünnen JSON-RPC-2.0-Wrapper über der bestehenden v1 REST-API. Er ist für Agenten-Integratoren (Claude Desktop, Cursor, benutzerdefinierte MCP-Clients, DigiRAMP) gedacht, die nativ MCP sprechen und nicht rohes HTTP.

• 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 die zur Laufzeit bereitgestellte Menge auf dem deployten Server.
• Verzeichniseinträge: Offizielle MCP-Registry · Smithery · Glama

Authentifizierung

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

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

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

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

1. Bitten Sie den Benutzer, sich anzumelden, Account → API Access zu öffnen, das Token anzuzeigen und es in den geheimen Speicher des Agenten einzufügen.
2. Verwenden Sie den vorhandenen Login-Endpunkt und senden Sie access_token als Bearer-Token. Kein Cookie-Header wird benötigt oder erwartet:

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

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

3. Oder tauschen Sie Anmeldeinformationen über den v1-Auth-Helfer aus, 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":"[email protected]","password":"..."}'

Ein fehlendes oder ungültiges Token wird als Tool-Fehler (isError: true) mit der Nachricht "API token required." / "Invalid API token." angezeigt, nicht als JSON-RPC-Fehler, damit MCP-Clients den Benutzer zur Eingabe von Anmeldeinformationen 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	Listet jedes Tool mit Schema + Beschreibung auf.	200 JSON-RPC-Ergebnis
tools/call	Ruft ein Tool auf. 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 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 vom Typ 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 exakte 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 endgültige 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 ABGEBROCHEN 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 verweist auf GET /api/v1/renderings/{id}/download (unterstützt HTTP Range). Abgeschlossene Compel-/Rendering-Antworten enthalten auch eine react-Übergabe mit dem kostenlosen REACT-Download (https://compeller.ai/download/desktop) und der Learn-More-URL (https://compeller.ai/react), damit Agenten den Benutzern mitteilen können, wie sie den Compel als Live-Performance-System erleben können.

Webhooks (Authentifizierung erforderlich)

Agenten, die sich 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 (rufen Sie dann start_render auf), ohne Polling; 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 (wird 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. 5s). Geheimnisse werden niemals zurückgegeben.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (neu – wird genau einmal zurückgegeben), created_at, updated_at. Das alte Geheimnis wird sofort ungültig.

Unbekannte Ereignisnamen werden stillschweigend auf den Platzhalter * reduziert; dies spiegelt POST /api/v1/webhooks wider, sodass ein Agent niemals ein No-Op-Abonnement erstellt.

Zustellung ist mindestens einmal. Jedes Ereignis wird sofort versucht und, falls Ihr Endpunkt nicht erreichbar ist oder einen Nicht-2xx-Status zurückgibt, mit Backoff wiederholt – 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, deduplizieren Sie also anhand dieser ID. Wenn alle Versuche erschöpft sind, wird das Ereignis verworfen; gleichen Sie über get_compel ab.

register_webhook weist Ziele, die auf interne Infrastruktur verweisen, mit einem Tool-Fehler zurück: Loopback, RFC1918 private Bereiche, 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 für jeden Versuch anhand des aufgelösten DNS erneut ausgeführt, sodass ein Hostname, der nach der Registrierung auf eine blockierte IP umbindet, für diesen Versuch übersprungen wird (protokolliert); bleibt er blockiert, 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 die abonnierten 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 dennoch erfolgreich zurückgegeben – das Ergebnis ist die Nutzlast.

update_webhook akzeptiert beliebige aus 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-stelliges hexadezimales Signaturgeheimnis, gibt es genau einmal zurück und macht das vorherige Geheimnis sofort ungültig. Speichern Sie das neue Geheimnis nach Erhalt vor der nächsten echten Zustellung.

Jede Zustellung wird genau wie der REST-Pfad signiert – siehe 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, fehlendes Tool name, falsche params-Form
-32603	Interner Fehler	Unbehandelte Ausnahme (serverseitig protokolliert)

Fehler auf Tool-Ebene (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 wortgetreu zu sehen und anzuzeigen. Agent-Audio-Entscheidungsbaum: Wenn der Benutzer MP3/WAV/FLAC bereitstellt, verwende upload_media dann create_compel; wenn der Benutzer nur einen Song-/Interpret-String bereitstellt, verwende search_music dann create_compel_from_music; synthetisiere keinen Ton, es sei denn, es wird ausdrücklich nach generiertem Test-Audio gefragt.