MCP Server

transloadit/node-sdk

The Transloadit MCP Server lets agent clients call Transloadit tools directly: create and monitor Assemblies, lint Assembly Instructions, and discover Robots and Templates.

Choose a deployment mode

Self-hosted (recommended): easiest happy path for most teams. Your MCP process has access to TRANSLOADIT_KEY and TRANSLOADIT_SECRET, so it can handle auth for API calls automatically.
Hosted endpoint: use https://api2.transloadit.com/mcp when you cannot run npx where your agent runs.

Quick start (self-hosted)

Stdio (recommended)

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

http mode defaults to path /mcp.

Note

If you bind HTTP mode to a non-localhost host, set TRANSLOADIT_MCP_TOKEN to require Bearer auth for MCP requests.

`TRANSLOADIT_MCP_TOKEN` explained

TRANSLOADIT_MCP_TOKEN is a self-hosted MCP transport token. It protects your own HTTP MCP endpoint (npx -y @transloadit/mcp-server http), not API2.

Set it yourself to any high-entropy secret.
Send it from your MCP client as Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>.
It is not minted via /token.
It is separate from API2 Bearer tokens used for https://api2.transloadit.com/mcp.

Generate one, then start HTTP mode:

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

Hosted endpoint

If you cannot self-host, point your agent client at:

https://api2.transloadit.com/mcp

Use Authorization: Bearer <token> and mint the token via:

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

Generate this token in a trusted environment (backend, CI, or local shell), then hand it to the agent runtime. You can mint it via:

CLI: npx -y @transloadit/node auth token --aud mcp
API: POST /token
Node.js SDK: instantiate Transloadit with authKey + authSecret, then call client.mintBearerToken({ aud: 'mcp' })

Tokens are valid for six hours (expires_in: 21600). When a request is authenticated with a valid Bearer token, API2 treats Signature Authentication as satisfied and skips signature validation. Signature Authentication remains enforced for key/secret requests.

Client configuration examples

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

Use the same streamable HTTP URL and Authorization header in MCP settings.

Tool surface

The MCP Server exposes these tools:

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 supports include_builtin (all, latest, exclusively-all, exclusively-latest) and optional include_content.

Input files and limits

transloadit_create_assembly supports three input kinds:

path: local files readable by the MCP server process
url: remote files
base64: inline payloads for small files

Limits and defaults:

Hosted default request body limit: 1 MB
Self-hosted default request body limit: 10 MB (configurable)
Default maxBase64Bytes: 512,000 decoded bytes

For larger files, prefer path or url inputs.

URL and template behavior

For URL inputs, the server chooses a safe path based on the target instructions/template:

If an /http/import Step exists, it sets/overrides that Step's url.
If the template expects uploads (:original or /upload/handle), it downloads then uploads via tus.
If the template does not take file inputs, URL inputs are ignored with a warning.
If a template forbids Step overrides and only supports /http/import, URL inputs are rejected.

Local vs hosted file access

path inputs only work when the MCP process can read the same filesystem (local stdio/HTTP). Hosted MCP cannot read your disk.

For remote workflows, use url, small base64, or upload out-of-band with the Transloadit CLI. Use expected_uploads when you want an Assembly to stay open for later tus uploads.

Metrics and server card

HTTP deployments include:

Prometheus metrics at GET /metrics (default)
Optional metrics auth via TRANSLOADIT_MCP_METRICS_USER and TRANSLOADIT_MCP_METRICS_PASSWORD
Public MCP server card at /.well-known/mcp/server-card.json

You can customize metricsPath, disable metrics (metricsPath: false), and configure CORS/host restrictions in the HTTP/Express server options.

Using MCP with `/ai/chat`

/ai/chat can call any MCP server reachable from your environment.

For Transloadit-hosted MCP servers, you can use:

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

With auth: "transloadit", API2 can auto-mint and inject a scoped short-lived Bearer token for eligible Transloadit-hosted MCP URLs. If you already provide Authorization in mcp_servers[].headers, API2 leaves it untouched.