trvrse

trvrse cinema — MCP guide for agents

You are (or are configuring) an LLM agent connected to the trvrse cinema MCP server. It exposes a five-stage film pipeline — Script → References → Storyboards → Videos → Assembly — as 31 tools: 18 stage-by-stage tools you drive yourself, plus 3 Autopilot tools (make_film, get_run, cancel_run) that hand the whole pipeline to the server for one-call film production, plus make_long_film (multi-minute films with consistent characters, §3) and get_gate_review_link (mint a no-login human review link for a gated stage), plus 5 cast tools (save_character_to_cast, list_cast, delete_cast_member, set_cast_voice, refresh_cast_portrait) for episodic reuse of approved characters, plus refresh_character_portrait for re-minting a non-cast character's expired trusted portrait, plus set_shot_face_trust_override for per-scene face-moderation control. Separately, 13 asset tools (estimate_generation_cost, generate_image, edit_image, generate_storyboard, promote_storyboard_panel, upload_image, list_images, generate_video, get_video_job, get_tool_call, list_videos, cancel_video_job, get_credit_balance) generate reference images and Seedance 2.5 videos without a cinema project (§4). A third surface, 6 video-plan tools (estimate_video_plan_cost, create_video_plan, get_video_plan, list_video_plans, approve_video_plan, reject_video_plan, §5), builds a full Seedance 2.x manifest — brief, refs, prompt, cost — that a human OR the agent itself approves before it dispatches. This guide is the complete playbook: connecting, the workflow loop, Autopilot, standalone assets, video plans, cost and error contracts, and a worked end-to-end transcript.

Endpoint: https://www.trvrse.com/api/mcp/mcp · Keys: minted by a human at Settings → Agent access · Raw markdown version of this page: https://www.trvrse.com/docs/agents.md

1. Quick start

Mint a key

1. Sign in to the app and go to Settings → Agent access (https://www.trvrse.com/settings/agent).
2. Click New key, give it a name (and, optionally, a spend cap in credits — leave blank for uncapped).
3. The plaintext key is shown exactly once in a modal you must explicitly dismiss with Done. Copy it now — it is never shown again (only a trv_ + 8-char prefix is kept for display). If you lose it, revoke the key and mint a new one.

The key looks like trv_ followed by 43 base64url characters, e.g. trv_9F2k7q....

Endpoint

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

(mcp-handler 's basePath is /api/mcp; it appends the mcp transport segment itself. Streamable HTTP only — SSE is disabled.)

Claude Code

claude mcp add --transport http --scope user trvrse https://www.trvrse.com/api/mcp/mcp \
  -H "Authorization: Bearer trv_YOUR_KEY_HERE"

Every per-client recipe (Claude Code, Claude.ai, ChatGPT, Cursor, mcpServers JSON) with the key pre-filled lives on Settings → Agent access → Connect and at https://www.trvrse.com/docs/agents/connect.

Generic MCP client (JSON config)

Most MCP clients (Claude Desktop, other agent runtimes) accept a config block like:

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

The exact key name/shape (url vs command, headers vs env) varies by client — anything that supports a streamable-HTTP MCP transport with a custom header works. The same canonical endpoint also supports the OAuth flow used by the OpenAI Plugins Directory; existing trv_ keys remain valid.

claude.ai and legacy ChatGPT custom connectors

claude.ai and ChatGPT custom connectors support only OAuth or "no authentication" — never a custom Authorization header, so the two connect methods above don't work there. Use the keyed-URL endpoint instead (shown alongside the plaintext key when a new one is minted, on Settings → Agent access):

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

claude.ai — Settings → Customize → Connectors → Add custom connector → paste the URL above, leave authentication as None.

For a legacy ChatGPT developer-mode custom connector, the same keyed URL continues to work with authentication None. The Plugins Directory uses the canonical /api/mcp/mcp URL and OAuth instead; never submit a keyed URL.

The key rides in the URL path; the endpoint injects it as the bearer token internally and forwards to the same authed handler above — no second server, no different tool catalog. The URL is bearer-equivalent: treat it like a password (don't paste it somewhere public), prefer a spend-capped key per connector, and revoke it any time from Settings → Agent access if it leaks.

Sanity-check the connection

A malformed, unknown or revoked key is refused at initialize, so claude mcp list shows ✗ immediately. To see WHY, and what the key has left:

curl -sS https://www.trvrse.com/api/mcp/health -H "Authorization: Bearer trv_YOUR_KEY_HERE"
# 200 {"ok":true,"keyName":"…","spendCap":500,"spent":0,"remaining":500,"lastSeen":null,"lastSeenClient":null}
# 401 {"ok":false,"reason":"malformed"|"unknown"|"revoked"}   429 rate-limited

Then ask the agent to call list_projects. A working connection returns real JSON; a key revoked mid-session returns an isError result naming BRIDGE_AUTH_FAILED (see the error contract below).

Install this guide as a skill (optional)

Claude Code and other skills-capable agents can carry this playbook in-context instead of re-reading it each session:

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. The workflow loop

Every film follows the same loop per stage:

1. Check state — get_project_status: read the five stage statuses and nextActions (it names exactly the tool calls the pipeline admits next; trust it over guessing).
2. Quote — get_cost_estimate for the stage you are about to generate.
3. Generate — call the stage's generate_* tool with confirmedCost set to the quote's exact total.
4. Poll — get_project_status every 15–30 seconds until the stage's entities leave GENERATING (typically 1–3 minutes).
5. Review & approve — inspect results (statuses, failure reasons), regenerate anything that failed, then call the stage's approve_* tool to unlock the next stage.

Script is the exception: generate_script and rewrite_scenes run the LLM in-request and return the full screenplay synchronously (~30–60 seconds), and script work is free — no quote needed.

3. One-call films (Autopilot)

Instead of driving the five-stage loop above yourself, make_film hands the whole pipeline to the server: submit a brief and a budget, then poll get_run until the film is done.

make_film

• briefText (required) — the production brief the whole film is generated from.
• profile (required) — "cinematic" (16:9 default) or "short" (see below).
• budgetCredits (required) — a hard ceiling for the run's total spend (see "Budget is a hard ceiling" below).
• gates (optional, default [] = fully unattended) — which of "script", "references", "storyboards", "videos", "assembly" pause the run for human review (see "Gates" below).
• webhookUrl (optional, https:// only) — receives run events (see "Webhooks" below).
• title, aspectRatio, videoModel (optional) — same shapes as create_project; profile supplies defaults you can override.

Returns {runId, projectId, webhookSecret?}. webhookSecret is present only when webhookUrl was set, and is shown exactly once, here — save it immediately, it is never returned again and you need it to verify webhook deliveries.

make_long_film — multi-minute films with consistent characters

Use this instead of make_film when the user wants a long-form piece whose characters must stay recognisably the same person throughout.

It runs the same pipeline, but changes how video is generated. make_film renders one independent clip per storyboard page and concatenates them, so a 3-minute film is 20–40 separate generations — each an independent roll of the dice on character identity. make_long_film renders each page as ONE continuous multi-shot Seedance 2.5 generation and continues the previous page through native video extension, so the same film is about 6 generations. Every segment re-sends the same approved character portraits: the extension carries continuity, the portraits carry identity.

• Pinned to seedance-2.5-reference. videoModel is not selectable.
• Total runtime is capped at 180 seconds. A storyboard that plans more is refused with the exact overage — cut scenes and regenerate.
• gates defaults to all four review points ("script", "references", "storyboards", "videos"), because the point of this tool is that a human signs off on the cast and the plot before the expensive video leg. Pass [] only if the user explicitly asks for an unattended run.
• Other arguments match make_film: briefText, budgetCredits, title, castIds, webhookUrl, aspectRatio.