MCP-Server

Mit dem Transloadit-MCP-Server rufen Agent-Clients Transloadit-Tools direkt auf: Assemblies erstellen und überwachen, Assembly Instructions linten sowie Robots und Templates entdecken.

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

Bereitstellungsmodus wählen

• Selbst gehostet (empfohlen): der einfachste Weg für die meisten Teams. Ihr MCP-Prozess hat Zugriff auf TRANSLOADIT_KEY und TRANSLOADIT_SECRET und kann daher die Authentifizierung für API-Aufrufe automatisch übernehmen.
• Gehosteter Endpunkt: Verwenden Sie https://api2.transloadit.com/mcp, wenn Sie npx nicht dort ausführen können, wo Ihr Agent läuft.

Schnellstart (selbst gehostet)

Stdio (empfohlen)

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

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

TRANSLOADIT_MCP_TOKEN erklärt

TRANSLOADIT_MCP_TOKEN ist ein Transport-Token für selbst gehostete MCP-Server. Es schützt Ihren eigenen HTTP-MCP-Endpunkt (npx -y @transloadit/mcp-server http), nicht API2.

• Legen Sie es selbst als beliebiges Secret mit hoher Entropie fest.
• Senden Sie es von Ihrem MCP-Client als Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>.
• Es wird nicht über /token ausgestellt.
• Es ist unabhängig von den API2-Bearer-Tokens, die für https://api2.transloadit.com/mcp verwendet werden.

Erzeugen Sie ein Token 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

Gehosteter Endpunkt

Wenn Sie nicht selbst hosten können, richten Sie Ihren Agent-Client auf diesen Endpunkt aus:

https://api2.transloadit.com/mcp

Die Suche nach Robots, die Robot-Hilfe und das Linting von Assembly Instructions funktionieren ohne Zugangsdaten. Kontoaktionen, darunter das Auflisten von Templates sowie das Erstellen oder Überwachen von Assemblies, erfordern eine Authentifizierung. Verwenden Sie für diese Aktionen Authorization: Bearer <token> und stellen Sie das Token so aus:

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 anschließend an die Laufzeitumgebung des Agenten. Sie können es auf folgenden Wegen ausstellen:

• 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

Beispiele für die Client-Konfiguration

Halten Sie Bearer-Tokens aus der Versionskontrolle und aus gemeinsam genutzten Konfigurationen heraus. Nutzen Sie den Secret-Speicher oder die Unterstützung für Umgebungsvariablen Ihres Clients, statt ein echtes Token zu committen.

Claude Code

Verwenden Sie diesen Remote-Server-Eintrag in der Projektdatei .mcp.json von Claude Code. Der Wert für den HTTP-Transport lautet http. Setzen Sie TRANSLOADIT_API2_BEARER_TOKEN in der Umgebung, aus der Claude Code gestartet wird, auf Ihr ausgestelltes API2-Token; die folgende Konfiguration löst diese Variable zur Laufzeit auf. Weitere Details finden Sie in der MCP-Dokumentation von Claude Code⁠.

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

Claude Desktop

Claude Desktop wird separat eingerichtet. Konfigurieren Sie den oben beschriebenen selbst gehosteten stdio-Server als lokalen MCP-Server über seine Konfiguration in claude_desktop_config.json. Remote-Server werden über Settings → Connectors verwaltet; das obige JSON für Claude Code ist keine Konfiguration für Claude Desktop. Unterstützte Optionen für die Remote-Authentifizierung finden Sie in der Dokumentation zu benutzerdefinierten Connectors von Claude⁠. Das gehostete Beispiel hier erfordert einen Client, der den angegebenen Bearer-Header senden kann.

VS Code / Copilot

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

Cursor

Verwenden Sie in den MCP-Einstellungen dieselbe Streamable-HTTP-URL und denselben Authorization-Header.

Verfügbare Tools

Der MCP-Server stellt diese Tools bereit:

• 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 unterstützt include_builtin (all, latest, exclusively-all, exclusively-latest) sowie optional include_content.

Eingabedateien und Limits

transloadit_create_assembly unterstützt drei Arten von Eingaben:

• path: lokale Dateien, die der MCP-Serverprozess lesen kann
• url: entfernte Dateien
• base64: Inline-Payloads für kleine Dateien

Limits und Standardwerte:

• Standardlimit für den Anfrage-Body bei gehostetem Betrieb: 1 MB
• Standardlimit für den Anfrage-Body bei selbst gehostetem Betrieb: 10 MB (konfigurierbar)
• Standardwert für maxBase64Bytes: 512.000 decodierte Bytes

Bevorzugen Sie für größere Dateien Eingaben vom Typ path oder url.

Verhalten bei URLs und Templates

Bei URL-Eingaben wählt der Server anhand der Ziel-Anweisungen bzw. des Ziel-Templates einen sicheren Weg:

• Wenn ein Step /http/import vorhanden ist, setzt bzw. überschreibt der Server den Wert url dieses Steps.
• Wenn das Template Uploads erwartet (:original oder /upload/handle), lädt der Server die Dateien herunter und anschließend per tus hoch.
• Wenn das Template keine Dateieingaben annimmt, werden URL-Eingaben mit einer Warnung ignoriert.
• Wenn ein Template das Überschreiben von Steps verbietet und nur /http/import unterstützt, werden URL-Eingaben abgelehnt.

Dateizugriff: lokal oder gehostet

Eingaben vom Typ path funktionieren nur, wenn der MCP-Prozess dasselbe Dateisystem lesen kann (lokales stdio/HTTP). Gehostetes MCP kann Ihre Festplatte nicht lesen.

Verwenden Sie für entfernte Workflows url, kleine Eingaben vom Typ base64 oder laden Sie Dateien separat mit der Transloadit CLI hoch. Verwenden Sie expected_uploads, wenn eine Assembly für spätere tus-Uploads geöffnet bleiben soll.

Metriken und Server-Card

HTTP-Bereitstellungen enthalten:

• Prometheus-Metriken unter GET /metrics (Standard)
• Optionale Authentifizierung für Metriken über TRANSLOADIT_MCP_METRICS_USER und TRANSLOADIT_MCP_METRICS_PASSWORD
• Öffentliche MCP-Server-Card unter /.well-known/mcp/server-card.json

In den Optionen des HTTP/Express-Servers können Sie metricsPath anpassen, Metriken deaktivieren (metricsPath: false) und CORS- bzw. Host-Beschränkungen konfigurieren.

MCP mit /ai/chat verwenden

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

Für von 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 für geeignete, von Transloadit gehostete MCP-URLs automatisch ein kurzlebiges Bearer-Token mit begrenzten Scopes ausstellen und einfügen. Wenn Sie Authorization bereits in mcp_servers[].headers angeben, lässt API2 diesen Wert unverändert.

Weiterführende Dokumentation

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