Connect Colossyan to Claude: Manage Avatars and Video Generation

If you need to connect Colossyan to Claude to automate AI video generation, manage custom avatars, or orchestrate bulk video production workflows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's function calls and Colossyan's REST API. You can either build, host, 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 a video generation platform like Colossyan is an engineering challenge. You have to handle OAuth 2.0 or API key token lifecycles, map massive JSON schemas for video scenes to MCP tool definitions, and deal with the realities of asynchronous video rendering. 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 Desktop, 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 a video synthesis API is painful. You are not just integrating a standard CRUD database - you are orchestrating an asynchronous media rendering pipeline.

If you decide to build a custom MCP server for Colossyan, you own the entire API lifecycle. Here are the specific challenges you will face:

The Asynchronous Polling Trap Colossyan's video generation is not instantaneous. When you call the API to create a video, it returns a job identifier, not the finished media file. If you expose this directly to an LLM without clear semantic instructions, the model will often hallucinate that the video is complete or fail to understand how to check the status. You have to expose explicit polling tools and prompt the LLM to recursively check the job status. Truto handles the schema translation so Claude understands exactly how to pass the id from the creation step into the status check step.

Deeply Nested Scene Payloads The payload to create a Colossyan video generation job requires deeply nested JSON. A single request might contain an array of scenes, each containing specific actor, voice, background, and text objects. LLMs struggle to generate perfectly structured nested JSON from scratch without strict schema definitions. Truto dynamically derives the required query and body schemas from documentation records, enhancing them so Claude knows exactly which fields are required and how to structure the scene array.

Handling Rate Limits and 429 Errors Video rendering APIs are highly resource-intensive and strictly rate-limited. If your AI agent tries to submit twenty video generation jobs concurrently, Colossyan will block the requests. It is critical to understand that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Colossyan API returns an HTTP 429 error, Truto passes that error directly to the caller.

However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - in this case, the script managing Claude or the agent framework - is responsible for reading these headers and implementing the appropriate exponential backoff or retry logic.

How to Generate a Colossyan MCP Server with Truto

Truto dynamically generates MCP tools based on the integration's documented resources. Instead of hand-coding tools, Truto derives them from existing API definitions. A tool only appears in the MCP server if it has a corresponding documentation entry. This acts as a quality gate, ensuring Claude only sees well-documented endpoints.

Each MCP server is scoped to a single connected Colossyan account. The server URL contains a cryptographic token that encodes the account, allowed tools, and expiration rules. You can create this server in two ways.

Method 1: Via the Truto UI

For IT admins or developers looking for a fast, no-code setup, you can generate the server directly from the dashboard.

1. Log into your Truto environment and navigate to the integrated account page for your Colossyan connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can specify a name, filter by specific methods (like read or write), filter by tags, and set an expiration date.
5. Click Save and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For platform engineers building multi-tenant AI products, you can generate MCP servers programmatically for your end-users. The Truto API validates the integration, generates a secure token, stores it in edge storage, and returns a ready-to-use URL.

Make an authenticated POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Colossyan Video Automation MCP",
    "config": {
      "methods": ["read", "write", "custom"],
      "tags": ["video", "assets"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response will include the configuration and the secure URL:

{
  "id": "abc-123",
  "name": "Colossyan Video Automation MCP",
  "config": {
    "methods": ["read", "write", "custom"],
    "tags": ["video", "assets"]
  },
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

How to Connect the MCP Server to Claude

Once you have the Truto MCP server URL, you need to register it with Claude. Because the Truto URL is fully self-contained - embedding the routing and authentication logic securely in the token - no additional client-side code is required.

Method A: Via the Claude UI

If you are using an Enterprise or Team plan with Claude, or connecting via a supported web interface, you can add the connector directly in the settings.

1. Copy the MCP server URL from the Truto API or UI.
2. Open Claude and navigate to Settings -> Integrations -> Add MCP Server (or the equivalent Custom Connectors menu).
3. Name the connector "Colossyan Video API".
4. Paste the Truto URL and click Add.
5. Claude will immediately handshake with the URL, discover the available Colossyan tools, and make them available in your chat interface.

Method B: Via Manual Config File

If you are running Claude Desktop locally for development or utilizing custom agent frameworks, you can configure the MCP server using the standard JSON configuration file. Claude Desktop relies on Server-Sent Events (SSE) to communicate with remote HTTP MCP servers.

Open your claude_desktop_config.json file (typically found in ~/Library/Application Support/Claude/ on macOS or %APPDATA%\Claude\ on Windows) and add the following configuration:

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

Restart Claude Desktop. The application will use the official SSE transport bridge to communicate with the Truto endpoint. When you prompt Claude, it will dynamically fetch the Colossyan schema and execute tool calls over the network.

Hero Tools for Colossyan

Truto maps Colossyan's endpoints to descriptive, snake_case tool names. Here are the highest-leverage tools available for automating your video production pipeline.

list_all_colossyan_assets_actors

Before creating a video, the LLM needs to know which avatars (actors) are available in the workspace. This tool returns the full directory of actors, including their id, name, gender, type, and their default_voice settings. The agent can use this context to match a script to an appropriate avatar.

"List all the available actors in our Colossyan account. I am looking for a professional-looking female avatar to read our Q3 financial report script. Please tell me her exact ID and default voice."

list_all_colossyan_assets_voices

Colossyan supports hundreds of localized voices. This tool allows Claude to query the available voices, analyzing their specific attributes like language, accent, and style. The model uses this tool to grab the exact voice ID required for the video generation payload.

"Find a male voice actor with a British accent available in our workspace. Return the ID of the voice so we can use it in the upcoming training video generation job."

create_a_colossyan_video_generation_jobs_template_job

Instead of building a complex video scene by scene, teams often save branded templates in Colossyan. This tool allows Claude to trigger a video generation run based on a pre-existing template. The model only needs to provide the templateJobId and the variables specific to that template, drastically reducing the complexity of the JSON payload.

"We have a 'Weekly Update' template saved in Colossyan. Create a new video generation job using that template, and inject this new script text: 'Welcome to the weekly engineering sync. Today we shipped the new database migration.'"

create_a_colossyan_video_generation_job

This is the core orchestration tool. It allows Claude to build a video entirely from scratch by passing an array of scenes. The model will assemble the actor ID, voice ID, background settings, and the actual script text. It returns the newly queued job identifier.

"Create a new video generation job. Use the actor ID 'act_123' and voice ID 'voc_456'. The video should have one scene with a solid white background, and the script should say: 'Thank you for signing up for our enterprise plan. Let us get started with your deployment.'"

get_single_colossyan_video_generation_job_by_id

Because video rendering takes time, the agent must check the status of the job it just created. This tool takes the job id and returns the current status, the rendering progress percentage, and ultimately the finalized videoId when complete.

"Check the status of the video generation job ID 'job_9876'. If it is still processing, tell me the current progress percentage. If it is finished, give me the final video ID."

get_single_colossyan_generated_video_by_id

Once a video generation job is marked as completed, Claude uses this tool to retrieve the actual media object. It returns the publicUrl, thumbnailUrl, file size, and duration. This is the final step in the pipeline, allowing the model to hand the finished video link back to the user.

"The video generation job just finished. Retrieve the generated video using its ID and give me the public URL so I can download the MP4 file."

To view the complete inventory of available Colossyan tools, including webhook management and deletion endpoints, visit the Colossyan integration page.

Workflows in Action

Exposing individual APIs is useful, but the real power of MCP comes from stringing these tools together into autonomous workflows. Because the LLM understands the schemas, it can pass data from one response directly into the next request.

Scenario 1: The Automated Avatar and Voice Match

A marketing operations manager wants to quickly generate a promotional video but does not want to log into the Colossyan UI to find the right assets and piece together the request.

"I need to generate a welcome video for our new German market launch. First, find a female actor. Then, find a voice that supports the German language. Finally, use those IDs to generate a video saying 'Willkommen in unserem Team. Wir freuen uns auf die Zusammenarbeit.' Let me know when the job is queued."

How the agent executes this:

1. list_all_colossyan_assets_actors: Claude queries the actors list, filtering the response for a female avatar, and extracts her ID.
2. list_all_colossyan_assets_voices: Claude queries the voices list, looking for a German locale voice, and extracts that ID.
3. create_a_colossyan_video_generation_job: Claude constructs the nested JSON payload, placing the extracted actor ID and voice ID into the scene definition, along with the German script, and submits the job.

Scenario 2: End-to-End Rendering and Polling

A content creator wants Claude to not only start the video but wait until the final MP4 is ready to download.

"Trigger a video generation using our standard onboarding template job ID 'tpl_555' with the text 'Welcome aboard'. Monitor the job until it is fully completed, and then give me the public URL to the finished video."

How the agent executes this:

sequenceDiagram
  participant User as User
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant Colossyan as Colossyan API

  User->>Claude: "Generate video and wait for link"
  Claude->>Truto: Call create_a_colossyan_video_generation_jobs_template_job
  Truto->>Colossyan: POST /v1/template_jobs
  Colossyan-->>Truto: Return jobId (Status: queued)
  Truto-->>Claude: Forward jobId
  Note over Claude: Claude waits 30 seconds
  Claude->>Truto: Call get_single_colossyan_video_generation_job_by_id
  Truto->>Colossyan: GET /v1/jobs/{id}
  Colossyan-->>Truto: Status: processing (progress 45%)
  Truto-->>Claude: Forward progress
  Note over Claude: Claude waits 30 seconds
  Claude->>Truto: Call get_single_colossyan_video_generation_job_by_id
  Truto->>Colossyan: GET /v1/jobs/{id}
  Colossyan-->>Truto: Status: completed, returns videoId
  Truto-->>Claude: Forward videoId
  Claude->>Truto: Call get_single_colossyan_generated_video_by_id
  Truto->>Colossyan: GET /v1/videos/{videoId}
  Colossyan-->>Truto: Returns publicUrl
  Truto-->>Claude: Forward publicUrl
  Claude-->>User: "Here is your finished video link!"

1. create_a_colossyan_video_generation_jobs_template_job: Claude submits the template request and receives a job ID.
2. get_single_colossyan_video_generation_job_by_id: Claude polls the status. Because it is instructed to wait, it may call this tool multiple times over a few minutes until the status reads completed.
3. get_single_colossyan_generated_video_by_id: Using the videoId from the completed job, Claude fetches the final media object and presents the publicUrl to the user.

Security and Access Control

Giving an AI agent access to an enterprise video rendering platform carries operational risks. Generating hours of video can quickly deplete API credits. Truto provides strict access controls encoded directly into the MCP token, ensuring your agents only access what you permit.

• Method Filtering (config.methods): You can restrict an MCP server to specific operation types. For example, setting methods: ["read"] ensures the LLM can only query actors, voices, and job statuses, completely preventing it from triggering new video generations or deleting existing assets.
• Tag Filtering (config.tags): Integrations in Truto group resources by tags. You can filter the MCP server to only expose tools tagged with video_generation, isolating the agent from administrative endpoints.
• Extra Authentication (require_api_token_auth): By default, the MCP token URL is sufficient for authentication. If you are sharing this URL in a distributed environment, you can set require_api_token_auth: true. This forces the client to also provide a valid Truto API token in the Authorization header, adding a second layer of identity verification.
• Automatic Expiration (expires_at): You can configure an MCP server to automatically destruct at a specific ISO datetime. Truto handles the cleanup via durable edge alarms. This is ideal for granting a contractor or temporary automated workflow short-lived access to Colossyan.

Managing AI Video Production at Scale

Connecting Colossyan to Claude transforms how teams approach video localization, bulk rendering, and dynamic content generation. Instead of navigating complex UI menus or writing custom Python scripts to parse nested JSON and poll for job statuses, you can orchestrate the entire pipeline through natural language.

Building this custom MCP infrastructure in-house means owning the token refreshes, mapping the scene payloads, and managing the edge deployments. Using a managed layer like Truto offloads the boilerplate. It normalizes pagination, dynamically translates documentation into schemas, and cleanly passes rate-limit headers back to the agent so it can handle backoff gracefully.