Transloadit

Servidor MCP

transloadit/node-sdk

El servidor MCP de Transloadit permite que los clientes de agentes llamen directamente a las herramientas de Transloadit: crear y supervisar Assemblies, validar Assembly Instructions y descubrir Robots y Templates.

Demostración: encoding de videos a streaming adaptativo HLS mediante el servidor MCP de Transloadit en Claude

Elige un modo de implementación

  • Autohospedado (recomendado): es la opción más sencilla para la mayoría de los equipos. Tu proceso MCP tiene acceso a TRANSLOADIT_KEY y TRANSLOADIT_SECRET, por lo que puede gestionar automáticamente la autenticación de las llamadas a la API.
  • Endpoint alojado: usa https://api2.transloadit.com/mcp cuando no puedas ejecutar npx donde se ejecuta tu agente.

Inicio rápido (autohospedado)

TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY npx -y @transloadit/mcp-server stdio

HTTP

TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY \
npx -y @transloadit/mcp-server http --host 127.0.0.1 --port 5723

Docker

docker run -i --rm \
  -e TRANSLOADIT_KEY=MY_AUTH_KEY \
  -e TRANSLOADIT_SECRET=MY_SECRET_KEY \
  ghcr.io/transloadit/mcp-server:latest

El modo http usa de forma predeterminada la ruta /mcp.

Explicación de TRANSLOADIT_MCP_TOKEN

TRANSLOADIT_MCP_TOKEN es un token de transporte MCP autohospedado. Protege tu propio endpoint MCP HTTP (npx -y @transloadit/mcp-server http), no API2.

  • Configúralo tú mismo con cualquier secreto de alta entropía.
  • Envíalo desde tu cliente MCP como Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>.
  • No se emite mediante /token.
  • Es independiente de los tokens Bearer de API2 utilizados para https://api2.transloadit.com/mcp.

Genera uno y, a continuación, inicia el modo HTTP:

export TRANSLOADIT_MCP_TOKEN="$(openssl rand -hex 32)"
npx -y @transloadit/mcp-server http --host 0.0.0.0 --port 5723

Endpoint alojado

Si no puedes autohospedarlo, configura tu cliente de agente para que use:

https://api2.transloadit.com/mcp

Usa Authorization: Bearer <token> y emite el token mediante:

npx -y @transloadit/node auth token --aud mcp

Genera este token en un entorno de confianza (backend, CI o shell local) y, a continuación, entrégaselo al entorno de ejecución del agente. Puedes emitirlo mediante:

  • CLI: npx -y @transloadit/node auth token --aud mcp
  • API: POST /token
  • SDK de Node.js: crea una instancia de Transloadit con authKey + authSecret y, a continuación, llama a client.mintBearerToken({ aud: 'mcp' })

Los tokens son válidos durante seis horas (expires_in: 21600). Cuando una solicitud se autentica con un token Bearer válido, API2 considera satisfecha Signature Authentication y omite la validación de la firma. Signature Authentication sigue siendo obligatoria para las solicitudes con clave y secreto.

Ejemplos de configuración de clientes

Claude Desktop / Claude Code

{
  "mcpServers": {
    "transloadit": {
      "type": "streamableHttp",
      "url": "https://api2.transloadit.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TRANSLOADIT_AUTH_TOKEN"
      }
    }
  }
}

VS Code / Copilot

{
  "servers": {
    "transloadit": {
      "type": "http",
      "url": "https://api2.transloadit.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TRANSLOADIT_AUTH_TOKEN"
      }
    }
  }
}

Cursor

Usa la misma URL HTTP transmisible y el encabezado Authorization en la configuración de MCP.

Herramientas disponibles

El servidor MCP expone estas herramientas:

  • transloadit_lint_assembly_instructions
  • transloadit_create_assembly
  • transloadit_get_assembly_status
  • transloadit_wait_for_assembly
  • transloadit_list_robots
  • transloadit_get_robot_help
  • transloadit_list_templates

transloadit_list_templates admite include_builtin (all, latest, exclusively-all, exclusively-latest) y el parámetro opcional include_content.

Archivos de entrada y límites

transloadit_create_assembly admite tres tipos de entrada:

  • path: archivos locales que el proceso del servidor MCP puede leer
  • url: archivos remotos
  • base64: cargas útiles en línea para archivos pequeños

Límites y valores predeterminados:

  • Límite predeterminado del cuerpo de las solicitudes alojadas: 1 MB
  • Límite predeterminado del cuerpo de las solicitudes autohospedadas: 10 MB (configurable)
  • Valor predeterminado de maxBase64Bytes: 512.000 bytes decodificados

Para archivos más grandes, usa preferentemente entradas path o url.

Comportamiento de las URL y los Templates

Para las entradas URL, el servidor elige una ruta segura según las instrucciones o el Template de destino:

  • Si existe un Step /http/import, establece o reemplaza la url de ese Step.
  • Si el Template espera subidas (:original o /upload/handle), descarga el archivo y después lo sube mediante tus.
  • Si el Template no acepta archivos de entrada, las entradas URL se ignoran y se muestra una advertencia.
  • Si un Template prohíbe reemplazar Steps y solo admite /http/import, las entradas URL se rechazan.

Acceso a archivos locales frente a alojados

Las entradas path solo funcionan cuando el proceso MCP puede leer el mismo sistema de archivos (stdio/HTTP local). El MCP alojado no puede leer tu disco.

Para flujos de trabajo remotos, usa url, archivos pequeños mediante base64 o realiza la subida por separado con la CLI de Transloadit. Usa expected_uploads cuando quieras que una Assembly permanezca abierta para subidas posteriores mediante tus.

Métricas y tarjeta del servidor

Las implementaciones HTTP incluyen:

  • Métricas de Prometheus en GET /metrics (valor predeterminado)
  • Autenticación opcional para las métricas mediante TRANSLOADIT_MCP_METRICS_USER y TRANSLOADIT_MCP_METRICS_PASSWORD
  • Tarjeta pública del servidor MCP en /.well-known/mcp/server-card.json

Puedes personalizar metricsPath, deshabilitar las métricas (metricsPath: false) y configurar las restricciones de CORS/host en las opciones del servidor HTTP/Express.

Usar MCP con /ai/chat

/ai/chat puede llamar a cualquier servidor MCP accesible desde tu entorno.

Para los servidores MCP alojados por Transloadit, puedes usar:

{
  "mcp_servers": [
    {
      "type": "http",
      "url": "https://api2.transloadit.com/mcp",
      "auth": "transloadit"
    }
  ]
}

Con auth: "transloadit", API2 puede emitir automáticamente e inyectar un token Bearer de corta duración y alcance limitado para las URL de MCP aptas alojadas por Transloadit. Si ya proporcionas Authorization en mcp_servers[].headers, API2 no lo modifica.