Servidor MCP

El Servidor MCP de Transloadit permite que los clientes de agentes llamen directamente a las herramientas de Transloadit: crear y monitorear Assemblies, validar Assembly Instructions, descubrir Robots y Templates, y mostrar los resultados en el chat.

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

Elige cómo conectarte

• Conectar mediante URL (recomendado): agrega https://api2.transloadit.com/mcp a tu cliente de agente y aprueba el acceso en tu navegador. No hay nada que instalar ni claves que copiar.
• CI y clientes sin interfaz: donde nadie puede aprobar en un navegador, envía un token Bearer generado a partir de una Auth Key.
• Autohospedado: ejecuta el servidor tú mismo con TRANSLOADIT_KEY y TRANSLOADIT_SECRET, junto a tu agente.

Dos formas de conectarte

Las apps acceden a tu cuenta de Transloadit de una de dos formas. Ambas envían una credencial con cada solicitud, pero difieren en quién la crea, qué permite hacer y cómo revocas el acceso.

• OAuth (conectar mediante URL): pegas https://api2.transloadit.com/mcp en la app y apruebas la pantalla de consentimiento de Transloadit para un Workspace. La app obtiene su propio acceso limitado (assemblies:read, assemblies:write y templates:read), que se renueva por sí solo y que puedes revocar por separado. No hay nada que copiar, y la app aparece en Aplicaciones conectadas. Las apps de chat alojadas, como ChatGPT y Claude, necesitan esta opción porque no pueden enviar encabezados personalizados.
• Auth Key o token Bearer: copias una Auth Key, o un token Bearer generado a partir de ella, en la herramienta. Esta puede hacer todo lo que permita la clave hasta que la elimines, y no aparece en Aplicaciones conectadas. Es la opción adecuada para tu propio backend, scripts, CI, un servidor MCP autohospedado e integraciones como Zapier.

Cuándo usar cada opción

• Usa OAuth cuando una persona conecte un cliente de agente, como ChatGPT, Claude, Codex, Cursor o VS Code. Consulta Conéctate mediante URL.
• Usa una Auth Key o un token Bearer para el código que ejecutas tú mismo y para herramientas que solicitan una clave. Consulta CI y clientes sin interfaz y Autohospedado.

Conectar mediante URL

El servidor alojado se encuentra en:

https://api2.transloadit.com/mcp

Agrega esta URL a tu cliente MCP. El cliente descubre la API de Transloadit como su servidor de autorización OAuth, abre una página de consentimiento en el Transloadit Console y luego conserva un token de acceso más un token de actualización por ti. Tu Auth Secret nunca sale de tu cuenta.

El endpoint alojado te pide iniciar sesión antes de que se ejecute cualquier herramienta, incluidos los documentos de Robots y la validación, porque los clientes MCP solo inician OAuth cuando el endpoint lo solicita. Para usar los documentos de Robots y la validación sin una cuenta, ejecuta el servidor tú mismo.

La página de consentimiento

Cuando te conectas, tu navegador abre la página de consentimiento. Nombra la app, muestra adónde te redirige y enumera los permisos que solicita. Elige el Workspace que la app puede usar y apruébalo.

Aprobar crea una Auth Key dedicada en ese Workspace, limitada a los permisos mostrados. Su descripción es el nombre de la app seguido de via OAuth y la fecha. Una conexión MCP obtiene como máximo assemblies:write, assemblies:read y templates:read. La página de consentimiento muestra cuánto dura cada token de acceso (una semana para el Servidor MCP); la app lo renueva por sí sola. Para revocar el acceso, abre Aplicaciones conectadas en el Console, donde se enumeran todas las apps que aprobaste, con sus permisos y cuándo se usaron por última vez. Al revocar el acceso allí, la app lo pierde de inmediato.

Claude Code

claude mcp add --transport http transloadit https://api2.transloadit.com/mcp

Luego ejecuta /mcp en Claude Code, selecciona transloadit y autentícate, o ejecuta claude mcp login transloadit desde tu shell. De cualquier forma, tu navegador abrirá la página de consentimiento.

Para ejecuciones no interactivas, como claude -p, permite las herramientas de Transloadit explícitamente:

claude -p "List my Templates" \
  --allowedTools 'mcp__transloadit__*' \
  --output-format json

Claude.ai y Claude Desktop

Ve a Settings → Connectors → Add custom connector e ingresa https://api2.transloadit.com/mcp. Claude se identifica ante la API de Transloadit y abre la página de consentimiento. Consulta la documentación de conectores personalizados de Claude⁠ para más detalles.

ChatGPT

Ve a Settings → Apps & Connectors → Advanced, activa Developer mode y crea una app con la URL de arriba. Configura su autenticación como OAuth. ChatGPT pasa los archivos que adjuntas en el chat a Transloadit por ti, y muestra los resultados en el widget de resultados.

ChatGPT conserva una instantánea de la lista de herramientas del momento en que creaste la app. Después de que agreguemos herramientas, abre la configuración de la app en ChatGPT y haz clic en Refresh tools para incorporarlas.

Codex

codex mcp add transloadit --url https://api2.transloadit.com/mcp

Codex abre la página de consentimiento de inmediato. Para iniciar sesión de nuevo más adelante, ejecuta codex mcp login transloadit.

También puedes agregar el servidor a ~/.codex/config.toml:

[mcp_servers.transloadit]
url = "https://api2.transloadit.com/mcp"

Cursor

Agrega el servidor a ~/.cursor/mcp.json:

{
  "mcpServers": {
    "transloadit": {
      "url": "https://api2.transloadit.com/mcp"
    }
  }
}

VS Code / Copilot

Agrega el servidor a tu configuración de MCP, por ejemplo .vscode/mcp.json:

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

Superficie de herramientas

El endpoint alojado te pide iniciar sesión antes de que se ejecute cualquier herramienta; las herramientas marcadas con «No» funcionan sin una cuenta en un servidor autohospedado.

transloadit_create_assembly es la única herramienta marcada como destructiva: los Robots de exportación como /s3/store pueden sobrescribir archivos en su destino, por lo que los clientes pueden pedirte que lo confirmes.

transloadit_list_templates admite include_builtin (all, latest, exclusively-all, exclusively-latest) y opcionalmente include_content. transloadit_get_profile devuelve el ID del Workspace detrás de las credenciales actuales, además de su nombre cuando Transloadit puede determinarlo, e informa mcp_profile_unavailable para un Workspace sin Assemblies ni Templates todavía.

Archivos de entrada

transloadit_create_assembly acepta archivos de estas formas:

• URL públicas (files con kind: 'url'): el servidor los importa o descarga, consulta comportamiento de URL y Template.
• Archivos en línea pequeños (files con kind: 'base64'): solo son prácticos para archivos pequeños, consulta Límites.
• Adjuntos de ChatGPT (attachments): ChatGPT pasa automáticamente los archivos que adjuntas en el chat. Cada uno se convierte en una entrada de URL llamada attachment_1, attachment_2, y así sucesivamente.
• Archivos que solo existen en el sandbox del agente o en tu máquina: crea la Assembly con expected_uploads y permite que el agente los suba, como se describe a continuación.

Las rutas de archivos locales no se aceptan como entradas de herramienta, tampoco en un servidor autohospedado. Para subir desde tu propia máquina, también puedes usar npx -y @transloadit/node upload.

Archivos en el sandbox de un agente

Algunos clientes, como Claude.ai, no entregan los adjuntos del chat a las herramientas del conector, y el base64 en los argumentos de la herramienta solo funciona para archivos muy pequeños. El agente entonces sube el archivo desde su propio sandbox:

1. Llama a transloadit_create_assembly con tus instrucciones y expected_uploads establecido en el número de archivos (como máximo 100 por llamada). La llamada devuelve el resultado de inmediato, incluso con wait_for_completion: true, porque la Assembly ahora espera esas subidas.

   {
     "instructions": {
       "steps": {
         ":original": { "robot": "/upload/handle" },
         "resized": { "robot": "/image/resize", "use": ":original", "width": 200 }
       }
     },
     "expected_uploads": 1
   }
   

2. Cada entrada en upload_instructions tiene el endpoint del protocolo tus, los metadatos del protocolo tus y un comando curl listo para ejecutar. El agente establece FILE en la ruta del archivo y ejecuta el comando en un shell bash. Imprime 201 una vez que el archivo se subió.

3. Llama a transloadit_wait_for_assembly con la URL de la Assembly.

Los comandos no contienen credenciales, pero mantén privada la URL de la Assembly: quien la tenga puede agregar archivos mientras la Assembly espera subidas, leer su estado y resultados, y cancelarla.

El sandbox necesita acceso HTTPS saliente a Transloadit. En Claude.ai, ve a Settings → Capabilities, activa el acceso a la red para la ejecución de código y agrega *.transloadit.com a los dominios adicionales permitidos. Agrega también *.transloadit.net si el agente debe descargar los resultados de vuelta a su sandbox.

Widget de resultados

transloadit_create_assembly y transloadit_wait_for_assembly enlazan el recurso MCP Apps ui://transloadit/assembly-result. Los clientes que admiten MCP Apps, como ChatGPT y Claude, muestran la Assembly como una tarjeta en el chat. Otros clientes reciben los mismos resultados como salida de herramienta normal.

• Estado: una etiqueta legible como Completed, Processing, Waiting for uploads o Failed. Una Assembly fallida también muestra su mensaje de error y su código. Mientras la Assembly se ejecuta, una nota indica que los archivos de resultados aparecen cuando termina.
• ID de la Assembly: enlaza a la Assembly en el Console.
• Acceso directo a Template: Save as Template abre un nuevo Template en el Console, creado a partir de las instrucciones de la Assembly. La tarjeta no lo ofrece para Assemblies fallidas, Assemblies que aún esperan subidas ni Assemblies cuyo estado no se pudo leer.
• Resultados: cuando varios Steps produjeron cada uno uno o dos archivos, todos los resultados comparten una sola cuadrícula y cada tarjeta nombra el Step que lo generó. De lo contrario, cada Step tiene su propia sección con su Robot y el número de archivos. Una tarjeta muestra el nombre del archivo, sus dimensiones y tamaño (o su tipo MIME), una vista previa y un botón de descarga. Las vistas previas de imagen y video conservan su tamaño mientras cargan, y los videos se reproducen en línea.
• Audio: cada archivo de audio es una fila de ancho completo con un reproductor.
• Subidas: los archivos que subiste se agrupan en una fila Uploaded files al final.
• Resultados largos: un Step muestra hasta 8 archivos y la tarjeta hasta 12; el resto se agrupa tras Show N more. La tarjeta limita su altura a lo que permite el cliente, o a 720 píxeles, y se desplaza, con un degradado que indica cuántos archivos hay debajo.
• Tema: la tarjeta sigue el tema claro u oscuro del cliente.

CI y clientes sin interfaz

Donde nadie puede aprobar el acceso en un navegador, como en trabajos de CI, servidores o entornos de ejecución de agentes, genera un token Bearer a partir de una Auth Key y envíalo como Authorization: Bearer <token>:

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

Genera este token en un entorno de confianza (backend, CI o shell local), y luego entrégalo 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' })

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

Claude Code con un token Bearer

Usa esta entrada de servidor remoto en el .mcp.json de proyecto de Claude Code. Su valor de transporte HTTP es http. Establece TRANSLOADIT_API2_BEARER_TOKEN en tu token de API2 generado, en el entorno que inicia Claude Code; 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}"
      }
    }
  }
}

Otros clientes que te permiten establecer encabezados de solicitud para un servidor MCP remoto usan el mismo encabezado Authorization.

Autohospedado

Ejecuta el servidor donde se ejecuta tu agente y establece TRANSLOADIT_KEY y TRANSLOADIT_SECRET; el servidor entonces maneja la autenticación para las llamadas a la API automáticamente.

Stdio

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

La mayoría de los clientes inician el servidor por ti. Por ejemplo, en Claude Code:

claude mcp add --transport stdio transloadit \
  --env TRANSLOADIT_KEY=MY_AUTH_KEY \
  --env TRANSLOADIT_SECRET=MY_SECRET_KEY \
  -- npx -y @transloadit/mcp-server stdio

O en Codex:

codex mcp add transloadit \
  --env TRANSLOADIT_KEY=MY_AUTH_KEY \
  --env 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

El modo http usa por defecto la ruta /mcp.

Docker

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

La imagen inicia el modo stdio. Para el modo HTTP, anula el punto de entrada y expón el puerto. Vincularse a 0.0.0.0 requiere un TRANSLOADIT_MCP_TOKEN, que los clientes entonces envían como Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>:

export TRANSLOADIT_MCP_TOKEN="$(openssl rand -hex 32)"
docker run --rm \
  -e TRANSLOADIT_KEY=MY_AUTH_KEY \
  -e TRANSLOADIT_SECRET=MY_SECRET_KEY \
  -e TRANSLOADIT_MCP_TOKEN \
  -p 5723:5723 \
  --entrypoint transloadit-mcp \
  ghcr.io/transloadit/mcp-server:latest \
  http --host 0.0.0.0 --port 5723

Algoritmo de firma

Establece TRANSLOADIT_SIGNATURE_ALGORITHM en el algoritmo con el que está configurada tu Auth Key; el fragmento de código del Console para la clave lo muestra. Las claves creadas en el Console con Allow signing Smart CDN URLs activado (el valor predeterminado) usan sha256, y el servidor usa de forma predeterminada sha384. Una discrepancia falla con mcp_invalid_signature, y su sugerencia nombra el algoritmo que la clave requiere.

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 la 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 genera mediante /token.
• Es independiente de los tokens Bearer de API2 usados 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

Configuración del widget de resultados

El widget de resultados puede cargar vistas previas desde https://*.transloadit.com, https://*.transloadit.net y https://*.r2.dev. Anula esa lista con TRANSLOADIT_MCP_RESULT_DOMAINS (orígenes separados por comas). Sus enlaces del Console apuntan a https://transloadit.com; cambia eso con TRANSLOADIT_MCP_CONSOLE_URL.

Límites

Estos límites se aplican a los payloads JSON en línea y base64:

• Límite del cuerpo de solicitud alojado: 1 MiB
• maxBase64Bytes: 512.000 bytes decodificados, alojado y autohospedado
• Límite predeterminado del cuerpo de solicitud autohospedado: 10 MiB (configurable con maxRequestBodyBytes)

Las entradas de URL que el servidor descarga (para Templates que esperan subidas) están limitadas a 1 GiB en total por llamada y 10 minutos por descarga. Para archivos más grandes, usa una URL pública con un Step /http/import, sube desde el sandbox del agente, o sube desde tu propia máquina con npx -y @transloadit/node upload.

Comportamiento de URL y Template

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

• Si existe un Step /http/import, establece/sobrescribe el url de ese Step.
• Si el Template espera subidas (:original o /upload/handle), descarga y luego sube mediante el protocolo tus. Estas descargas requieren URL HTTP(S) públicas; se rechazan los destinos de red privada, incluidas las redirecciones a direcciones privadas.
• Si el Template no acepta entradas de archivo, 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.

Métricas y tarjeta del servidor

Los despliegues HTTP incluyen:

• Métricas de Prometheus en GET /metrics (predeterminado)
• Autenticación opcional de 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, que enumera cada herramienta con sus anotaciones y esquemas de seguridad

Puedes personalizar metricsPath, desactivar 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 generar e inyectar automáticamente un token Bearer con ámbito limitado y de corta duración para las URL MCP alojadas por Transloadit que sean elegibles. Si ya proporcionas Authorization en mcp_servers[].headers, API2 lo deja sin modificar.

Documentación relacionada

• Agentes de IA
• Autenticación
• Crea un token Bearer (POST /token)
• README del Servidor MCP⁠