Agent guide

Set up the Convertrilo MCP server in agent clients

Install @convertrilo/sdk, save an API key with the CLI, configure convertrilo-mcp in an MCP client, and verify the available video encoding tools.

The Convertrilo MCP server is a local stdio server for agents and workflow tools. It exposes a narrow set of video encoding tools while using the same credentials and API behavior as the CLI and SDK.

Create API keyAPI docsIntegration overview
MCP client configguide
npm install -g @convertrilo/sdk
convertrilo login

{
  "mcpServers": {
    "convertrilo": {
      "command": "convertrilo-mcp"
    }
  }
}

Node.js 22.13 or newer.

An MCP client that supports local stdio server commands.

A scoped Convertrilo API key from Developer Settings.

The @convertrilo/sdk npm package installed globally or available by absolute path.

Recipe

Build the workflow with stable API primitives

These guides focus on primitives that can be reused by dashboards, queue workers, scripts, CLIs, MCP tools, and agent runtimes.

  1. Step 1

    Install the npm package to get both convertrilo and convertrilo-mcp.

  2. Step 2

    Run convertrilo login or set CONVERTRILO_API_KEY in the MCP client environment.

  3. Step 3

    Add convertrilo-mcp as a stdio server command in your MCP client config.

  4. Step 4

    List tools in the client and verify get_token_balance before creating an encode job.

Use saved CLI credentials

convertrilo-mcp reads the API key saved by convertrilo login, so local clients do not need to duplicate secrets in every config file.

Keep agent tools narrow

Expose only the Convertrilo MCP server to agents that need video encoding, then use scoped keys for job creation, status reads, cancellation, and tokens.

Verify with a read-only call

Call get_token_balance first. Once authentication works, create an encode job with explicit codec, resolution, quality, and idempotency instructions.

Developer questions

Does convertrilo-mcp need an HTTP server URL?

No. The current server uses stdio. Configure your MCP client with the command convertrilo-mcp, or point it at a local dist/src/mcp.js build during development.

Where does the API key come from?

Run convertrilo login --open to open Developer Settings, then paste the key into the CLI. MCP will reuse the saved key unless CONVERTRILO_API_KEY is set.

Which tools does the MCP server expose?

create_encode_job, get_job_status, wait_for_job, cancel_job, and get_token_balance.

Related developer paths

SDK quickstartInstall the Convertrilo TypeScript SDK, create an API key, submit a retry-safe encoding job, and wait for a completed output.Queue automationConnect Convertrilo to your own queues, cron jobs, imports, and backfills without duplicating jobs when retries happen.Webhook receiverReceive signed Convertrilo job events, verify the HMAC signature, and update your own product when outputs are ready.S3 output workflowsRoute completed video encodes to S3-compatible buckets so your product keeps ownership of storage, CDN, lifecycle rules, and access control.Agent workflowsDesign agent-friendly video encoding workflows with the Convertrilo MCP server, scoped API keys, deterministic job payloads, idempotency, polling, and signed webhooks.Video encoding APICreate video encoding jobs from your backend with API keys, idempotency, metadata, priority queues, webhooks, and storage destinations you control.Video encoding CLIAutomate video compression from terminals, deployment jobs, content pipelines, and scheduled scripts with a Convertrilo CLI workflow.VMAF video encodingUse VMAF-guided sample encoding to choose a better quality target before the final video encode, without manually testing bitrate settings.Two-pass video encodingUse classic two-pass H.264 and H.265 encoding when predictable bitrate allocation matters more than raw hardware speed.

Start with a real estimate

Choose your codec, resolution, FPS, bitrate, quality, and optimization settings. Convertrilo shows the NEU estimate before credits are reserved, and failed jobs release reserved credits back to your balance.

Start FreeCalculate Pricing