# Servidor MCP

[transloadit/node-sdk](https://github.com/transloadit/node-sdk/tree/main/packages/mcp-server)

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](/_next/static/media/mcp-demo.0_tw8arokc4ks.gif?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

## 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)

### Stdio (recomendado)

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

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

```

### HTTP

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

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

```

### Docker

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```bash
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`.

###### Nota

Si vinculas el modo HTTP a un host distinto de localhost, configura `TRANSLOADIT_MCP_TOKEN` para exigir autenticación Bearer en las solicitudes 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:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```bash
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:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```plaintext
https://api2.transloadit.com/mcp

```

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

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```bash
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](/es/docs/api/token-post.md)
* 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

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

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

```

### VS Code / Copilot

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```json
{
  "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:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_3z41v8VuCJJKgtsQfSKB6o2uiSXL)

```json
{
  "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.

## Documentación relacionada

* [Agentes de IA](/es/docs/topics/ai-agents.md)
* [Autenticación](/es/docs/api/authentication.md)
* [Crea un token Bearer (POST /token)](/es/docs/api/token-post.md)
* [README del servidor MCP](https://github.com/transloadit/node-sdk/tree/main/packages/mcp-server)