# MCP Server

[transloadit/node-sdk](https://github.com/transloadit/node-sdk/tree/main/packages/mcp-server)

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

![Demo: encoding videos to HLS adaptive streaming through the Transloadit MCP Server in Claude](/_next/static/media/mcp-demo.0_tw8arokc4ks.gif?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

## 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)

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

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

```

### HTTP

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```bash
TRANSLOADIT_KEY=MY_AUTH_KEY TRANSLOADIT_SECRET=MY_SECRET_KEY \
npx -y @transloadit/mcp-server http --host 127.0.0.1 --port 5723

```

### Docker

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```bash
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:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```bash
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:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```text
https://api2.transloadit.com/mcp

```

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

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```bash
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](/docs/api/token-post.md)
* 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

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

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

```

### VS Code / Copilot

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```json
{
  "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:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CtwzFbHWtqiCy9uvWb9fE7WvfP9N)

```json
{
  "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.

## Related docs

* [AI Agents](/docs/topics/ai-agents.md)
* [Authentication](/docs/api/authentication.md)
* [Create a bearer token (POST /token)](/docs/api/token-post.md)
* [MCP Server README](https://github.com/transloadit/node-sdk/tree/main/packages/mcp-server)