Transloadit Media Processing

@transloadit/mcp-server

Transloadit MCP Server (Streamable HTTP + stdio), built on top of @transloadit/node.

Connect by URL (recommended)

The hosted server lives at:

https://api2.transloadit.com/mcp

Add it to your MCP client by URL. The client discovers API2 as the OAuth authorization server, opens a browser consent page in the Transloadit Console, and keeps a short-lived token plus refresh token for you. No API keys leave your Workspace.

The hosted endpoint asks you to sign in before any tool runs, Robot docs and linting included, because MCP clients only start OAuth when the endpoint challenges them. Robot docs and linting ask for no scopes. To use them without an account, run the server yourself (see Self-hosted).

Claude Code

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

claude mcp login transloadit

For non-interactive runs (for example claude -p), explicitly allow MCP tools:

claude -p "List templates" \

--allowedTools mcptransloadit* \ --output-format json

Claude.ai and Claude Desktop

Settings → Connectors → Add custom connector → enter https://api2.transloadit.com/mcp. Claude registers itself with API2 and opens the consent page.

ChatGPT

Settings → Apps & Connectors → Advanced → Developer mode → Create, then enter the URL above with authentication set to OAuth. Files you attach in the chat are handed to transloadit_create_assembly as attachments; results render in the Assembly result widget.

The plugin manifest for the ChatGPT and Codex catalog (plugin.json, mcp.json and the .codex-plugin/plugin.json fallback) lives in this package directory. It points at the hosted server and at the Agent Skills catalog at https://transloadit.com/.well-known/skills/index.json instead of bundling skill files.

Codex

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

Codex opens the consent page right away. To sign in again later, run codex mcp login transloadit.

Or in ~/.codex/config.toml:

[mcp_servers.transloadit]

url = "https://api2.transloadit.com/mcp"

Cursor

~/.cursor/mcp.json:

{

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

MCP Inspector

npx @modelcontextprotocol/inspector --cli https://api2.transloadit.com/mcp

CI and headless agents

Where no browser is available, mint a bearer token from an Auth Key and pass it as Authorization: Bearer :

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 https://api2.transloadit.com/token (HTTP Basic Auth with key/secret)
• Node SDK: instantiate Transloadit with authKey + authSecret, then call client.mintBearerToken({ aud: 'mcp' })

Interactive CLI sessions can also run npx -y @transloadit/node auth login (device flow) and reuse the stored credentials.

Bearer tokens satisfy signature auth on API2 requests; signature checks apply to key/secret requests.

Self-hosted

Run the server where your agent runs, set TRANSLOADIT_KEY and TRANSLOADIT_SECRET, and the server handles API auth automatically.

Install

npm install @transloadit/mcp-server

Stdio

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

Auth Keys sign with one HMAC algorithm. Keys created in the Console with "Allow signing Smart CDN URLs" (the default) require sha256, so add TRANSLOADIT_SIGNATURE_ALGORITHM=sha256, as the Console's snippet for the key shows. Other keys use the default sha384. A mismatch fails with mcp_invalid_signature, and its hint names the algorithm the key requires.

HTTP

TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY \

npx -y @transloadit/mcp-server http --host 127.0.0.1 --port 5723

When binding HTTP mode to non-localhost hosts, TRANSLOADIT_MCP_TOKEN (or the hosted-mode TRANSLOADIT_MCP_RESOURCE_METADATA_URL) is required.

Docker

docker run -i --rm \

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

For HTTP mode via Docker, override the stdio entrypoint, expose the port, and set a transport token, which binding to 0.0.0.0 requires:

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

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 .
• 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

Self-hosted client setup

Most self-hosted users add the server to their MCP client and let the client start it via stdio.

Claude Code

claude mcp add --transport stdio transloadit \

--env TRANSLOADIT_KEY=... \ --env TRANSLOADIT_SECRET=... \ -- npx -y @transloadit/mcp-server stdio

Codex CLI

codex mcp add transloadit \

--env TRANSLOADIT_KEY=... \ --env TRANSLOADIT_SECRET=... \ -- npx -y @transloadit/mcp-server stdio

Allowlist tools in ~/.codex/config.toml:

[mcp_servers.transloadit]

command = "npx" args = ["-y", "@transloadit/mcp-server", "stdio"] enabled_tools = ["transloadit_list_templates"]

Gemini CLI

gemini mcp add --scope user transloadit npx -y @transloadit/mcp-server stdio \

--env TRANSLOADIT_KEY=... \ --env TRANSLOADIT_SECRET=...

Allowlist tools in ~/.gemini/settings.json:

{

"mcpServers": { "transloadit": { "command": "npx", "args": ["-y", "@transloadit/mcp-server", "stdio"], "env": { "TRANSLOADIT_KEY": "...", "TRANSLOADIT_SECRET": "..." }, "includeTools": ["transloadit_list_templates"] } } }

Cursor

~/.cursor/mcp.json:

{

"mcpServers": { "transloadit": { "command": "npx", "args": ["-y", "@transloadit/mcp-server", "stdio"], "env": { "TRANSLOADIT_KEY": "...", "TRANSLOADIT_SECRET": "..." } } } }

OpenCode

~/.config/opencode/opencode.json:

{

"mcp": { "transloadit": { "command": "npx", "args": ["-y", "@transloadit/mcp-server", "stdio"], "env": { "TRANSLOADIT_KEY": "...", "TRANSLOADIT_SECRET": "..." } } } }

Auth model

Hosted (https://api2.transloadit.com/mcp)

• Requests without a bearer token get 401 with WWW-Authenticate: Bearer resource_metadata="https://api2.transloadit.com/.well-known/oauth-protected-resource/mcp". MCP clients follow that document to API2's authorization server (authorization code + PKCE, Dynamic Client Registration or Client ID Metadata Documents).
• This includes a bare GET /mcp, because some clients (Codex) discover the authorization server from that probe. Directory health checks therefore see 401 instead of 200; the JSON body still carries name, status and docs. Self-hosted and unauthenticated deployments keep answering the bare GET with 200.
• Bearer tokens (OAuth or minted with --aud mcp) are forwarded to API2, which verifies them on every call. A rejected or expired token yields a tool result with isError and _meta["mcp/www_authenticate"], so ChatGPT and Claude prompt you to reconnect.
• Each tool declares securitySchemes (top level and in _meta). Because the hosted endpoint challenges every unauthenticated request, all tools declare oauth2 there; the Robot docs and linting tools ask for no scopes.
• A rejected or expired key/secret on a self-hosted server is reported as mcp_credentials_rejected without an OAuth challenge, since only an operator can fix it.
• Browser requests must come from ChatGPT, Claude, Transloadit or loopback origins; requests without an Origin header (CLIs, servers) are not restricted. Set allowedOrigins to change the list.
• TRANSLOADIT_MCP_UPSTREAM_SECRET is set by Transloadit's own deployment so API2 can tell that a relayed aud=mcp token arrives from the hosted service; it is not needed for self-hosting. Hosted mode refuses to start without it, because every authenticated call would fail.

Self-hosted

• Stdio and localhost HTTP need no MCP auth by default.
• Non-localhost HTTP requires TRANSLOADIT_MCP_TOKEN (a static secret you define).
• Live Transloadit API calls use:
• incoming Bearer token from MCP request headers, or
• TRANSLOADIT_KEY + TRANSLOADIT_SECRET.

Configuration

Environment variables

• TRANSLOADIT_KEY
• TRANSLOADIT_SECRET
• TRANSLOADIT_SIGNATURE_ALGORITHM (optional, sha1, sha256 or sha384, default sha384; must match the Auth Key)
• TRANSLOADIT_MCP_TOKEN
• TRANSLOADIT_MCP_RESOURCE_METADATA_URL (hosted mode: protected-resource metadata URL to advertise in 401 challenges)
• TRANSLOADIT_MCP_UPSTREAM_SECRET (hosted mode only, set by Transloadit's deployment; sent to API2 as Transloadit-Mcp-Upstream next to forwarded bearer tokens)
• TRANSLOADIT_MCP_RESULT_DOMAINS (optional, comma-separated origins the result widget may load previews from and link to, either exact such as https://tmp-us-east-1.transloadit.net or with a wildcard host; default https://*.transloadit.com,https://*.transloadit.net,https://*.r2.dev)
• TRANSLOADIT_MCP_WIDGET_DOMAIN (optional, default https://transloadit.com; the origin ChatGPT serves the result widget from, sent as _meta["openai/widgetDomain"])
• TRANSLOADIT_MCP_CONSOLE_URL (optional, default https://transloadit.com; Console origin for widget deep links)
• TRANSLOADIT_ENDPOINT (optional, default https://api2.transloadit.com)
• TRANSLOADIT_MCP_METRICS_PATH (optional, default /metrics)
• TRANSLOADIT_MCP_METRICS_USER (optional)
• TRANSLOADIT_MCP_METRICS_PASSWORD (optional)

CLI flags

• npx -y @transloadit/mcp-server http --host 127.0.0.1 --port 5723
• npx -y @transloadit/mcp-server http --endpoint https://api2.transloadit.com
• npx -y @transloadit/mcp-server http --config path/to/config.json

The JSON config accepts the same keys as createTransloaditMcpHttpHandler(), including allowedOrigins, resourceMetadataUrl, signatureAlgorithm, resultDomains, widgetDomain and consoleUrl.

Tool surface

| transloadit_create_assembly | yes | assemblies:write, templates:read | destructive, open-world (URL imports),