Serveur MCP

Le serveur MCP de Transloadit permet aux clients d’agents d’appeler directement les outils Transloadit : créer et suivre des Assemblies, analyser les Assembly Instructions avec un linter, et découvrir les Robots et les Templates.

Pour un aperçu rapide de ce que les agents peuvent faire avec Transloadit, consultez Transloadit via MCP EN (English).

Choisir un mode de déploiement

• Auto-hébergé (recommandé) : le parcours le plus simple pour la plupart des équipes. Votre processus MCP a accès à TRANSLOADIT_KEY et TRANSLOADIT_SECRET, il peut donc gérer automatiquement l’authentification des appels API.
• Point de terminaison hébergé : utilisez https://api2.transloadit.com/mcp lorsque vous ne pouvez pas exécuter npx là où votre agent s’exécute.

Démarrage rapide (auto-hébergé)

Stdio (recommandé)

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

Le mode http utilise par défaut le chemin /mcp.

TRANSLOADIT_MCP_TOKEN expliqué

TRANSLOADIT_MCP_TOKEN est un jeton de transport MCP auto-hébergé. Il protège votre propre point de terminaison HTTP MCP (npx -y @transloadit/mcp-server http), et non API2.

• Définissez-le vous-même avec n’importe quel secret à forte entropie.
• Envoyez-le depuis votre client MCP sous la forme Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>.
• Il n’est pas émis via /token.
• Il est distinct des jetons Bearer d’API2 utilisés pour https://api2.transloadit.com/mcp.

Générez-en un, puis démarrez le mode HTTP :

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

Point de terminaison hébergé

Si vous ne pouvez pas auto-héberger le serveur, pointez votre client d’agent vers :

https://api2.transloadit.com/mcp

La découverte des Robots, l’aide sur les Robots et le lint des Assembly Instructions fonctionnent sans informations d’identification. Les actions liées au compte, notamment lister les Templates et créer ou suivre des Assemblies, nécessitent une authentification. Pour ces actions, utilisez Authorization: Bearer <token> et émettez le jeton via :

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

Générez ce jeton dans un environnement de confiance (backend, CI ou shell local), puis transmettez-le à l’environnement d’exécution de l’agent. Vous pouvez l’émettre via :

• CLI : npx -y @transloadit/node auth token --aud mcp
• API : POST /token
• SDK Node.js : instanciez Transloadit avec authKey + authSecret, puis appelez client.mintBearerToken({ aud: 'mcp' })

Exemples de configuration client

Ne conservez pas les jetons Bearer dans le contrôle de version ni dans une configuration partagée. Utilisez le stockage de secrets de votre client ou sa prise en charge des variables d’environnement plutôt que de committer un vrai jeton.

Claude Code

Utilisez cette entrée de serveur distant dans le fichier .mcp.json du projet Claude Code. Sa valeur de transport HTTP est http. Dans l’environnement qui lance Claude Code, définissez TRANSLOADIT_API2_BEARER_TOKEN sur le jeton API2 que vous avez émis ; la configuration ci-dessous développe cette variable à l’exécution. Consultez la documentation 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 utilise une configuration distincte. Configurez le serveur stdio auto-hébergé ci-dessus comme serveur MCP local à l’aide de sa configuration claude_desktop_config.json. Les serveurs distants se gèrent via Settings → Connectors ; le JSON Claude Code ci-dessus n’est pas une configuration Claude Desktop. Consultez la documentation de Claude sur les connecteurs personnalisés⁠ pour connaître les options d’authentification à distance prises en charge. L’exemple hébergé ici nécessite un client capable d’envoyer l’en-tête Bearer indiqué.

VS Code / Copilot

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

Cursor

Utilisez la même URL HTTP streamable et le même en-tête Authorization dans les paramètres MCP.

Outils exposés

Le serveur MCP expose les outils suivants :

• 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 prend en charge include_builtin (all, latest, exclusively-all, exclusively-latest) ainsi qu’un include_content facultatif.

Fichiers d’entrée et limites

transloadit_create_assembly prend en charge trois types d’entrée :

• path : fichiers locaux lisibles par le processus du serveur MCP
• url : fichiers distants
• base64 : charges utiles intégrées pour les petits fichiers

Limites et valeurs par défaut :

• Limite par défaut du corps de requête en mode hébergé : 1 MB
• Limite par défaut du corps de requête en mode auto-hébergé : 10 MB (configurable)
• maxBase64Bytes par défaut : 512 000 octets décodés

Pour les fichiers plus volumineux, privilégiez les entrées path ou url.

Comportement des URL et des Templates

Pour les entrées URL, le serveur choisit un chemin sûr en fonction des instructions ou du Template cible :

• Si un Step /http/import existe, il définit ou remplace le url de ce Step.
• Si le Template attend des téléversements (:original ou /upload/handle), il télécharge les fichiers puis les téléverse via tus.
• Si le Template n’accepte pas de fichiers en entrée, les entrées URL sont ignorées avec un avertissement.
• Si un Template interdit le remplacement des Steps et ne prend en charge que /http/import, les entrées URL sont rejetées.

Accès aux fichiers en local ou en mode hébergé

Les entrées path ne fonctionnent que lorsque le processus MCP peut lire le même système de fichiers (stdio/HTTP en local). Le MCP hébergé ne peut pas lire votre disque.

Pour les flux de travail distants, utilisez url, de petites entrées base64, ou téléversez hors bande avec la CLI Transloadit. Utilisez expected_uploads lorsque vous souhaitez qu’une Assembly reste ouverte pour des téléversements tus ultérieurs.

Métriques et carte de serveur

Les déploiements HTTP incluent :

• Des métriques Prometheus sur GET /metrics (par défaut)
• Une authentification facultative des métriques via TRANSLOADIT_MCP_METRICS_USER et TRANSLOADIT_MCP_METRICS_PASSWORD
• Une carte de serveur MCP publique sur /.well-known/mcp/server-card.json

Vous pouvez personnaliser metricsPath, désactiver les métriques (metricsPath: false) et configurer les restrictions CORS et d’hôte dans les options du serveur HTTP/Express.

Utiliser MCP avec /ai/chat

/ai/chat peut appeler n’importe quel serveur MCP accessible depuis votre environnement.

Pour les serveurs MCP hébergés par Transloadit, vous pouvez utiliser :

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

Avec auth: "transloadit", API2 peut émettre et injecter automatiquement un jeton Bearer à portée limitée et de courte durée pour les URL MCP éligibles hébergées par Transloadit. Si vous fournissez déjà Authorization dans mcp_servers[].headers, API2 le laisse intact.

Documentation associée

• Agents IA EN (English)
• Authentification
• Créer un jeton Bearer (POST /token)
• README du serveur MCP⁠