Compeller

Point de terminaison MCP Compeller (/api/mcp)

Le point de terminaison MCP Compeller implémente le Model Context Protocol sous la forme d'une fine couche JSON-RPC 2.0 au-dessus de l'API REST v1 existante. Il est destiné aux intégrateurs d'agents (Claude Desktop, Cursor, clients MCP personnalisés, DigiRAMP) qui communiquent nativement en MCP plutôt qu'en HTTP brut.

• Transport : HTTP streamable (un seul message JSON-RPC par POST HTTP).
• URL : POST https://compeller.ai/api/mcp
• Version du protocole : 2024-11-05
• Nom / version du serveur : compeller-mcp / voir le résultat de initialize.
• Contrat d'outil : La liste d'outils ci-dessous constitue le contrat d'intégration public. Utilisez tools/list pour l'ensemble annoncé à l'exécution sur le serveur déployé.
• Annuaires : Registre MCP officiel · Smithery · Glama

Authentification

Méthodes anonymes (découverte) : initialize, tools/list, ping, notifications/initialized, ainsi que les outils anonymes get_capabilities, get_pricing, list_styles.

Tous les autres outils nécessitent un jeton API Compeller transmis via la requête HTTP elle-même, et non dans le corps JSON-RPC. L'un ou l'autre des en-têtes fonctionne :

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

Les jetons sont émis par User Compeller (les mêmes jetons que ceux utilisés par /api/v1/*). Les agents peuvent en obtenir un de deux manières :

1. Demander à l'utilisateur de se connecter, d'ouvrir Compte → Accès API, de révéler le jeton et de le coller dans le magasin de secrets de l'agent.
2. Utiliser le point de terminaison de connexion existant et envoyer access_token comme jeton porteur. Aucun en-tête Cookie n'est nécessaire ni attendu :

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

Les utilisateurs normaux reçoivent username et access_token. roles n'apparaît que pour les comptes ayant des rôles au-delà du ROLE_COMPELLER de base ; refresh_token et expires_in n'apparaissent que s'ils ne sont pas vides.

3. Ou échanger des identifiants via l'assistant d'authentification v1, qui renvoie le jeton API persistant :

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

Un jeton manquant ou invalide se manifeste sous la forme d'une erreur d'outil (isError: true) avec le message "API token required." / "Invalid API token.", et non comme une erreur JSON-RPC, afin que les clients MCP puissent inviter l'utilisateur à fournir des identifiants.

Méthodes JSON-RPC

Méthode	Objectif	Résultat HTTP
initialize	Négociation de capacités. Renvoie protocolVersion, serverInfo, capabilities.	200 Résultat JSON-RPC
notifications/initialized	Accusé de réception du client. Pas de corps de réponse.	204
tools/list	Lister tous les outils avec schéma + description.	200 Résultat JSON-RPC
tools/call	Invoquer un outil. params = {name, arguments}.	200 Résultat JSON-RPC (les erreurs d'outil sont renvoyées comme {isError: true, content: [...]})
ping	Maintien de session sans opération.	200 JSON-RPC result: {}

Les méthodes inconnues renvoient une erreur JSON-RPC -32601 Method not found. Les noms d'outils inconnus renvoient -32602 Unknown tool. Un corps JSON mal formé renvoie -32700 Parse error. Un jsonrpc manquant/incorrect ou un method manquant renvoie -32600 Invalid Request.

Outils

Tous les outils renvoient une seule entrée content de type: text dont le champ text est une sortie structurée au format JSON. En cas d'échec, la même forme de réponse est renvoyée avec isError: true et un message d'erreur lisible dans content[0].text — jamais comme une error JSON-RPC.

Découverte (sans authentification)

Outil	Entrées	Renvoie
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	plans[] avec id, name, monthlyUsd, features[]
list_styles	—	styles[] avec id, name (le id est la valeur exacte que create_compel / create_compel_from_music acceptent pour style)

Médias et musique (authentification requise sauf indication contraire)

Outil	Requis	Optionnel	Renvoie
search_music	query	limit	Résultats de recherche musicale publique adaptés à create_compel_from_music. Aucune authentification requise.
upload_media	—	name, mime_type, type	Instructions de téléversement pointant vers POST /api/v1/media
search_media	—	type (audio/image/video/text), limit (≤100, défaut 20), offset	media[], paging

Compels (authentification requise)

Outil	Requis	Optionnel	Renvoie
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	—	Démarre le rendu final lorsque le compel est prêt ; renvoie le statut et l'action suivante.
cancel_compel	compel_id	—	Annule un compel en cours (idempotent — un statut déjà ANNULÉ réussit) ; renvoie compel_id, status: CANCELLED, stage.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform et aspect_ratio sont contraints par enum dans les schémas d'outils (voir get_capabilities.enums) ; les valeurs style proviennent directement de list_styles.

Compte (authentification requise)

Outil	Entrées	Renvoie
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — à appeler avant un rendu coûteux pour prendre des décisions éclairées par les coûts.

Rendus (authentification requise)

Outil	Requis	Renvoie
list_renderings	compel_id	compel_id, renderings[] avec rendering_id, status, download_url
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url pointe vers GET /api/v1/renderings/{id}/download (prend en charge HTTP Range). Les réponses de compel/rendu terminées incluent également un transfert react avec le téléchargement gratuit REACT (https://compeller.ai/download/desktop) et l'URL pour en savoir plus (https://compeller.ai/react) afin que les agents puissent indiquer aux utilisateurs comment expérimenter le compel en tant que système de performance en direct.

Webhooks (authentification requise)

Les agents qui s'intègrent à Compeller peuvent s'auto-enregistrer pour recevoir des notifications push signées des événements du cycle de vie des compels au lieu d'interroger get_compel. Abonnez-vous à compel.ready pour savoir à quel moment un compel est prêt à être rendu (puis appelez start_render) sans interrogation ; compel.completed / compel.failed sont les événements terminaux.

Outil	Requis	Optionnel	Renvoie
register_webhook	url (HTTPS, ≤2048 caractères)	events[] — par défaut ["*"] ; valeurs connues : *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (renvoyé exactement une fois), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Les secrets ne sont jamais renvoyés par cet outil.
update_webhook	webhook_id	url, events[], active — au moins un	webhook_id, url, events, active, created_at, updated_at. Les secrets ne sont jamais renvoyés ; utilisez rotate_webhook_secret pour cela.
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?. Synchrone — l'outil attend la réponse du point de terminaison de l'intégrateur (max 5s). Les secrets ne sont jamais renvoyés.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (nouveau — renvoyé exactement une fois), created_at, updated_at. L'ancien secret est immédiatement invalidé.

Les noms d'événements inconnus sont réduits silencieusement au joker * ; cela reflète POST /api/v1/webhooks afin qu'un agent ne crée jamais un abonnement sans effet.

La livraison est de type au-moins-une-fois. Chaque événement est tenté immédiatement et, si votre point de terminaison est injoignable ou renvoie un code autre que 2xx, une nouvelle tentative est effectuée avec un délai exponentiel — jusqu'à 6 tentatives au total (immédiatement, puis après 1 min, 5 min, 30 min, 2 h, 6 h). Chaque tentative porte le même X-Compeller-Event-Id et un corps signé identique octet par octet, donc dédupliquez sur cet identifiant. Si toutes les tentatives sont épuisées, l'événement est abandonné ; réconciliez via get_compel.

register_webhook rejette les destinations pointant vers une infrastructure interne avec une erreur d'outil : boucle locale, plages privées RFC1918, lien local (y compris les IP de métadonnées cloud comme 169.254.169.254), ULA IPv6, CGNAT, multidiffusion, l'adresse non spécifiée et les noms d'hôte se terminant par .local / .internal / .localhost. La même vérification est réexécutée au moment de la livraison par rapport au DNS résolu à chaque tentative, de sorte qu'un nom d'hôte qui se relie à une IP bloquée après l'enregistrement est ignoré pour cette tentative (journalisé) ; s'il reste bloqué, il consomme simplement son budget de nouvelles tentatives et est ensuite abandonné.

test_webhook_delivery envoie un événement synthétique webhook.test avec une signature HMAC-SHA256 et attend de manière synchrone la réponse du point de terminaison. Il ignore le events souscrit par le point de terminaison (toujours livré) et applique la même vérification de sécurité d'URL que les livraisons réelles. Une réponse autre que 2xx est signalée comme delivered: false mais l'appel MCP lui-même renvoie toujours un succès — le résultat est la charge utile.

update_webhook accepte l'un quelconque de url, events, active (au moins un). La validation d'URL reflète register_webhook. Les secrets ne sont jamais renvoyés par cet outil.

rotate_webhook_secret crée un nouveau secret de signature hexadécimal de 64 caractères, le renvoie exactement une fois et invalide immédiatement le secret précédent. Stockez le nouveau secret dès réception avant la prochaine livraison réelle.

Chaque livraison est signée exactement comme le chemin REST — voir la section Webhooks de openapi.yaml pour le contrat complet d'enveloppe et d'en-tête.

Exemple de 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 <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"]
          }
        }
      }'

La réponse à l'étape 3 est un result JSON-RPC contenant content[0].text — lui-même un document JSON avec webhook_id, secret, etc. Stockez secret immédiatement ; le serveur ne le renverra plus.

Codes d'erreur

Code	Signification	Cause
-32700	Erreur d'analyse	Le corps n'est pas un JSON valide
-32600	Requête invalide	jsonrpc manquant/incorrect, method manquant, corps vide
-32601	Méthode non trouvée	Méthode JSON-RPC inconnue
-32602	Paramètres invalides	Outil inconnu, name d'outil manquant, forme params incorrecte
-32603	Erreur interne	Exception non gérée (journalisée côté serveur)

Les échecs au niveau de l'outil (validation, authentification, non trouvé) sont renvoyés à l'intérieur d'une réponse JSON-RPC réussie en tant que {result: {isError: true, content: [{type: "text", text: "..."}]}}. C'est une convention MCP — cela permet au LLM de voir et de présenter l'échec tel quel. Arbre de décision audio de l'agent : si l'utilisateur fournit un fichier MP3/WAV/FLAC, utilisez upload_media puis create_compel ; si l'utilisateur fournit uniquement une chaîne de caractères de type chanson/artiste, utilisez search_music puis create_compel_from_music ; ne synthétisez pas de tonalité sauf demande explicite de génération d'un fichier audio de test.