trvrse

trvrse cinema — Guía MCP para agentes

Eres (o estás configurando) un agente LLM conectado al servidor MCP de trvrse cinema. Expone un pipeline de cine de cinco etapas — Guion → Referencias → Storyboards → Videos → Ensamblaje — como 28 herramientas: 17 herramientas etapa por etapa que manejas tú mismo, más 3 herramientas de Autopilot (make_film, get_run, cancel_run) que entregan todo el pipeline al servidor para producción de cine en una sola llamada, más make_long_film (películas de varios minutos con personajes consistentes, §3) y get_gate_review_link (genera un enlace de revisión humana sin inicio de sesión para una etapa bloqueada), más 4 herramientas de reparto (save_character_to_cast, list_cast, delete_cast_member, refresh_cast_portrait) para reutilización episódica de personajes aprobados, más refresh_character_portrait para re-generar el retrato de confianza expirado de un personaje no perteneciente al reparto, más set_shot_face_trust_override para control de moderación facial por escena. Por separado, 7 herramientas de activos (estimate_generation_cost, generate_image, edit_image, upload_image, list_images, generate_video, get_video_job) generan imágenes de referencia y videos Seedance 2.5 sin un proyecto de cine (§4). Una tercera superficie, 6 herramientas de plan de video (estimate_video_plan_cost, create_video_plan, get_video_plan, list_video_plans, approve_video_plan, reject_video_plan, §5), construye un manifiesto completo de Seedance 2.x — brief, referencias, prompt, costo — que un humano O el propio agente aprueba antes de que se despache. Esta guía es el manual completo: conexión, el bucle de trabajo, Autopilot, activos independientes, planes de video, contratos de costo y errores, y una transcripción completa de extremo a extremo.

Endpoint: https://www.trvrse.com/api/mcp/mcp · Claves: generadas por un humano en Configuración → Acceso de agente · Versión en markdown sin formato de esta página: https://www.trvrse.com/docs/agents.md

1. Inicio rápido

Generar una clave

1. Inicia sesión en la aplicación y ve a Configuración → Acceso de agente (https://www.trvrse.com/settings/agent).
2. Haz clic en Nueva clave, dale un nombre (y, opcionalmente, un límite de gasto en créditos — déjalo en blanco para sin límite).
3. La clave en texto plano se muestra exactamente una vez en un modal que debes cerrar explícitamente con Listo. Cópiala ahora — nunca se vuelve a mostrar (solo se conserva un trv_ + prefijo de 8 caracteres para visualización). Si la pierdes, revoca la clave y genera una nueva.

La clave se ve como trv_ seguido de 43 caracteres base64url, por ejemplo trv_9F2k7q....

Endpoint

https://www.trvrse.com/api/mcp/mcp

(El basePath de mcp-handler es /api/mcp; agrega el segmento de transporte mcp por sí mismo. Solo HTTP transmisible — SSE está deshabilitado.)

Claude Code

claude mcp add --transport http trvrse-cinema https://www.trvrse.com/api/mcp/mcp \
  --header "Authorization: Bearer trv_YOUR_KEY_HERE"

Cliente MCP genérico (configuración JSON)

La mayoría de los clientes MCP (Claude Desktop, otros runtimes de agentes) aceptan un bloque de configuración como:

{
  "mcpServers": {
    "trvrse-cinema": {
      "url": "https://www.trvrse.com/api/mcp/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer trv_YOUR_KEY_HERE"
      }
    }
  }
}

El nombre/forma exacta de la clave (url vs command, headers vs env) varía según el cliente — cualquier cosa que admita un transporte MCP HTTP transmisible con un encabezado personalizado funciona. No hay flujo de OAuth/registro dinámico; el token bearer es la credencial.

claude.ai y ChatGPT (conectores personalizados)

Los conectores personalizados de claude.ai y ChatGPT solo admiten OAuth o "sin autenticación" — nunca un encabezado Authorization personalizado, por lo que los dos métodos de conexión anteriores no funcionan allí. Usa el endpoint de URL con clave en su lugar (se muestra junto con la clave en texto plano cuando se genera una nueva, en Configuración → Acceso de agente):

https://www.trvrse.com/api/mcp/k/trv_YOUR_KEY_HERE/mcp

claude.ai — Configuración → Conectores → Agregar conector personalizado → pega la URL anterior, deja la autenticación como Ninguna.

ChatGPT (modo desarrollador / conectores personalizados) — agrega un conector con la misma URL, autenticación Ninguna.

La clave viaja en la ruta de la URL; el endpoint la inyecta como token bearer internamente y reenvía al mismo manejador autenticado anterior — sin segundo servidor, sin catálogo de herramientas diferente. La URL es equivalente a un bearer: trátala como una contraseña (no la pegues en un lugar público), prefiere una clave con límite de gasto por conector, y revócala en cualquier momento desde Configuración → Acceso de agente si se filtra.

Verificar la conexión

Una vez conectado, pide al agente que llame a list_projects (o ejecuta get_project_status contra un id de proyecto existente). Una conexión que funciona devuelve JSON real; una clave mala devuelve un resultado isError que nombra a BRIDGE_AUTH_FAILED (consulta el contrato de errores a continuación).

Instalar esta guía como habilidad (opcional)

Claude Code y otros agentes con capacidad de habilidades pueden llevar este manual en contexto en lugar de releerlo en cada sesión:

SKILLS_DIR=~/.claude
mkdir -p "$SKILLS_DIR/skills/trvrse-cinema" && \
  curl -fsSL https://www.trvrse.com/docs/agents/skill.md \
  -o "$SKILLS_DIR/skills/trvrse-cinema/SKILL.md"

2. El bucle de trabajo

Cada película sigue el mismo bucle por etapa:

1. Verificar estado — get_project_status: lee los cinco estados de etapa y nextActions (nombra exactamente las llamadas a herramientas que el pipeline admite a continuación; confía en él en lugar de adivinar).
2. Cotizar — get_cost_estimate para la etapa que estás a punto de generar.
3. Generar — llama a la herramienta generate_* de la etapa con confirmedCost configurado con el total exacto de la cotización.
4. Consultar — get_project_status cada 15–30 segundos hasta que las entidades de la etapa salgan de GENERATING (normalmente 1–3 minutos).
5. Revisar y aprobar — inspecciona los resultados (estados, razones de fallo), regenera lo que haya fallado, luego llama a la herramienta approve_* de la etapa para desbloquear la siguiente.

El guion es la excepción: generate_script y rewrite_scenes ejecutan el LLM en la solicitud y devuelven el guion completo de forma síncrona (~30–60 segundos), y el trabajo de guion es gratuito — no se necesita cotización.

3. Películas de una sola llamada (Autopilot)

En lugar de manejar el bucle de cinco etapas tú mismo, make_film entrega todo el pipeline al servidor: envía un brief y un presupuesto, luego consulta get_run hasta que la película esté lista.

make_film

• briefText (obligatorio) — el brief de producción del que se genera toda la película.
• profile (obligatorio) — "cinematic" (16:9 predeterminado) o "short" (consulta a continuación).
• budgetCredits (obligatorio) — un límite máximo para el gasto total de la ejecución (consulta "El presupuesto es un límite máximo" a continuación).
• gates (opcional, predeterminado [] = completamente desatendido) — cuál de "script", "references", "storyboards", "videos", "assembly" pausa la ejecución para revisión humana (consulta "Bloqueos" a continuación).
• webhookUrl (opcional, solo https://) — recibe eventos de ejecución (consulta "Webhooks" a continuación).
• title, aspectRatio, videoModel (opcional) — mismas formas que create_project; profile proporciona valores predeterminados que puedes anular.

Devuelve {runId, projectId, webhookSecret?}. webhookSecret está presente solo cuando webhookUrl se configuró, y se muestra exactamente una vez, aquí — guárdalo inmediatamente, nunca se devuelve de nuevo y lo necesitas para verificar las entregas de webhook.

make_long_film — películas de varios minutos con personajes consistentes

Usa esto en lugar de make_film cuando el usuario quiera una pieza de formato largo cuyos personajes deben seguir siendo reconociblemente la misma persona en todo momento.

Ejecuta el mismo pipeline, pero cambia cómo se genera el video. make_film renderiza un clip independiente por página de storyboard y los concatena, por lo que una película de 3 minutos son 20–40 generaciones separadas — cada una un lanzamiento de dados independiente sobre la identidad del personaje. make_long_film renderiza cada página como UNA generación continua de múltiples tomas de Seedance 2.5 y continúa la página anterior mediante extensión de video nativa, por lo que la misma película son unas 6 generaciones. Cada segmento reenvía los mismos retratos de personajes aprobados: la extensión lleva la continuidad, los retratos llevan la identidad.

• Fijado a seedance-2.5-reference. videoModel no es seleccionable.
• La duración total está limitada a 180 segundos. Un storyboard que planee más se rechaza con el exceso exacto — corta escenas y regenera.
• gates predeterminado a los cuatro puntos de revisión ("script", "references", "storyboards", "videos"), porque el punto de esta herramienta es que un humano apruebe el reparto y la trama antes de la costosa etapa de video. Pasa [] solo si el usuario pide explícitamente una ejecución desatendida.
• Otros argumentos coinciden con make_film: briefText, budgetCredits, title, castIds, webhookUrl, aspectRatio.