Servidor MCP

O servidor MCP da Transloadit permite que clientes de agentes chamem ferramentas da Transloadit diretamente: criar e monitorar Assemblies, fazer análise estática das Assembly Instructions, descobrir Robots e Templates e mostrar os resultados no chat.

Para uma visão geral rápida do que os agentes podem fazer com a Transloadit, consulte Transloadit via MCP.

Escolha como se conectar

• Conectar por URL (recomendado): adicione https://api2.transloadit.com/mcp ao seu cliente de agente e aprove o acesso no navegador. Não há nada para instalar nem chaves para copiar.
• CI e clientes sem interface: quando ninguém puder aprovar o acesso em um navegador, envie um token Bearer emitido a partir de uma Auth Key.
• Hospedagem própria: execute o servidor por conta própria com TRANSLOADIT_KEY e TRANSLOADIT_SECRET, junto ao seu agente.

Conectar por URL

O servidor hospedado está disponível em:

https://api2.transloadit.com/mcp

Adicione esta URL ao seu cliente MCP. O cliente descobre a API da Transloadit como seu servidor de autorização OAuth, abre uma página de consentimento no Transloadit Console e mantém um token de acesso e um token de atualização para você. Seu Auth Secret nunca sai da sua conta.

O endpoint hospedado exige que você entre na sua conta antes de executar qualquer ferramenta, inclusive as de documentação de Robots e análise estática, porque os clientes MCP só iniciam o OAuth quando o endpoint solicita. Para usar a documentação de Robots e a análise estática sem uma conta, execute o servidor por conta própria.

A página de consentimento

Quando você se conecta, seu navegador abre a página de consentimento. Ela informa o nome do aplicativo, mostra para onde você será redirecionado e lista as permissões solicitadas. Escolha o Workspace que o aplicativo poderá usar e aprove o acesso.

A aprovação cria uma Auth Key dedicada nesse Workspace, limitada às permissões exibidas. Sua descrição é o nome do aplicativo seguido de via OAuth e da data. Uma conexão MCP recebe, no máximo, assemblies:write, assemblies:read e templates:read. A página de consentimento mostra por quanto tempo cada token de acesso dura (uma semana para o servidor MCP); o aplicativo o renova por conta própria. Para revogar o acesso, abra Aplicativos conectados no Console, que lista todos os aplicativos que você aprovou, com suas permissões e quando foram usados pela última vez. Revogar ali encerra o acesso do aplicativo imediatamente.

Claude Code

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

Em seguida, execute /mcp no Claude Code, selecione transloadit e autentique-se, ou execute claude mcp login transloadit no seu shell. Em ambos os casos, o navegador abre a página de consentimento.

Para execuções não interativas, como claude -p, permita explicitamente o uso das ferramentas da Transloadit:

claude -p "List my Templates" \
  --allowedTools 'mcp__transloadit__*' \
  --output-format json

Claude.ai e Claude Desktop

Acesse Settings → Connectors → Add custom connector e insira https://api2.transloadit.com/mcp. O Claude se identifica junto à API da Transloadit e abre a página de consentimento. Consulte a documentação de conectores personalizados do Claude⁠ para mais detalhes.

ChatGPT

Acesse Settings → Apps & Connectors → Advanced, ative Developer mode e crie um aplicativo com a URL acima. Defina a autenticação como OAuth. O ChatGPT encaminha à Transloadit, por você, os arquivos que você anexa no chat e mostra os resultados no widget de resultados.

Codex

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

O Codex abre a página de consentimento imediatamente. Para entrar novamente mais tarde, execute codex mcp login transloadit.

Você também pode adicionar o servidor a ~/.codex/config.toml:

[mcp_servers.transloadit]
url = "https://api2.transloadit.com/mcp"

Cursor

Adicione o servidor a ~/.cursor/mcp.json:

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

VS Code / Copilot

Adicione o servidor à sua configuração MCP, por exemplo, .vscode/mcp.json:

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

Ferramentas disponíveis

O endpoint hospedado exige que você entre na sua conta antes de executar qualquer ferramenta; as ferramentas marcadas como “Não” funcionam sem conta em um servidor com hospedagem própria.

transloadit_create_assembly é a única ferramenta marcada como destrutiva: Robots de exportação, como /s3/store, podem sobrescrever arquivos no destino, por isso os clientes podem pedir sua confirmação.

transloadit_list_templates oferece suporte a include_builtin (all, latest, exclusively-all, exclusively-latest) e, opcionalmente, a include_content. transloadit_get_profile retorna o ID do Workspace associado às credenciais atuais, além do nome dele quando a Transloadit conseguir identificá-lo, e informa mcp_profile_unavailable para um Workspace sem Assemblies ou Templates ainda.

Arquivos de entrada

transloadit_create_assembly recebe arquivos das seguintes formas:

• URLs públicas (files com kind: 'url'): o servidor importa os arquivos ou faz o download deles. Consulte Comportamento de URLs e Templates.
• Arquivos pequenos inline (files com kind: 'base64'): uma opção prática apenas para arquivos pequenos. Consulte Limites.
• Anexos do ChatGPT (attachments): o ChatGPT encaminha automaticamente os arquivos que você anexa no chat. Cada um se torna uma entrada por URL chamada attachment_1, attachment_2 e assim por diante.
• Arquivos que existem apenas no sandbox do agente ou na sua máquina: crie a Assembly com expected_uploads e deixe o agente fazer o upload deles, conforme descrito abaixo.

Caminhos de arquivos locais não são aceitos como entradas das ferramentas, nem mesmo por um servidor com hospedagem própria. Para fazer upload da sua própria máquina, você também pode usar npx -y @transloadit/node upload.

Arquivos no sandbox de um agente

Alguns clientes, como o Claude.ai, não repassam anexos do chat às ferramentas dos conectores, e base64 nos argumentos das ferramentas só funciona para arquivos muito pequenos. Nesse caso, o agente faz o upload do arquivo a partir do próprio sandbox:

1. Chame transloadit_create_assembly com suas instruções e expected_uploads definido como o número de arquivos (no máximo 100 por chamada). A chamada retorna imediatamente, mesmo com wait_for_completion: true, porque a Assembly agora aguarda esses uploads.

   {
     "instructions": {
       "steps": {
         ":original": { "robot": "/upload/handle" },
         "resized": { "robot": "/image/resize", "use": ":original", "width": 200 }
       }
     },
     "expected_uploads": 1
   }
   

2. Cada entrada em upload_instructions contém o endpoint tus, os metadados tus e um comando curl pronto para execução. O agente define FILE com o caminho do arquivo e executa o comando em um shell bash. O comando imprime 201 assim que o upload do arquivo é concluído.

3. Chame transloadit_wait_for_assembly com a Assembly URL.

Os comandos não contêm credenciais, mas mantenha a Assembly URL privada: quem a possuir pode adicionar arquivos enquanto a Assembly aguarda uploads, ler seu status e seus resultados, e cancelá-la.

O sandbox precisa de acesso HTTPS de saída à Transloadit. No Claude.ai, abra Settings → Capabilities, ative o acesso de saída à rede para execução de código e adicione *.transloadit.com aos domínios adicionais permitidos. Adicione também *.transloadit.net se o agente precisar baixar os resultados de volta para o sandbox dele.

Widget de resultados

transloadit_create_assembly e transloadit_wait_for_assembly apontam para o recurso MCP Apps ui://transloadit/assembly-result. Clientes que oferecem suporte a MCP Apps, como o ChatGPT, mostram os resultados de cada Step no chat com prévias de imagem, vídeo e áudio, links de download, um link Open in Console e um atalho Save as Template. Outros clientes recebem os mesmos resultados como saída normal da ferramenta.

CI e clientes sem interface

Quando ninguém puder aprovar o acesso em um navegador, como em jobs de CI, servidores ou ambientes de execução de agentes, emita um token Bearer a partir de uma Auth Key e envie-o como Authorization: Bearer <token>:

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

Gere esse token em um ambiente confiável (backend, CI ou shell local) e depois o repasse ao ambiente de execução do agente. Você pode emiti-lo via:

• CLI: npx -y @transloadit/node auth token --aud mcp
• API: POST /token
• SDK Node.js: instancie Transloadit com authKey + authSecret e depois chame client.mintBearerToken({ aud: 'mcp' })

Mantenha os tokens Bearer fora do controle de versão e das configurações compartilhadas. Use o armazenamento de segredos ou o suporte a variáveis de ambiente do seu cliente, em vez de incluir um token real em um commit.

Claude Code com um token Bearer

Use esta entrada de servidor remoto no .mcp.json do projeto do Claude Code. O valor do transporte HTTP é http. Defina TRANSLOADIT_API2_BEARER_TOKEN com o token API2 que você emitiu no ambiente que inicia o Claude Code; a configuração abaixo expande essa variável em tempo de execução. Consulte a documentação de MCP do Claude Code⁠.

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

Outros clientes que permitem definir cabeçalhos de requisição para um servidor MCP remoto aceitam o mesmo cabeçalho Authorization.

Hospedagem própria

Execute o servidor onde seu agente é executado e defina TRANSLOADIT_KEY e TRANSLOADIT_SECRET; o servidor cuidará automaticamente da autenticação das chamadas à API.

Stdio

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

A maioria dos clientes inicia o servidor para você. Por exemplo, no Claude Code:

claude mcp add --transport stdio transloadit \
  --env TRANSLOADIT_KEY=MY_AUTH_KEY \
  --env TRANSLOADIT_SECRET=MY_SECRET_KEY \
  -- npx -y @transloadit/mcp-server stdio

Ou no Codex:

codex mcp add transloadit \
  --env TRANSLOADIT_KEY=MY_AUTH_KEY \
  --env 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

O modo http usa o caminho /mcp por padrão.

Docker

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

A imagem inicia o modo stdio. Para o modo HTTP, sobrescreva o entrypoint e exponha a porta. Vincular a 0.0.0.0 exige um TRANSLOADIT_MCP_TOKEN, que os clientes então enviam como Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>:

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

Algoritmo de assinatura

Defina TRANSLOADIT_SIGNATURE_ALGORITHM com o algoritmo configurado para sua Auth Key; o trecho de código da chave no Console mostra qual é. Chaves criadas no Console com a opção Allow signing Smart CDN URLs ativada (o padrão) usam sha256, e o servidor usa sha384 por padrão. Uma incompatibilidade resulta em falha com mcp_invalid_signature, e a dica que acompanha o erro indica o algoritmo exigido pela chave.

TRANSLOADIT_MCP_TOKEN em detalhes

TRANSLOADIT_MCP_TOKEN é um token de transporte MCP para hospedagem própria. Ele protege seu próprio endpoint MCP HTTP (npx -y @transloadit/mcp-server http), não a API2.

• Defina-o você mesmo com qualquer segredo de alta entropia.
• Envie-o do seu cliente MCP como Authorization: Bearer <TRANSLOADIT_MCP_TOKEN>.
• Ele não é emitido via /token.
• Ele é separado dos tokens Bearer da API2 usados para https://api2.transloadit.com/mcp.

Gere um token e depois inicie o modo HTTP:

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

Configurações do widget de resultados

O widget de resultados pode carregar prévias de https://*.transloadit.com, https://*.transloadit.net e https://*.r2.dev. Substitua essa lista com TRANSLOADIT_MCP_RESULT_DOMAINS (origens separadas por vírgulas). Seus links do Console apontam para https://transloadit.com; altere isso com TRANSLOADIT_MCP_CONSOLE_URL.

Limites

Estes limites se aplicam a payloads JSON inline e base64:

• Limite do corpo da requisição no servidor hospedado: 1 MiB
• maxBase64Bytes: 512.000 bytes decodificados, tanto na versão hospedada quanto na versão com hospedagem própria
• Limite padrão do corpo da requisição em hospedagem própria: 10 MiB (configurável com maxRequestBodyBytes)

As entradas por URL das quais o servidor faz download (para Templates que esperam uploads) são limitadas a 1 GiB no total por chamada e a 10 minutos por download. Para arquivos maiores, use uma URL pública com um Step /http/import, faça upload a partir do sandbox do agente ou faça upload da sua própria máquina com npx -y @transloadit/node upload.

Comportamento de URLs e Templates

Para entradas por URL, o servidor escolhe um caminho seguro com base nas instruções ou no Template de destino:

• Se existir um Step /http/import, ele define/sobrescreve url desse Step.
• Se o Template espera uploads (:original ou /upload/handle), ele faz o download e depois o upload via tus. Esses downloads exigem URLs HTTP(S) públicas; destinos em redes privadas são rejeitados, incluindo redirecionamentos para endereços privados.
• Se o Template não aceita arquivos de entrada, as entradas por URL são ignoradas com um aviso.
• Se um Template proíbe sobrescritas de Steps e oferece suporte apenas a /http/import, as entradas por URL são rejeitadas.

Métricas e ficha do servidor

As implantações HTTP incluem:

• Métricas Prometheus em GET /metrics (padrão)
• Autenticação opcional das métricas via TRANSLOADIT_MCP_METRICS_USER e TRANSLOADIT_MCP_METRICS_PASSWORD
• Ficha pública do servidor MCP em /.well-known/mcp/server-card.json, listando todas as ferramentas com suas anotações e esquemas de segurança

Você pode personalizar metricsPath, desativar as métricas (metricsPath: false) e configurar restrições de CORS/host nas opções do servidor HTTP/Express.

Uso de MCP com /ai/chat

/ai/chat pode chamar qualquer servidor MCP acessível a partir do seu ambiente.

Para servidores MCP hospedados pela Transloadit, você pode usar:

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

Com auth: "transloadit", a API2 pode emitir e injetar automaticamente um token Bearer de curta duração com escopos definidos para URLs MCP elegíveis hospedadas pela Transloadit. Se você já fornecer Authorization em mcp_servers[].headers, a API2 não o altera.

Documentação relacionada

• Agentes de IA
• Autenticação
• Criar um token Bearer (POST /token)
• README do servidor MCP⁠