Compeller

Point de terminaison MCP Compeller (/api/mcp)

Le point de terminaison MCP Compeller implémente le Model Context Protocol comme une fine surcouche JSON-RPC 2.0 sur l'API REST v1 existante. Il est destiné aux intégrateurs d'agents (Claude Desktop, Cursor, clients MCP personnalisés, DigiRAMP) qui parlent nativement MCP plutôt que 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 initialize.
• Contrat d'outils : 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, plus les outils anonymes get_capabilities, get_pricing, list_styles.

Chaque autre outil nécessite un jeton API Compeller transmis sur la requête HTTP elle-même, pas dans le corps JSON-RPC. L'un ou l'autre en-tête fonctionne :

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

Les jetons sont émis par User Compeller (les mêmes jetons 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 coffre-fort 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":"artist@example.com","password":"..."}'

Les utilisateurs normaux reçoivent username et access_token. roles n'apparaît que pour les comptes avec des rôles au-delà du ROLE_COMPELLER de base ; refresh_token et expires_in n'apparaissent que lorsqu'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":"artist@example.com","password":"..."}'

Un jeton manquant ou invalide apparaît comme 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 demander les identifiants à l'utilisateur.

Méthodes JSON-RPC

Méthode	Objectif	Résultat HTTP
initialize	Poignée de main des capacités. Renvoie protocolVersion, serverInfo, capabilities.	Résultat JSON-RPC 200
notifications/initialized	Accusé de réception du client. Aucun corps de réponse.	204
tools/list	Lister chaque outil avec schéma + description.	Résultat JSON-RPC 200
tools/call	Invoquer un outil. params = {name, arguments}.	Résultat JSON-RPC 200 (les erreurs d'outil reviennent comme {isError: true, content: [...]})
ping	Maintien en vie sans opération.	result: {} JSON-RPC 200

Les méthodes inconnues renvoient l'erreur JSON-RPC -32601 Method not found. Les noms d'outils inconnus renvoient -32602 Unknown tool. Un corps JSON malformé 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 par l'humain dans content[0].text — jamais comme un 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 mention 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 la prochaine action.
cancel_compel	compel_id	—	Annule un compel en cours (idempotent — un déjà-ANNULE 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 sur les coûts.

Rendu (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 REACT gratuit (https://compeller.ai/download/desktop) et l'URL d'apprentissage (https://compeller.ai/react) afin que les agents puissent indiquer aux utilisateurs comment expérimenter le compel comme système de performance en direct.

Webhooks (authentification requise)

Les agents qui s'intègrent à Compeller peuvent s'auto-enregistrer pour 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 connaître le moment où un compel est rendable (puis appelez start_render) sans interroger ; 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 5 s). 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 invalidé immédiatement.

Les noms d'événements inconnus se réduisent silencieusement au caractère générique * ; cela reflète POST /api/v1/webhooks afin qu'un agent ne crée jamais d'abonnement sans effet.

La livraison est au moins une fois. Chaque événement est tenté immédiatement et, si votre point de terminaison est inaccessible ou renvoie un non-2xx, relancé avec backoff — 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é octet pour octet identique, 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 qui pointent vers l'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, multicast, 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 contre le DNS résolu à chaque tentative, donc 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 puis est abandonné.

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

update_webhook accepte l'un 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 génère 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 à la 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 l'enveloppe complète et le contrat d'en-têtes.

Session d'exemple

# 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 pas.

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 des outils (validation, authentification, non trouvé) sont renvoyés dans une réponse JSON-RPC réussie comme {result: {isError: true, content: [{type: "text", text: "..."}]}}. C'est par convention MCP — cela permet au LLM de voir et de signaler l'échec textuellement. Arbre de décision audio pour 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 avec le nom d'une chanson ou d'un artiste, utilisez search_music puis create_compel_from_music ; ne synthétisez pas de tonalité sauf si une demande explicite est faite pour un audio de test généré.