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 (lint) Assembly Instructions y descubrir Robots y Templates.

Para ver un resumen rápido de lo que los agentes pueden hacer con Transloadit, consulta Transloadit mediante MCP.

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

Elige un modo de despliegue

  • Autoalojado (recomendado): el camino más sencillo 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 (autoalojado)

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 autoalojado. Protege tu propio endpoint MCP HTTP (npx -y @transloadit/mcp-server http), no API2.

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

Genera uno y luego 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 alojarlo tú mismo, apunta tu cliente de agente a:

https://api2.transloadit.com/mcp

El descubrimiento de Robots, la ayuda de Robots y la validación (lint) de las Assembly Instructions funcionan sin credenciales. Las acciones de cuenta, como listar Templates y crear o supervisar Assemblies, requieren autenticación. Para esas acciones, usa Authorization: Bearer <token> y genera 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 luego entrégaselo al entorno de ejecución del agente. Puedes generarlo 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 luego llama a client.mintBearerToken({ aud: 'mcp' })

Uso del token

Pasa el token como Authorization: Bearer <access_token> en las solicitudes a la API. Cuando una solicitud se autentica con un token Bearer válido, API2 considera satisfecho el requisito de Signature Authentication y omite la validación de la Signature. Signature Authentication solo se exige para las solicitudes con clave/secreto. Las comprobaciones de ámbito siguen aplicándose. La audiencia predeterminada api2 se acepta en los endpoints habituales de API2 y es válida durante 21.600 segundos de forma predeterminada. La audiencia mcp se acepta en el servidor MCP, que la transmite a API2 con una credencial de servicio; los endpoints habituales de API2 la rechazan cuando se presenta directamente, y es válida durante 604.800 segundos de forma predeterminada. Toma como definitivo el valor expires_in de la respuesta.

Ejemplos de configuración de clientes

Mantén los tokens Bearer fuera del control de versiones y de la configuración compartida. Usa el almacenamiento de secretos o la compatibilidad con variables de entorno de tu cliente en lugar de incluir un token real en un commit.

Claude Code

Usa esta entrada de servidor remoto en el .mcp.json del proyecto de Claude Code. Su valor de transporte HTTP es http. En el entorno desde el que se inicia Claude Code, define TRANSLOADIT_API2_BEARER_TOKEN con el token de API2 que generaste; la configuración siguiente expande esa variable en tiempo de ejecución. Consulta la documentación de MCP de Claude Code.

{
  "mcpServers": {
    "transloadit": {
      "type": "http",
      "url": "https://api2.transloadit.com/mcp",
      "headers": {
        "Authorization": "Bearer ${TRANSLOADIT_API2_BEARER_TOKEN}"
      }
    }
  }
}

Claude Desktop

Claude Desktop usa una configuración independiente. Configura el servidor stdio autoalojado anterior como servidor MCP local mediante su configuración claude_desktop_config.json. Los servidores remotos se gestionan desde Settings → Connectors; el JSON de Claude Code anterior no es una configuración de Claude Desktop. Consulta la documentación de conectores personalizados de Claude para conocer las opciones de autenticación remota compatibles. El ejemplo alojado de aquí requiere un cliente que pueda enviar el encabezado Bearer especificado.

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 de HTTP transmisible (streamable HTTP) y el mismo 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 include_content opcional.

Archivos de entrada y límites

transloadit_create_assembly admite tres tipos de entrada:

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

Límites y valores predeterminados:

  • Límite predeterminado del cuerpo de la solicitud en el modo alojado: 1 MB
  • Límite predeterminado del cuerpo de la solicitud en el modo autoalojado: 10 MB (configurable)
  • maxBase64Bytes predeterminado: 512.000 bytes decodificados

Para archivos más grandes, es preferible usar entradas path o url.

Comportamiento con URL y Templates

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

  • Si existe un Step /http/import, establece o sobrescribe el url de ese Step.
  • Si el Template espera subidas (:original o /upload/handle), descarga los archivos y luego los sube mediante el protocolo tus.
  • Si el Template no acepta entradas de archivos, las entradas de URL se ignoran con una advertencia.
  • Si un Template prohíbe sobrescribir Steps y solo admite /http/import, las entradas de URL se rechazan.

Acceso a archivos: local frente a alojado

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, entradas base64 pequeñas o sube los archivos fuera de banda con la CLI de Transloadit. Usa expected_uploads cuando quieras que una Assembly permanezca abierta para subidas posteriores mediante el protocolo tus.

Métricas y tarjeta del servidor

Los despliegues HTTP incluyen:

  • Métricas de Prometheus en GET /metrics (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, desactivar las métricas (metricsPath: false) y configurar restricciones de CORS y de 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 generar automáticamente e inyectar un token Bearer de corta duración y con ámbito limitado para las URL de MCP alojadas por Transloadit que cumplan los requisitos. Si ya proporcionas Authorization en mcp_servers[].headers, API2 lo deja intacto.