Compeller MCP Server

Endpoint MCP de Compeller (/api/mcp)

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

• Transporte: HTTP transmitible (un solo 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 a continuación es el contrato público de integración. Use tools/list para el conjunto anunciado en tiempo de ejecución en el servidor desplegado.
• Listados de directorios: Registro Oficial MCP · 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.

Cualquier otra herramienta requiere un token de API de Compeller pasado en la propia solicitud HTTP, no dentro del cuerpo JSON-RPC. Cualquiera de estos encabezados funciona:

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

Los tokens se emiten por User de Compeller (los mismos tokens utilizados por /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 secreto del agente.
2. Usar el endpoint de inicio de sesión existente y enviar access_token como token portador. No se necesita ni se espera un encabezado Cookie:

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

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

3. O intercambiar credenciales a través del ayudante 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":"[email protected]","password":"..."}'

Un token faltante o invá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 solicitar credenciales al usuario.

Métodos JSON-RPC

Método	Propósito	Resultado HTTP
initialize	Saludo de capacidades. Devuelve protocolVersion, serverInfo, capabilities.	200 resultado JSON-RPC
notifications/initialized	Confirmación del cliente. Sin cuerpo de respuesta.	204
tools/list	Lista cada herramienta con esquema + descripción.	200 resultado JSON-RPC
tools/call	Invoca una herramienta. params = {name, arguments}.	200 resultado JSON-RPC (los errores de herramienta regresan como {isError: true, content: [...]})
ping	Keepalive sin operación.	200 JSON-RPC result: {}

Los métodos desconocidos devuelven 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 faltante/incorrecto o un method faltante devuelve -32600 Invalid Request.

Herramientas

Todas las herramientas devuelven una sola 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 por humanos 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 (se requiere autenticación a menos 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 se requiere autenticación.
upload_media	—	name, mime_type, type	Instrucciones de carga apuntando a POST /api/v1/media
search_media	—	type (audio/image/video/text), limit (≤100, predeterminado 20), offset	media[], paging

Compels (se requiere autenticación)

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 progreso (idempotente — uno 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 herramientas (ver get_capabilities.enums); los valores de style provienen directamente de list_styles.

Cuenta (se requiere autenticación)

Herramienta	Entradas	Devuelve
get_account_credits	—	plan, minutes_remaining, free_minutes_remaining, paid_minutes_remaining, minutes_total, quota_exceeded, api_eligible, billing_url — llamar antes de un renderizado costoso para tomar decisiones informadas sobre costos.

Renderizados (se requiere autenticación)

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 Rango HTTP). Las respuestas de compel/renderizado completadas también incluyen un traspaso react con la descarga gratuita REACT (https://compeller.ai/download/desktop) y la URL para aprender más (https://compeller.ai/react) para que los agentes puedan decir a los usuarios cómo experimentar el compel como un sistema de actuación en vivo.

Webhooks (se requiere autenticación)

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íbase a compel.ready para saber el momento en que un compel es renderizable (luego llame a start_render) sin sondeo; compel.completed / compel.failed son los eventos terminales.

Herramienta	Requerido	Opcional	Devuelve
register_webhook	url (HTTPS, ≤2048 caracteres)	events[] — predeterminado a ["*"]; 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 son devueltos por esta herramienta.
update_webhook	webhook_id	url, events[], active — al menos uno	webhook_id, url, events, active, created_at, updated_at. Los secretos nunca son devueltos; use 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íncrono — la herramienta espera la respuesta del endpoint del integrador (máx. 5s). Los secretos nunca son devueltos.
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 su endpoint es inalcanzable o devuelve un no-2xx, se reintenta con retroceso — hasta 6 intentos en total (inmediatamente, luego después de 1m, 5m, 30m, 2h, 6h). Cada intento lleva el mismo X-Compeller-Event-Id y un cuerpo firmado idéntico byte a byte, así que deduplique por ese id. Si se agotan todos los intentos, el evento se descarta; reconcilie mediante get_compel.

register_webhook rechaza destinos que apuntan a infraestructura interna con un error de herramienta: loopback, rangos privados RFC1918, enlace local (incluyendo IPs de metadatos en la nube como 169.254.169.254), IPv6 ULA, CGNAT, multicast, la dirección no especificada y nombres de host que terminan en .local / .internal / .localhost. La misma verificación se vuelve a ejecutar en el momento de la entrega contra el DNS resuelto en cada intento, por lo que un nombre de host que se revincule a una IP bloqueada después del 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 sincrónicamente la respuesta del endpoint. Ignora el events suscrito del endpoint (siempre entregado) y aplica la misma verificación de seguridad de URL que las entregas reales. Una respuesta no-2xx se manifiesta como delivered: false pero la llamada MCP en sí misma aún regresa exitosamente — 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 son devueltos por 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. Almacene el nuevo secreto al recibirlo antes de la próxima entrega real.

Cada entrega se firma exactamente como la ruta REST — vea la sección Webhooks de openapi.yaml para el contrato completo de envoltura y encabezado.

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. Almacene 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 inválida	jsonrpc faltante/incorrecto, method faltante, cuerpo vacío
-32601	Método no encontrado	Método JSON-RPC desconocido
-32602	Parámetros inválidos	Herramienta desconocida, name de herramienta faltante, forma de params incorrecta
-32603	Error interno	Excepción no manejada (registrada en el lado del 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 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, use upload_media luego create_compel; si el usuario proporciona solo una cadena de canción/artista, use search_music luego create_compel_from_music; no sintetice un tono a menos que se solicite explícitamente audio de prueba generado.