Connect Colossyan to Claude: Turn knowledge into video drafts

If you need to connect Colossyan to Claude to automate text-to-video generation, query digital actors, or handle asynchronous rendering jobs natively from a chat interface, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Colossyan's REST API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Colossyan to ChatGPT or explore our broader architectural overview on connecting Colossyan to AI Agents.

Giving a Large Language Model (LLM) read and write access to an AI video synthesis platform like Colossyan is an engineering challenge. You are dealing with deeply nested JSON schemas for scene definitions, long-running asynchronous rendering jobs, and strict rate limits. Every time Colossyan updates an endpoint or deprecates a voice model, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Colossyan, connect it natively to Claude, and execute complex video generation workflows using natural language.

The Engineering Reality of the Colossyan API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Colossyan's API requires dealing with domain-specific complexities.

If you decide to build a custom MCP server for Colossyan, here are the specific challenges you will face:

Asynchronous Job Management Colossyan's core capability - generating video - is fundamentally asynchronous. You do not send a payload and get an MP4 file back in the HTTP response. Instead, you send a highly structured payload dictating scenes, actors, and scripts, and receive a jobId. Your MCP server must then expose tools that allow the LLM to intelligently poll the job status endpoint until the job resolves to a completed state, at which point a separate endpoint must be queried to fetch the actual video asset. Exposing these mechanics cleanly via MCP requires strictly mapping the job inputs and outputs so Claude understands when to wait and when to proceed.

Complex Nested Scene Schemas The video generation payload requires an intricate, deeply nested JSON structure. A single video contains multiple scenes, and each scene requires background settings, actor positioning, script text, and voice configurations. If you expose this raw schema to Claude without clear descriptions and required field mappings, the model will hallucinate invalid actor IDs or malformed scene arrays, resulting in constant 400 Bad Request errors from Colossyan. Truto handles the schema parsing directly from the API definitions, presenting Claude with standard JSON Schema requirements that guide its tool executions.

Raw Rate Limit Pass-Through Video rendering is computationally expensive, and Colossyan enforces rate limits on API interactions. A critical architectural note when using Truto: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Colossyan API returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. This means Claude (or your orchestration layer) receives clear signals on exactly how long to back off before retrying the job status ping, but the caller is fully responsible for implementing that retry logic.

Generating the Colossyan MCP Server

Truto dynamically generates MCP tools based on the resources and documentation available in your Colossyan integration. It provisions a self-contained server URL secured by a cryptographic token. You can generate this server via the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For administrators who want to quickly provision access for Claude Desktop users, the UI provides a one-click generation path.

1. Navigate to the integrated account page for your connected Colossyan instance in the Truto dashboard.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., allow only read methods to prevent accidental video rendering, or filter by specific tags).
5. Click Generate and copy the provided MCP server URL.

Method 2: Via the Truto API

If you are building dynamic agents or provisioning access programmatically, you can generate the MCP server via a REST call to Truto.

Endpoint: POST /integrated-account/:id/mcp

curl -X POST https://api.truto.one/integrated-account/<your_integrated_account_id>/mcp \
  -H "Authorization: Bearer <your_truto_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Colossyan Video Automation MCP",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API validates the available documentation records, generates a secure token, stores it in KV for edge-optimized routing, and returns the ready-to-use URL:

{
  "id": "mcp_abc123",
  "name": "Colossyan Video Automation MCP",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/t_7f8a9b0c..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with your Claude environment.

Method A: Via the Claude UI (Web/Desktop)

Anthropic natively supports adding custom remote MCP servers directly from the interface.

1. Open Claude and navigate to Settings -> Integrations.
2. Click Add MCP Server (or "Add custom connector" depending on your client version).
3. Paste the Truto MCP URL (https://api.truto.one/mcp/...).
4. Click Add.

Claude will immediately execute an initialization handshake, fetch the available Colossyan tools via the tools/list protocol, and make them available in your chat context.

Method B: Via Manual Config File (Claude Desktop)

If you prefer to manage your environment via configuration files, you can add the server using the claude_desktop_config.json file. Truto's MCP server communicates over HTTP/SSE, which requires the @modelcontextprotocol/server-sse transport bridge.

Locate your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration, replacing the URL with your actual Truto token URL:

{
  "mcpServers": {
    "colossyan": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/t_7f8a9b0c..."
      ]
    }
  }
}

Save the file and restart Claude Desktop. The initialization logs will show Claude discovering the Colossyan tools.

Hero Tools for Colossyan

Truto exposes the Colossyan API as distinct, callable tools. By explicitly mapping the query and body schemas into standard JSON Schema, Claude understands exactly what arguments to pass. Here are the most critical operations you will use when automating video generation.

list_all_colossyan_assets_actors

Before creating a video, the agent needs to know which digital actors (avatars) are available in the workspace. This tool returns the full roster of actors including their IDs, display names, supported features, and default voice associations.

"I need to create a new instructional video. Show me all the digital actors we have available in Colossyan, and list their default voice IDs."

list_all_colossyan_assets_voices

Voices are critical to the video generation process. This tool queries the workspace for all available voice models. The agent uses this to map a specific language, tone, or gender to the chosen actor before building the scene payload.

"Retrieve the list of available Colossyan voices. Filter the response to show me only the professional sounding British English voices."

create_a_colossyan_knowledge_to_draft_generate_draft

This tool leverages Colossyan's native AI drafting capabilities. You provide a structured text summary, and Colossyan returns a draft URL containing a pre-assembled video project. This is highly effective when translating knowledge base articles directly into video content.

"Take this technical guide on SSO configuration and run it through Colossyan to generate a new video draft. Return the draft URL when it is ready."

create_a_colossyan_video_generation_job

This is the core write operation. The agent constructs the complex JSON request body defining the video's scenes, text scripts, selected actors, and background assets. It returns a queued job identifier and a provisioned video ID.

"Create a Colossyan video generation job. The video should have one scene. Use the actor ID 'act_987' and the voice ID 'voc_654'. The script text is: 'Welcome to the quarterly review. Let's look at the numbers.'"

get_single_colossyan_video_generation_job_by_id

Because rendering is asynchronous, the agent must use this tool to poll the status of a specific job ID. It returns the current state (e.g., queued, processing, completed, failed) and a progress percentage.

"Check the status of Colossyan video generation job 'job_222'. If it is still processing, tell me the current progress percentage."

get_single_colossyan_generated_video_by_id

Once the job polling returns a completed status, the agent calls this tool using the videoId to fetch the finalized asset. The response includes the public URL, thumbnail URL, and metadata like video duration and size.

"The video job finished. Fetch the generated video asset for ID 'vid_555' and give me the public URL so I can share it with the team."

For the complete tool inventory and schema definitions, see the Colossyan integration page.

Workflows in Action

Exposing these tools to Claude transforms manual video production into a fluid, conversational workflow. Here are two concrete examples of how Claude executes these tasks.

Scenario 1: Drafting a Marketing Video

A content marketer needs to quickly turn a text update into a video draft for review.

"I have a new product update about our Q3 features. Please list our available Colossyan actors, pick one that looks professional, and then use the knowledge-to-draft tool to generate a video draft using this text: 'Q3 brings new API endpoints, faster sync times, and improved error handling.'"

Tool Execution Flow:

flowchart TD
    A["User Prompt"] --> B["list_all_colossyan_assets_actors"]
    B --> C["Claude analyzes actor metadata"]
    C --> D["create_a_colossyan_knowledge_to_draft_generate_draft<br>(summary: Q3 update)"]
    D --> E["Return Draft URL to User"]

1. Claude calls list_all_colossyan_assets_actors to inspect the available avatars.
2. It selects an appropriate actor based on the prompt criteria.
3. It calls create_a_colossyan_knowledge_to_draft_generate_draft passing the summary text.
4. Claude presents the resulting draft URL to the user, allowing them to open the Colossyan UI, review the draft, and manually trigger the final render.

Scenario 2: End-to-End Automated Video Generation

A developer wants Claude to fully assemble, initiate, and poll a video render until the final MP4 is ready.

"Generate a welcome video for new employees. Use actor 'act_101'. Create the job, and then monitor it until it is finished. When it completes, retrieve the final video URL."

Tool Execution Flow:

sequenceDiagram
    participant Claude as Claude
    participant Server as MCP Server
    participant API as Colossyan API
    
    Claude->>Server: create_a_colossyan_video_generation_job
    Server->>API: POST /video-generation-jobs
    API-->>Server: 201 Created (jobId: 123)
    Server-->>Claude: Result: jobId 123
    
    Note over Claude, API: Claude enters polling loop
    Claude->>Server: get_single_colossyan_video_generation_job_by_id(123)
    Server->>API: GET /video-generation-jobs/123
    API-->>Server: 200 OK (status: Processing, progress: 45)
    Server-->>Claude: Result: Processing (45%)
    
    Note over Claude: Backs off, waits...
    Claude->>Server: get_single_colossyan_video_generation_job_by_id(123)
    Server->>API: GET /video-generation-jobs/123
    API-->>Server: 200 OK (status: Completed, videoId: 456)
    Server-->>Claude: Result: Completed, videoId 456
    
    Claude->>Server: get_single_colossyan_generated_video_by_id(456)
    Server->>API: GET /generated-videos/456
    API-->>Server: 200 OK (publicUrl: https://...)
    Server-->>Claude: Result: publicUrl

1. Claude calls create_a_colossyan_video_generation_job with the defined scene structure and actor ID.
2. Colossyan returns a jobId.
3. Claude intelligently calls get_single_colossyan_video_generation_job_by_id to check the status.
4. If the status is "processing", Claude waits and polls again (handling its own internal timing or asking the user to wait).
5. Once the job reports "completed" and provides a videoId, Claude calls get_single_colossyan_generated_video_by_id.
6. Claude presents the final publicUrl to the user.

Security and Access Control

When exposing a system as powerful as Colossyan - where API calls consume compute credits - security is paramount. Truto's MCP servers provide several layers of access control configured at creation time:

• Method Filtering (config.methods): You can restrict the server to only read operations (listing actors/voices) to ensure the LLM cannot accidentally trigger expensive video generation jobs.
• Tag Filtering (config.tags): If you only want the model to manage drafts but not finalize videos, you can filter tools by specific functional tags defined in the integration.
• Secondary Authentication (require_api_token_auth): By default, possessing the MCP URL grants access. By setting this to true, the connecting client must also supply a valid Truto API token via the Authorization header, preventing unauthorized execution if the URL leaks.
• Automatic Expiration (expires_at): You can enforce a strict time-to-live. Once the ISO datetime is reached, the server is automatically purged from edge storage and the database, instantly revoking the LLM's access.

Automating the Studio

Connecting Colossyan to Claude removes the friction between raw text content and polished video output. Instead of manually navigating a UI to assign voices, select actors, and trigger renders, you can simply instruct your AI agent to orchestrate the API pipeline.

By leveraging a managed MCP server via Truto, you eliminate the need to write polling logic, maintain complex JSON schemas, or handle raw HTTP protocol translation. Your engineers can focus on building better prompts and workflows, while the integration layer handles the plumbing.