MCP-Server

Der Transloadit MCP-Server ermöglicht es Agent-Clients, Transloadit-Tools direkt aufzurufen: Assemblies erstellen und überwachen, Assembly Instructions linten, Robots und Templates entdecken und die Ergebnisse im Chat anzeigen.

Einen schnellen Überblick darüber, was Agenten mit Transloadit tun können, finden Sie unter Transloadit per MCP.

So verbinden Sie sich

• Per URL verbinden (empfohlen): Fügen Sie https://api2.transloadit.com/mcp in Ihrem Agent-Client hinzu und bestätigen Sie den Zugriff im Browser. Es gibt nichts zu installieren und keine Schlüssel zu kopieren.
• CI und Headless-Clients: Wenn niemand im Browser bestätigen kann, senden Sie ein Bearer-Token, das aus einem Auth Key erzeugt wurde.
• Self-Hosted: Betreiben Sie den Server selbst mit TRANSLOADIT_KEY und TRANSLOADIT_SECRET, direkt neben Ihrem Agenten.

Zwei Verbindungswege

Apps greifen auf zwei Arten auf Ihr Transloadit-Konto zu. Beide senden bei jeder Anfrage Zugangsdaten mit. Sie unterscheiden sich jedoch darin, wer diese erstellt, welche Berechtigungen sie gewähren und wie Sie den Zugriff widerrufen.

• OAuth (per URL verbinden): Sie fügen https://api2.transloadit.com/mcp in die App ein und bestätigen auf der Transloadit-Zustimmungsseite den Zugriff auf einen Workspace. Die App erhält einen eigenen, eingeschränkten Zugriff (assemblies:read, assemblies:write und templates:read), der sich selbst erneuert und den Sie separat widerrufen können. Sie müssen nichts kopieren, und die App wird unter Verbundene Apps aufgeführt. Gehostete Chat-Apps wie ChatGPT und Claude benötigen diesen Weg, da sie keine benutzerdefinierten Header senden können.
• Auth Key oder Bearer-Token: Sie kopieren einen Auth Key oder ein daraus erzeugtes Bearer-Token in das Tool. Es kann alles tun, was der Schlüssel erlaubt, bis Sie diesen löschen, und wird nicht unter Verbundene Apps aufgeführt. Dies ist die richtige Wahl für Ihr eigenes Backend, Skripte, CI, einen selbst gehosteten MCP-Server und Integrationen wie Zapier.

Wann welcher Weg passt

• Verwenden Sie OAuth, wenn eine Person einen Agent-Client wie ChatGPT, Claude, Codex, Cursor oder VS Code verbindet. Siehe Per URL verbinden.
• Verwenden Sie einen Auth Key oder ein Bearer-Token für Code, den Sie selbst ausführen, und für Tools, die einen Schlüssel verlangen. Siehe CI und Headless-Clients und Self-Hosted.

Per URL verbinden

Der gehostete Server befindet sich unter:

https://api2.transloadit.com/mcp

Fügen Sie diese URL in Ihrem MCP-Client hinzu. Der Client erkennt die Transloadit-API als seinen OAuth-Autorisierungsserver, öffnet eine Zustimmungsseite in der Transloadit Console und speichert anschließend ein Access-Token sowie ein Refresh-Token für Sie. Ihr Auth Secret verlässt niemals Ihr Konto.

Der gehostete Endpunkt verlangt eine Anmeldung, bevor ein Tool ausgeführt wird, auch bei Robot-Dokumentation und Linting, weil MCP-Clients OAuth nur starten, wenn der Endpunkt danach fragt. Um Robot-Dokumentation und Linting ohne Konto zu nutzen, betreiben Sie den Server selbst.

Die Zustimmungsseite

Wenn Sie sich verbinden, öffnet Ihr Browser die Zustimmungsseite. Sie nennt die App, zeigt, wohin sie Sie zurückleitet, und listet die angeforderten Berechtigungen auf. Wählen Sie den Workspace, den die App verwenden darf, und bestätigen Sie.

Durch die Bestätigung wird ein dedizierter Auth Key in diesem Workspace erstellt, beschränkt auf die angezeigten Berechtigungen. Seine Beschreibung ist der Name der App, gefolgt von via OAuth und dem Datum. Eine MCP-Verbindung erhält höchstens assemblies:write, assemblies:read und templates:read. Die Zustimmungsseite zeigt, wie lange jedes Access-Token gültig ist (eine Woche beim MCP-Server); die App erneuert es selbstständig. Um den Zugriff zu widerrufen, öffnen Sie Verbundene Apps in der Console, wo jede von Ihnen genehmigte App mit ihren Berechtigungen und dem Zeitpunkt der letzten Nutzung aufgeführt ist. Ein Widerruf dort beendet den Zugriff der App sofort.

Claude Code

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

Führen Sie dann /mcp in Claude Code aus, wählen Sie transloadit und authentifizieren Sie sich, oder führen Sie claude mcp login transloadit in Ihrer Shell aus. In beiden Fällen öffnet Ihr Browser die Zustimmungsseite.

Für nicht interaktive Ausführungen, etwa claude -p, erlauben Sie die Transloadit-Tools explizit:

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

Claude.ai und Claude Desktop

Gehen Sie zu Settings → Connectors → Add custom connector und geben Sie https://api2.transloadit.com/mcp ein. Claude identifiziert sich bei der Transloadit-API und öffnet die Zustimmungsseite. Weitere Details finden Sie in Claudes Dokumentation zu benutzerdefinierten Connectors⁠.

ChatGPT

Gehen Sie zu Settings → Apps & Connectors → Advanced, aktivieren Sie Developer mode und erstellen Sie eine App mit der obigen URL. Setzen Sie ihre Authentifizierung auf OAuth. ChatGPT übergibt Dateien, die Sie im Chat anhängen, automatisch an Transloadit und zeigt Ergebnisse im Ergebnis-Widget an.

ChatGPT speichert die Tool-Liste mit dem Stand, an dem Sie die App erstellt haben. Nachdem wir Tools hinzugefügt haben, öffnen Sie die App-Einstellungen in ChatGPT und klicken Sie auf Refresh tools, um sie zu übernehmen.

Codex

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

Codex öffnet die Zustimmungsseite sofort. Um sich später erneut anzumelden, führen Sie codex mcp login transloadit aus.

Sie können den Server auch zu ~/.codex/config.toml hinzufügen:

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

Cursor

Fügen Sie den Server zu ~/.cursor/mcp.json hinzu:

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

VS Code / Copilot

Fügen Sie den Server zu Ihrer MCP-Konfiguration hinzu, zum Beispiel .vscode/mcp.json:

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

Tool-Übersicht

Der gehostete Endpunkt verlangt eine Anmeldung, bevor ein Tool ausgeführt wird; die mit „Nein“ markierten Tools funktionieren auch ohne Konto auf einem Self-Hosted-Server.

transloadit_create_assembly ist das einzige als destruktiv markierte Tool: Export-Robots wie /s3/store können Dateien an ihrem Ziel überschreiben, daher können Clients Sie um eine Bestätigung bitten.

transloadit_list_templates unterstützt include_builtin (all, latest, exclusively-all, exclusively-latest) und optional include_content. transloadit_get_profile gibt die ID des Workspaces zurück, der zu den aktuellen Zugangsdaten gehört, zusätzlich seinen Namen, wenn Transloadit ihn ermitteln kann, und meldet mcp_profile_unavailable für einen Workspace, der noch keine Assemblies oder Templates hat.

Eingabedateien

transloadit_create_assembly nimmt Dateien auf folgende Arten entgegen:

• Öffentliche URLs (files mit kind: 'url'): Der Server importiert oder lädt sie herunter, siehe URL- und Template-Verhalten.
• Kleine inline Dateien (files mit kind: 'base64'): praktikabel nur für kleine Dateien, siehe Limits.
• ChatGPT-Anhänge (attachments): ChatGPT übergibt Dateien, die Sie im Chat anhängen, automatisch. Jede wird zu einer URL-Eingabe mit dem Namen attachment_1, attachment_2 und so weiter.
• Dateien, die nur in der Sandbox des Agenten oder auf Ihrem eigenen Rechner existieren: Erstellen Sie die Assembly mit expected_uploads und lassen Sie den Agenten sie hochladen, wie unten beschrieben.

Lokale Dateipfade werden nicht als Tool-Eingaben akzeptiert, auch nicht von einem Self-Hosted-Server. Um von Ihrem eigenen Rechner hochzuladen, können Sie auch npx -y @transloadit/node upload verwenden.

Dateien in der Sandbox eines Agenten

Manche Clients, etwa Claude.ai, übergeben Chat-Anhänge nicht an Connector-Tools, und Base64 in Tool-Argumenten funktioniert nur für sehr kleine Dateien. Der Agent lädt die Datei dann aus seiner eigenen Sandbox hoch:

1. Rufen Sie transloadit_create_assembly mit Ihren Anweisungen auf und setzen Sie expected_uploads auf die Anzahl der Dateien (höchstens 100 pro Aufruf). Der Aufruf kehrt sofort zurück, auch mit wait_for_completion: true, weil die Assembly nun auf diese Uploads wartet.

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

2. Jeder Eintrag in upload_instructions enthält den tus-Endpunkt, die tus-Metadaten und einen einsatzbereiten Befehl für curl. Der Agent setzt FILE auf den Pfad der Datei und führt den Befehl in einer Bash-Shell aus. Er gibt 201 aus, sobald die Datei hochgeladen ist.

3. Rufen Sie transloadit_wait_for_assembly mit der Assembly URL auf.

Die Befehle enthalten keine Zugangsdaten, aber halten Sie die Assembly URL geheim: Wer sie besitzt, kann Dateien hinzufügen, während die Assembly auf Uploads wartet, ihren Status und ihre Ergebnisse lesen und sie abbrechen.

Die Sandbox benötigt ausgehenden HTTPS-Zugriff auf Transloadit. Öffnen Sie bei Claude.ai Settings → Capabilities, aktivieren Sie den Netzwerk-Egress für die Code-Ausführung und fügen Sie *.transloadit.com zu den zusätzlich erlaubten Domains hinzu. Fügen Sie auch *.transloadit.net hinzu, falls der Agent Ergebnisse zurück in seine Sandbox herunterladen soll.

Ergebnis-Widget

transloadit_create_assembly und transloadit_wait_for_assembly verknüpfen die MCP-Apps-Ressource ui://transloadit/assembly-result. Clients, die MCP Apps unterstützen, etwa ChatGPT und Claude, zeigen die Assembly als Karte im Chat an. Andere Clients erhalten dieselben Ergebnisse als normale Tool-Ausgabe.

• Status: eine lesbare Bezeichnung wie Completed, Processing, Waiting for uploads oder Failed. Eine fehlgeschlagene Assembly zeigt zusätzlich ihre Fehlermeldung und ihren Code an. Solange die Assembly läuft, weist ein Hinweis darauf hin, dass die Ergebnisdateien nach dem Abschluss erscheinen.
• Assembly ID: verlinkt auf die Assembly in der Console.
• Template-Shortcut: Save as Template öffnet ein neues Template in der Console, vorbefüllt mit den Anweisungen der Assembly. Die Karte bietet ihn nicht für fehlgeschlagene Assemblies, für Assemblies, die noch auf Uploads warten, oder für Assemblies an, deren Status nicht gelesen werden konnte.
• Ergebnisse: Wenn mehrere Steps jeweils eine oder zwei Dateien erzeugt haben, teilen sich alle Ergebnisse ein Raster, und jede Karte nennt den Step, der sie erzeugt hat. Andernfalls erhält jeder Step einen eigenen Abschnitt mit seinem Robot und der Anzahl der Dateien. Eine Karte zeigt den Dateinamen, die Abmessungen und die Größe (oder den MIME-Typ), eine Vorschau und eine Download-Schaltfläche. Bild- und Videovorschauen behalten beim Laden ihre Größe, und Videos werden inline abgespielt.
• Audio: Jede Audiodatei ist eine Zeile in voller Breite mit einem Player.
• Uploads: Die Dateien, die Sie hochgeladen haben, werden unten in einer Uploaded files-Zeile zusammengefasst.
• Lange Ergebnisse: Ein Step zeigt bis zu 8 Dateien und die Karte bis zu 12; der Rest wird hinter Show N more eingeklappt. Die Karte begrenzt ihre Höhe auf das, was der Client erlaubt, oder auf 720 Pixel, und lässt sich scrollen, mit einem Ausblendeffekt, der angibt, wie viele Dateien weiter unten folgen.
• Design: Die Karte folgt dem hellen oder dunklen Design des Clients.

CI und Headless-Clients

Wo niemand den Zugriff im Browser bestätigen kann, etwa in CI-Jobs, auf Servern oder in Agent-Laufzeitumgebungen, erzeugen Sie ein Bearer-Token aus einem Auth Key und senden es als Authorization: Bearer <token>:

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

Erzeugen Sie dieses Token in einer vertrauenswürdigen Umgebung (Backend, CI oder lokale Shell) und übergeben Sie es dann der Agent-Laufzeitumgebung. Sie können es erzeugen über:

• CLI: npx -y @transloadit/node auth token --aud mcp
• API: POST /token
• Node.js SDK: Instanziieren Sie Transloadit mit authKey + authSecret und rufen Sie dann client.mintBearerToken({ aud: 'mcp' }) auf

Halten Sie Bearer-Tokens von Versionskontrolle und geteilten Konfigurationen fern. Verwenden Sie die Secret-Speicherung Ihres Clients oder die Unterstützung für Umgebungsvariablen, statt ein reales Token zu committen.

Claude Code mit einem Bearer-Token

Verwenden Sie diesen Remote-Server-Eintrag in der Projektdatei .mcp.json von Claude Code. Sein HTTP-Transportwert ist http. Setzen Sie TRANSLOADIT_API2_BEARER_TOKEN auf Ihr erzeugtes API2-Token in der Umgebung, die Claude Code startet; die untenstehende Konfiguration erweitert diese Variable zur Laufzeit. Siehe die Claude Code MCP-Dokumentation⁠.

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

Andere Clients, die das Setzen von Request-Headern für einen Remote-MCP-Server erlauben, verwenden denselben Header Authorization.

Self-Hosted

Betreiben Sie den Server dort, wo Ihr Agent läuft, und setzen Sie TRANSLOADIT_KEY und TRANSLOADIT_SECRET; der Server übernimmt dann die Authentifizierung für API-Aufrufe automatisch.

Stdio

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

Die meisten Clients starten den Server für Sie. Zum Beispiel in 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

Oder in 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

Der Modus http verwendet standardmäßig den Pfad /mcp.

Docker

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

Das Image startet den Stdio-Modus. Für den HTTP-Modus überschreiben Sie den Entrypoint und exponieren Sie den Port. Die Bindung an 0.0.0.0 erfordert ein TRANSLOADIT_MCP_TOKEN, das Clients dann als Authorization: Bearer <TRANSLOADIT_MCP_TOKEN> senden:

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

Signaturalgorithmus

Setzen Sie TRANSLOADIT_SIGNATURE_ALGORITHM auf den Algorithmus, für den Ihr Auth Key konfiguriert ist; das Snippet der Console für den Key zeigt ihn an. Schlüssel, die in der Console mit aktiviertem Allow signing Smart CDN URLs (Standardeinstellung) erstellt wurden, verwenden sha256, und der Server verwendet standardmäßig sha384. Eine falsche Zuordnung schlägt mit mcp_invalid_signature fehl, und der Hinweis nennt den vom Key benötigten Algorithmus.

TRANSLOADIT_MCP_TOKEN erklärt

TRANSLOADIT_MCP_TOKEN ist ein Self-Hosted-MCP-Transporttoken. Es schützt Ihren eigenen HTTP-MCP-Endpunkt (npx -y @transloadit/mcp-server http), nicht API2.

• Setzen Sie es selbst auf ein beliebiges hochentropisches Secret.
• Senden Sie es von Ihrem MCP-Client als Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>.
• Es wird nicht über /token erzeugt.
• Es ist getrennt von API2-Bearer-Tokens, die für https://api2.transloadit.com/mcp verwendet werden.

Erzeugen Sie eines und starten Sie dann den HTTP-Modus:

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

Einstellungen des Ergebnis-Widgets

Das Ergebnis-Widget kann Vorschauen von https://*.transloadit.com, https://*.transloadit.net und https://*.r2.dev laden. Überschreiben Sie diese Liste mit TRANSLOADIT_MCP_RESULT_DOMAINS (kommagetrennte Ursprünge). Ihre Console-Links verweisen auf https://transloadit.com; ändern Sie das mit TRANSLOADIT_MCP_CONSOLE_URL.

Limits

Diese Limits gelten für Inline-JSON- und Base64-Payloads:

• Anfragekörper-Limit beim gehosteten Server: 1 MiB
• maxBase64Bytes: 512.000 decodierte Bytes, gehostet und Self-Hosted
• Standard-Anfragekörper-Limit beim Self-Hosted-Server: 10 MiB (konfigurierbar mit maxRequestBodyBytes)

URL-Eingaben, die der Server herunterlädt (für Templates, die Uploads erwarten), sind auf insgesamt 1 GiB pro Aufruf und 10 Minuten pro Download begrenzt. Für größere Dateien verwenden Sie eine öffentliche URL mit einem Step für /http/import, laden Sie aus der Sandbox des Agenten hoch, oder laden Sie von Ihrem eigenen Rechner mit npx -y @transloadit/node upload hoch.

URL- und Template-Verhalten

Bei URL-Eingaben wählt der Server einen sicheren Pfad basierend auf den Zielanweisungen/dem Ziel-Template:

• Wenn ein Step für /http/import existiert, setzt oder überschreibt er dessen url.
• Wenn das Template Uploads erwartet (:original oder /upload/handle), lädt er die Datei herunter und anschließend per tus hoch. Diese Downloads erfordern öffentliche HTTP(S)-URLs; Ziele in privaten Netzwerken werden abgelehnt, einschließlich Weiterleitungen zu privaten Adressen.
• Wenn das Template keine Dateieingaben annimmt, werden URL-Eingaben mit einer Warnung ignoriert.
• Wenn ein Template Step-Überschreibungen verbietet und nur /http/import unterstützt, werden URL-Eingaben abgelehnt.

Metriken und Server-Karte

HTTP-Deployments enthalten:

• Prometheus-Metriken unter GET /metrics (Standard)
• Optionale Metriken-Authentifizierung über TRANSLOADIT_MCP_METRICS_USER und TRANSLOADIT_MCP_METRICS_PASSWORD
• Öffentliche MCP-Server-Karte unter /.well-known/mcp/server-card.json, die jedes Tool mit seinen Annotationen und Sicherheitsschemata auflistet

Sie können metricsPath anpassen, Metriken deaktivieren (metricsPath: false) und CORS-/Host-Beschränkungen in den HTTP/Express-Serveroptionen konfigurieren.

MCP mit /ai/chat verwenden

/ai/chat kann jeden MCP-Server aufrufen, der aus Ihrer Umgebung erreichbar ist.

Für Transloadit-gehostete MCP-Server können Sie Folgendes verwenden:

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

Mit auth: "transloadit" kann API2 automatisch ein zeitlich begrenztes, auf Berechtigungen beschränktes Bearer-Token erzeugen und für geeignete Transloadit-gehostete MCP-URLs einfügen. Wenn Sie bereits Authorization in mcp_servers[].headers angeben, lässt API2 es unverändert.

Verwandte Dokumentation

• KI-Agenten
• Authentifizierung
• Ein Bearer-Token erstellen (POST /token)
• MCP-Server-README⁠