MCP Server

transloadit/node-sdk

Mit dem Transloadit MCP Server können Agent-Clients Transloadit-Tools direkt aufrufen: Assemblies erstellen und überwachen, Assembly Instructions prüfen sowie Robots und Templates finden.

Bereitstellungsmodus auswä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 http-Modus verwendet standardmäßig den Pfad /mcp.

Hinweis

Wenn Sie den HTTP-Modus an einen Host außerhalb von localhost binden, legen Sie TRANSLOADIT_MCP_TOKEN fest, um für MCP-Anfragen eine Bearer-Authentifizierung zu verlangen.

Erklärung zu `TRANSLOADIT_MCP_TOKEN`

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

Legen Sie selbst ein beliebiges Geheimnis 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 von API2-Bearer-Tokens getrennt, die für https://api2.transloadit.com/mcp verwendet werden.

Generieren Sie ein Token und starten Sie anschließend 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 den Server nicht selbst hosten können, richten Sie Ihren Agent-Client auf folgende Adresse:

https://api2.transloadit.com/mcp

Verwenden Sie Authorization: Bearer <token> und stellen Sie das Token wie folgt aus:

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

Generieren Sie dieses Token in einer vertrauenswürdigen Umgebung (Backend, CI oder lokale Shell) und übergeben Sie es anschließend an die Agent-Laufzeitumgebung. Sie können es wie folgt 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 anschließend client.mintBearerToken({ aud: 'mcp' }) auf.

Tokens sind sechs Stunden gültig (expires_in: 21600). Wenn eine Anfrage mit einem gültigen Bearer-Token authentifiziert wird, betrachtet API2 die Signature Authentication als erfüllt und überspringt die Signaturprüfung. Für Anfragen mit Schlüssel und Geheimnis bleibt die Signature Authentication erforderlich.

Beispiele für die Client-Konfiguration

Claude Desktop / Claude Code

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

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 streamfähige HTTP-URL und denselben Authorization-Header.

Verfügbare Tools

Der MCP Server stellt folgende 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 Eingabearten:

path: lokale Dateien, die der MCP-Server-Prozess lesen kann
url: entfernte Dateien
base64: Inline-Nutzdaten für kleine Dateien

Limits und Standardwerte:

Standardlimit für den Anfrage-Body beim Hosting: 1 MB
Standardlimit für den Anfrage-Body beim Selbst-Hosting: 10 MB (konfigurierbar)
Standardwert für maxBase64Bytes: 512.000 decodierte Bytes

Verwenden Sie für größere Dateien bevorzugt path- oder url-Eingaben.

URL- und Template-Verhalten

Bei URL-Eingaben wählt der Server anhand der Ziel-Assembly-Instructions bzw. des Ziel-Templates einen sicheren Pfad:

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

Lokaler und gehosteter Dateizugriff

path-Eingaben funktionieren nur, wenn der MCP-Prozess dasselbe Dateisystem lesen kann (lokales stdio/HTTP). Ein gehosteter MCP-Server kann nicht auf Ihren Datenträger zugreifen.

Verwenden Sie für Remote-Workflows url, kleine base64-Nutzdaten 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 umfassen:

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

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 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 begrenztem Berechtigungsumfang ausstellen und einfügen. Wenn Sie bereits Authorization in mcp_servers[].headers angeben, lässt API2 den Wert unverändert.