Compeller

Endpoint MCP de Compeller (/api/mcp)

El endpoint MCP de Compeller implementa el Protocolo de Contexto de Modelo como un envoltorio ligero de JSON-RPC 2.0 sobre la API REST v1 existente. Está pensado para integradores de agentes (Claude Desktop, Cursor, clientes MCP personalizados, DigiRAMP) que hablan MCP de forma nativa en lugar de HTTP crudo.

• Transporte: HTTP Streamable (un mensaje JSON-RPC por POST HTTP).
• URL: POST https://compeller.ai/api/mcp
• Versión del protocolo: 2024-11-05
• Nombre/versión del servidor: compeller-mcp / ver resultado de initialize.
• Contrato de herramientas: La lista de herramientas siguiente es el contrato público de integración. Usa tools/list para el conjunto anunciado en tiempo de ejecución en el servidor desplegado.
• Listados de directorios: Registro MCP oficial · Smithery · Glama

Autenticación

Métodos anónimos (de descubrimiento): initialize, tools/list, ping, notifications/initialized, más las herramientas anónimas get_capabilities, get_pricing, list_styles.

Todas las demás herramientas requieren un token de API de Compeller pasado en la propia solicitud HTTP, no dentro del cuerpo JSON-RPC. Cualquiera de las dos cabeceras funciona:

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

Los tokens se emiten por User de Compeller (los mismos tokens que usa /api/v1/*). Los agentes pueden obtener uno de dos maneras:

1. Pedir al usuario que inicie sesión, abra Cuenta → Acceso API, revele el token y lo pegue en el almacén de secretos del agente.
2. Usar el endpoint de inicio de sesión existente y enviar access_token como token de portador. No se necesita ni se espera ninguna cabecera Cookie:

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

Los usuarios normales reciben username y access_token. roles aparece solo para cuentas con roles más allá del ROLE_COMPELLER de referencia; refresh_token y expires_in aparecen solo cuando no están vacíos.

3. O intercambiar credenciales mediante el asistente de autenticación v1, que devuelve el token de API persistente:

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

Un token ausente o no válido se manifiesta como un error de herramienta (isError: true) con el mensaje "API token required." / "Invalid API token.", no como un error JSON-RPC, para que los clientes MCP puedan pedir credenciales al usuario.

Métodos JSON-RPC

Método	Propósito	Resultado HTTP
initialize	Apretón de manos de capacidades. Devuelve protocolVersion, serverInfo, capabilities.	Resultado JSON-RPC 200
notifications/initialized	Acuse de recibo del cliente. Sin cuerpo de respuesta.	204
tools/list	Lista todas las herramientas con esquema y descripción.	Resultado JSON-RPC 200
tools/call	Invoca una herramienta. params = {name, arguments}.	Resultado JSON-RPC 200 (los errores de herramienta vuelven como {isError: true, content: [...]})
ping	Mantenimiento de conexión sin operación.	result: {} JSON-RPC 200

Los métodos desconocidos devuelven el error JSON-RPC -32601 Method not found. Los nombres de herramienta desconocidos devuelven -32602 Unknown tool. Un cuerpo JSON mal formado devuelve -32700 Parse error. Un jsonrpc ausente o incorrecto, o un method ausente, devuelve -32600 Invalid Request.

Herramientas

Todas las herramientas devuelven una única entrada content de type: text cuyo campo text es una salida estructurada con formato JSON. En caso de fallo, se devuelve la misma forma de respuesta con isError: true y un mensaje de error legible en content[0].text — nunca como un error JSON-RPC.

Descubrimiento (sin autenticación)

Herramienta	Entradas	Devuelve
get_capabilities	—	productName, version, capabilities[], spec_url, enums (styles, target_platforms, aspect_ratios), auth, media_limits, rate_limits
get_pricing	—	plans[] con id, name, monthlyUsd, features[]
list_styles	—	styles[] con id, name (el id es el valor exacto que create_compel / create_compel_from_music aceptan para style)

Medios y música (autenticación requerida salvo que se indique)

Herramienta	Requerido	Opcional	Devuelve
search_music	query	limit	Resultados de búsqueda de música pública adecuados para create_compel_from_music. No requiere autenticación.
upload_media	—	name, mime_type, type	Instrucciones de subida que apuntan a POST /api/v1/media
search_media	—	type (audio/image/video/text), limit (≤100, por defecto 20), offset	media[], paging

Compels (autenticación requerida)

Herramienta	Requerido	Opcional	Devuelve
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	—	Inicia el renderizado final cuando el compel está listo; devuelve estado y siguiente acción.
cancel_compel	compel_id	—	Cancela un compel en curso (idempotente — un ya-CANCELADO tiene éxito); devuelve compel_id, status: CANCELLED, stage.
list_compels	—	limit (≤100), offset	compels[], paging
search_compels	query	limit	compels[], count

style, target_platform y aspect_ratio están restringidos por enum en los esquemas de las herramientas (ver get_capabilities.enums); los valores de style provienen directamente de list_styles.

Cuenta (autenticación requerida)

Herramienta	Entradas	Devuelve
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — llama antes de un renderizado costoso para tomar decisiones conscientes del costo.

Renderizados (autenticación requerida)

Herramienta	Requerido	Devuelve
list_renderings	compel_id	compel_id, renderings[] con rendering_id, status, download_url
get_rendering	rendering_id	rendering_id, compel_id, status, download_url

download_url apunta a GET /api/v1/renderings/{id}/download (soporta HTTP Range). Las respuestas de compel/renderizado completadas también incluyen un traspaso react con la descarga gratuita de REACT (https://compeller.ai/download/desktop) y la URL de más información (https://compeller.ai/react) para que los agentes puedan indicar a los usuarios cómo experimentar el compel como sistema de actuación en vivo.

Webhooks (autenticación requerida)

Los agentes que se integran con Compeller pueden auto-registrarse para recibir notificaciones push firmadas de eventos del ciclo de vida del compel en lugar de sondear get_compel. Suscríbete a compel.ready para saber el momento en que un compel es renderizable (y luego llama a start_render) sin sondear; compel.completed / compel.failed son los eventos terminales.

Herramienta	Requerido	Opcional	Devuelve
register_webhook	url (HTTPS, ≤2048 caracteres)	events[] — por defecto ["*"]; valores conocidos: *, compel.ready, compel.completed, compel.failed	webhook_id, url, events, secret (devuelto exactamente una vez), active, created_at
list_webhooks	—	—	webhooks[] — webhook_id, url, events, active, created_at, updated_at. Los secretos nunca se devuelven con esta herramienta.
update_webhook	webhook_id	url, events[], active — al menos uno	webhook_id, url, events, active, created_at, updated_at. Los secretos nunca se devuelven; usa rotate_webhook_secret para eso.
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?. Síncrona — la herramienta espera la respuesta del endpoint del integrador (máx. 5 s). Los secretos nunca se devuelven.
rotate_webhook_secret	webhook_id	—	webhook_id, url, events, active, secret (nuevo — devuelto exactamente una vez), created_at, updated_at. El secreto antiguo se invalida inmediatamente.

Los nombres de evento desconocidos colapsan silenciosamente al comodín *; esto refleja POST /api/v1/webhooks para que un agente nunca cree una suscripción sin operación.

La entrega es al-menos-una-vez. Cada evento se intenta inmediatamente y, si tu endpoint es inalcanzable o devuelve un no-2xx, se reintenta con retroceso — hasta 6 intentos en total (inmediatamente, luego tras 1 m, 5 m, 30 m, 2 h, 6 h). Cada intento lleva el mismo X-Compeller-Event-Id y un cuerpo firmado byte-idéntico, así que deduplica con ese id. Si se agotan todos los intentos, el evento se descarta; concilia mediante get_compel.

register_webhook rechaza destinos que apuntan a infraestructura interna con un error de herramienta: bucle local, rangos privados RFC1918, enlace-local (incluidas IPs de metadatos de nube como 169.254.169.254), ULA IPv6, CGNAT, multidifusión, la dirección no especificada y nombres de host que terminan en .local / .internal / .localhost. La misma comprobación se vuelve a ejecutar en el momento de la entrega contra el DNS resuelto en cada intento, de modo que un nombre de host que se re-vincula a una IP bloqueada tras el registro se omite para ese intento (registrado); si permanece bloqueado, simplemente consume su presupuesto de reintentos y luego se descarta.

test_webhook_delivery envía un evento sintético webhook.test con una firma HMAC-SHA256 y espera síncronamente la respuesta del endpoint. Ignora el events suscrito del endpoint (siempre se entrega) y aplica la misma comprobación de seguridad de URL que las entregas reales. Una respuesta no-2xx se manifiesta como delivered: false, pero la llamada MCP en sí aún devuelve éxito — el resultado es la carga útil.

update_webhook acepta cualquiera de url, events, active (al menos uno). La validación de URL refleja register_webhook. Los secretos nunca se devuelven con esta herramienta.

rotate_webhook_secret acuña un nuevo secreto de firma hexadecimal de 64 caracteres, lo devuelve exactamente una vez e invalida el secreto anterior inmediatamente. Guarda el nuevo secreto al recibirlo antes de la siguiente entrega real.

Cada entrega está firmada exactamente como la ruta REST — ver la sección Webhooks de openapi.yaml para el sobre completo y el contrato de cabeceras.

Sesión de ejemplo

# 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 respuesta al paso 3 es un result JSON-RPC que contiene content[0].text — en sí mismo un documento JSON con webhook_id, secret, etc. Guarda secret inmediatamente; el servidor no lo devolverá de nuevo.

Códigos de error

Código	Significado	Causa
-32700	Error de análisis	El cuerpo no es JSON válido
-32600	Solicitud no válida	jsonrpc ausente/incorrecto, method ausente, cuerpo vacío
-32601	Método no encontrado	Método JSON-RPC desconocido
-32602	Parámetros no válidos	Herramienta desconocida, name de herramienta ausente, forma de params incorrecta
-32603	Error interno	Excepción no controlada (registrada en el servidor)

Los fallos a nivel de herramienta (validación, autenticación, no encontrado) se devuelven dentro de una respuesta JSON-RPC exitosa como {result: {isError: true, content: [{type: "text", text: "..."}]}}. Esto es por convención de MCP — permite que el LLM vea y muestre el fallo textualmente. Árbol de decisión de audio del agente: si el usuario proporciona MP3/WAV/FLAC, usa upload_media y luego create_compel; si el usuario proporciona solo una cadena de canción/artista, usa search_music y luego create_compel_from_music; no sintetices un tono a menos que se te pida explícitamente audio de prueba generado.