Serveur MCP

Le serveur MCP Transloadit permet aux clients d’agents d’appeler directement les outils Transloadit : créer et suivre des Assemblies, valider (lint) des Assembly Instructions, découvrir les Robots et les Templates, et afficher les résultats dans le chat.

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

Choisir le mode de connexion

Connexion par URL (recommandé) : ajoutez https://api2.transloadit.com/mcp à votre client d’agent et approuvez l’accès dans votre navigateur. Il n’y a rien à installer et aucune clé à copier.
CI et clients sans interface : lorsque personne ne peut approuver dans un navigateur, envoyez un jeton Bearer généré à partir d’une Auth Key.
Auto-hébergé : exécutez vous-même le serveur avec TRANSLOADIT_KEY et TRANSLOADIT_SECRET, à côté de votre agent.

Se connecter par URL

Le serveur hébergé se trouve à l’adresse :

https://api2.transloadit.com/mcp

Ajoutez cette URL à votre client MCP. Le client identifie l’API Transloadit comme son serveur d’autorisation OAuth, ouvre une page de consentement dans la Transloadit Console, puis conserve pour vous un jeton d’accès ainsi qu’un jeton d’actualisation. Votre Auth Secret ne quitte jamais votre compte.

Le point de terminaison hébergé vous demande de vous connecter avant l’exécution de tout outil, y compris la documentation des Robots et le linting, car les clients MCP ne lancent OAuth que lorsque le point de terminaison le leur demande. Pour utiliser la documentation des Robots et le linting sans compte, exécutez le serveur vous-même.

Lorsque vous vous connectez, votre navigateur ouvre la page de consentement. Elle indique le nom de l’application, l’adresse vers laquelle elle vous renvoie et les autorisations qu’elle demande. Choisissez le Workspace que l’application peut utiliser, puis approuvez.

L’approbation crée une Auth Key dédiée dans ce Workspace, limitée aux autorisations affichées. Sa description reprend le nom de l’application, suivi de via OAuth et de la date. Une connexion MCP obtient au plus assemblies:write, assemblies:read et templates:read. La page de consentement indique la durée de validité de chaque jeton d’accès (une semaine pour le serveur MCP) ; l’application le renouvelle d’elle-même. Pour révoquer l’accès, ouvrez Applications connectées dans la Console, qui liste chaque application que vous avez approuvée avec ses autorisations et sa dernière utilisation. La révoquer depuis là met fin immédiatement à l’accès de l’application.

Claude Code

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

Exécutez ensuite /mcp dans Claude Code, sélectionnez transloadit et authentifiez-vous, ou exécutez claude mcp login transloadit depuis votre shell. Dans les deux cas, votre navigateur ouvre la page de consentement.

Pour les exécutions non interactives, comme claude -p, autorisez explicitement les outils Transloadit :

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

Claude.ai et Claude Desktop

Accédez à Settings → Connectors → Add custom connector et saisissez https://api2.transloadit.com/mcp. Claude s’identifie auprès de l’API Transloadit et ouvre la page de consentement. Consultez la documentation de Claude sur les connecteurs personnalisés pour plus de détails.

ChatGPT

Accédez à Settings → Apps & Connectors → Advanced, activez Developer mode et créez une application avec l’URL ci-dessus. Définissez son authentification sur OAuth. ChatGPT transmet pour vous à Transloadit les fichiers que vous joignez dans le chat et affiche les résultats dans le widget de résultats.

Codex

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

Codex ouvre immédiatement la page de consentement. Pour vous reconnecter plus tard, exécutez codex mcp login transloadit.

Vous pouvez aussi ajouter le serveur à ~/.codex/config.toml :

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

Cursor

Ajoutez le serveur à ~/.cursor/mcp.json :

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

VS Code / Copilot

Ajoutez le serveur à votre configuration MCP, par exemple .vscode/mcp.json :

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

Surface des outils

Outil	Compte requis	Scopes OAuth	Remarques
`transloadit_lint_assembly_instructions`	Non	Aucun	Lecture seule
`transloadit_list_robots`	Non	Aucun	Lecture seule
`transloadit_get_robot_help`	Non	Aucun	Lecture seule
`transloadit_create_assembly`	Oui	`assemblies:write`, `templates:read`	Destructif ; widget de résultats
`transloadit_get_assembly_status`	Oui	`assemblies:read`	Lecture seule
`transloadit_wait_for_assembly`	Oui	`assemblies:read`	Lecture seule ; widget de résultats
`transloadit_list_templates`	Oui	`templates:read`	Lecture seule
`transloadit_get_profile`	Oui	`assemblies:read`, `templates:read`	Lecture seule

Le point de terminaison hébergé vous demande de vous connecter avant l’exécution de tout outil ; les outils marqués « Non » fonctionnent sans compte sur un serveur auto-hébergé.

transloadit_create_assembly est le seul outil marqué comme destructif : les Robots d’export tels que /s3/store peuvent écraser des fichiers à leur destination, si bien que les clients peuvent vous demander de le confirmer.

transloadit_list_templates prend en charge include_builtin (all, latest, exclusively-all, exclusively-latest) ainsi que include_content, facultatif. transloadit_get_profile renvoie l’ID du Workspace associé aux informations d’identification actuelles, ainsi que son nom quand Transloadit peut le déterminer, et indique mcp_profile_unavailable pour un Workspace sans Assemblies ni Templates pour l’instant.

Fichiers d’entrée

transloadit_create_assembly accepte des fichiers des manières suivantes :

URL publiques (files avec kind: 'url') : le serveur les importe ou les télécharge, voir Comportement des URL et des Templates.
Petits fichiers intégrés (files avec kind: 'base64') : pratique uniquement pour les petits fichiers, voir Limites.
Pièces jointes ChatGPT (attachments) : ChatGPT transmet automatiquement les fichiers que vous joignez dans le chat. Chacun devient une entrée URL nommée attachment_1, attachment_2, etc.
Fichiers qui n’existent que dans le bac à sable de l’agent ou sur votre machine : créez l’Assembly avec expected_uploads et laissez l’agent les téléverser, comme décrit ci-dessous.

Les chemins de fichiers locaux ne sont pas acceptés comme entrées d’outil, pas même par un serveur auto-hébergé. Pour téléverser depuis votre propre machine, vous pouvez aussi utiliser npx -y @transloadit/node upload.

Fichiers dans le bac à sable d’un agent

Certains clients, comme Claude.ai, ne transmettent pas les pièces jointes du chat aux outils des connecteurs, et le base64 dans les arguments d’outil ne fonctionne que pour de très petits fichiers. L’agent téléverse alors le fichier depuis son propre bac à sable :

Appelez transloadit_create_assembly avec vos instructions et expected_uploads défini sur le nombre de fichiers (100 au maximum par appel). L’appel rend la main immédiatement, même avec wait_for_completion: true, car l’Assembly attend désormais ces téléversements.
```
{
  "instructions": {
    "steps": {
      ":original": { "robot": "/upload/handle" },
      "resized": { "robot": "/image/resize", "use": ":original", "width": 200 }
    }
  },
  "expected_uploads": 1
}
```
Chaque entrée de upload_instructions contient le point de terminaison tus, les métadonnées tus et une commande curl prête à l’emploi. L’agent définit FILE sur le chemin du fichier et exécute la commande dans un shell bash. Elle affiche 201 une fois le fichier téléversé.
Appelez transloadit_wait_for_assembly avec l’URL de l’Assembly.

Les commandes ne contiennent aucune information d’identification, mais gardez l’URL de l’Assembly privée : quiconque la détient peut ajouter des fichiers tant que l’Assembly attend des téléversements, lire son statut et ses résultats, et l’annuler.

Le bac à sable a besoin d’un accès HTTPS sortant vers Transloadit. Sur Claude.ai, ouvrez Settings → Capabilities, activez l’accès réseau sortant pour l’exécution de code, et ajoutez *.transloadit.com aux domaines supplémentaires autorisés. Ajoutez aussi *.transloadit.net si l’agent doit retélécharger les résultats dans son bac à sable.

transloadit_create_assembly et transloadit_wait_for_assembly renvoient vers la ressource MCP Apps ui://transloadit/assembly-result. Les clients qui prennent en charge MCP Apps, comme ChatGPT et Claude, affichent l’Assembly sous forme de carte dans le chat. Les autres clients reçoivent les mêmes résultats sous forme de sortie d’outil classique.

Statut : une étiquette lisible telle que Completed, Processing, Waiting for uploads ou Failed. Un Assembly en échec affiche aussi son message d’erreur et son code. Pendant l’exécution de l’Assembly, une note indique que les fichiers de résultat apparaissent à la fin de l’exécution.
ID de l’Assembly : renvoie vers l’Assembly dans la Console.
Raccourci Template : Save as Template ouvre un nouveau Template dans la Console, prérempli avec les instructions de l’Assembly. La carte ne le propose pas pour les Assemblies en échec, ceux qui attendent encore des téléversements ou ceux dont le statut n’a pas pu être lu.
Résultats : lorsque plusieurs Steps ont chacun produit un ou deux fichiers, tous les résultats partagent une même grille et chaque carte indique le Step qui l’a produite. Sinon, chaque Step a sa propre section avec son Robot et le nombre de fichiers. Une carte affiche le nom du fichier, ses dimensions et sa taille (ou son type MIME), un aperçu et un bouton de téléchargement. Les aperçus d’images et de vidéos conservent leur taille pendant le chargement, et les vidéos sont lues directement dans la carte.
Audio : chaque fichier audio occupe une ligne pleine largeur avec un lecteur.
Téléversements : les fichiers que vous avez téléversés sont regroupés dans une ligne Uploaded files en bas de la carte.
Résultats nombreux : un Step affiche jusqu’à 8 fichiers et la carte jusqu’à 12 ; les autres sont repliés derrière Show N more. La carte limite sa hauteur à ce que le client autorise, ou à 720 pixels, et défile, avec un fondu qui indique combien de fichiers se trouvent plus bas.
Thème : la carte suit le thème clair ou sombre du client.

CI et clients sans interface

Lorsque personne ne peut approuver l’accès dans un navigateur, par exemple dans des Jobs CI, sur des serveurs ou dans des environnements d’exécution d’agents, générez un jeton Bearer à partir d’une Auth Key et envoyez-le sous la forme Authorization: Bearer <token> :

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 le générer 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' })

Utiliser le jeton

Passez le jeton sous la forme Authorization: Bearer <access_token> dans les requêtes API. Lorsqu’une requête est authentifiée avec un jeton porteur valide, API2 considère l’exigence de Signature Authentication comme satisfaite et ignore la validation de la signature. Signature Authentication n’est exigée que pour les requêtes avec clé/secret. Les vérifications de portée continuent de s’appliquer. L’audience par défaut api2 est acceptée par les points de terminaison API2 ordinaires et est valide pendant 21 600 secondes par défaut. L’audience mcp est acceptée par le serveur MCP, qui la relaie à API2 avec des informations d’identification de service ; elle est rejetée par les points de terminaison API2 ordinaires lorsqu’elle est présentée directement, et est valide pendant 604 800 secondes par défaut. Considérez la valeur expires_in de la réponse comme faisant autorité.

Ne versionnez pas les jetons Bearer et ne les placez pas dans une configuration partagée. Utilisez plutôt le stockage de secrets ou les variables d’environnement de votre client au lieu de committer un vrai jeton.

Claude Code avec un jeton Bearer

Utilisez cette entrée de serveur distant dans le fichier .mcp.json du projet Claude Code. Sa valeur de transport HTTP est http. Définissez TRANSLOADIT_API2_BEARER_TOKEN sur votre jeton API2 généré dans l’environnement qui lance Claude Code ; 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}"
      }
    }
  }
}

Les autres clients qui vous permettent de définir des en-têtes de requête pour un serveur MCP distant acceptent le même en-tête Authorization.

Auto-hébergé

Exécutez le serveur là où s’exécute votre agent et définissez TRANSLOADIT_KEY et TRANSLOADIT_SECRET ; le serveur gère alors automatiquement l’authentification des appels API.

Stdio

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

La plupart des clients démarrent le serveur pour vous. Par exemple, dans 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

Ou dans 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

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

Note

Si vous liez le mode HTTP à un hôte autre que localhost, définissez TRANSLOADIT_MCP_TOKEN pour exiger une authentification Bearer pour les requêtes MCP.

Docker

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

L’image démarre en mode stdio. Pour le mode HTTP, remplacez le point d’entrée et exposez le port. La liaison à 0.0.0.0 nécessite un TRANSLOADIT_MCP_TOKEN, que les clients envoient ensuite sous la forme 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

Algorithme de signature

Définissez TRANSLOADIT_SIGNATURE_ALGORITHM sur l’algorithme configuré pour votre Auth Key ; l’extrait de la Console pour cette clé l’indique. Les clés créées dans la Console avec Allow signing Smart CDN URLs activé (par défaut) utilisent sha256, et le serveur utilise par défaut sha384. En cas de non-correspondance, la requête échoue avec mcp_invalid_signature, et l’indication associée nomme l’algorithme requis par la clé.

`TRANSLOADIT_MCP_TOKEN` en détail

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

Définissez-le vous-même sur n’importe quel secret à forte entropie.
Envoyez-le depuis votre client MCP sous la forme Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>.
Il n’est pas généré via /token.
Il est distinct des jetons Bearer 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

Le widget de résultats peut charger des aperçus depuis https://*.transloadit.com, https://*.transloadit.net et https://*.r2.dev. Remplacez cette liste avec TRANSLOADIT_MCP_RESULT_DOMAINS (origines séparées par des virgules). Ses liens vers la Console pointent vers https://transloadit.com ; modifiez cela avec TRANSLOADIT_MCP_CONSOLE_URL.

Limites

Ces limites s’appliquent aux charges utiles JSON et base64 intégrées :

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

Les entrées URL que le serveur télécharge (pour les Templates qui attendent des téléversements) sont plafonnées à 1 GiB au total par appel et à 10 minutes par téléchargement. Pour les fichiers plus volumineux, utilisez une URL publique avec un Step /http/import, téléversez depuis le bac à sable de l’agent ou téléversez depuis votre propre machine avec npx -y @transloadit/node upload.

Comportement des URL et des Templates

Pour les entrées URL, le serveur choisit une méthode sûre 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 puis téléverse via tus. Ces téléchargements exigent des URL HTTP(S) publiques ; les cibles situées sur un réseau privé sont rejetées, y compris les redirections vers des adresses privées.
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.

Métriques et fiche 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 fiche serveur MCP publique sur /.well-known/mcp/server-card.json, qui liste chaque outil avec ses annotations et ses schémas de sécurité

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 générer automatiquement et injecter un jeton Bearer à portée limitée et à courte durée de vie pour les URL MCP éligibles hébergées par Transloadit. Si vous fournissez déjà Authorization dans mcp_servers[].headers, API2 n’y touche pas.

Serveur MCP

Choisir le mode de connexion

Se connecter par URL

Claude Code

Claude.ai et Claude Desktop

ChatGPT

Codex

Cursor

VS Code / Copilot

Surface des outils

Fichiers d’entrée

Fichiers dans le bac à sable d’un agent

Widget de résultats

CI et clients sans interface

Utiliser le jeton

Claude Code avec un jeton Bearer

Auto-hébergé

Stdio

HTTP

Docker

Algorithme de signature

`TRANSLOADIT_MCP_TOKEN` en détail

Paramètres du widget de résultats

Limites

Comportement des URL et des Templates

Métriques et fiche serveur

Utiliser MCP avec `/ai/chat`

Choisir le mode de connexion

Se connecter par URL

La page de consentement

Claude Code

Claude.ai et Claude Desktop

ChatGPT

Codex

Cursor

VS Code / Copilot

Surface des outils

Fichiers d’entrée

Fichiers dans le bac à sable d’un agent

Widget de résultats

CI et clients sans interface

Utiliser le jeton

Claude Code avec un jeton Bearer

Auto-hébergé

Stdio

HTTP

Docker

Algorithme de signature

TRANSLOADIT_MCP_TOKEN en détail

Paramètres du widget de résultats

Limites

Comportement des URL et des Templates

Métriques et fiche serveur

Utiliser MCP avec /ai/chat

Documentation associée

`TRANSLOADIT_MCP_TOKEN` en détail

Utiliser MCP avec `/ai/chat`