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.

Duas formas de se conectar

Os aplicativos acessam sua conta da Transloadit de uma de duas formas. Ambas enviam uma credencial em cada requisição, mas diferem em quem a cria, no que ela permite fazer e em como revogá-la.

• OAuth (conectar por URL): você cola https://api2.transloadit.com/mcp no aplicativo e aprova a tela de consentimento da Transloadit para um Workspace. O aplicativo recebe seu próprio acesso limitado (assemblies:read, assemblies:write e templates:read), que se renova automaticamente e pode ser revogado separadamente. Não há nada para copiar, e o aplicativo aparece em Aplicativos conectados. Aplicativos de chat hospedados, como ChatGPT e Claude, precisam disso porque não podem enviar cabeçalhos personalizados.
• Auth Key ou token Bearer: você copia uma Auth Key, ou um token Bearer emitido a partir dela, para a ferramenta. Ela pode fazer tudo o que a chave permite até você excluir a chave, e não aparece em Aplicativos conectados. Esta é a opção adequada para seu próprio backend, scripts, CI, um servidor MCP com hospedagem própria e integrações como Zapier.

Quando usar cada opção

• Use OAuth quando uma pessoa conectar um cliente de agente, como ChatGPT, Claude, Codex, Cursor ou VS Code. Consulte Conectar por URL.
• Use uma Auth Key ou um token Bearer para código que você executa por conta própria e para ferramentas que pedem uma chave. Consulte CI e clientes sem interface e Hospedagem própria.

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

Abra Transloadit no diretório de plugins do ChatGPT⁠, clique em Install plugin e aprove a página de consentimento. O ChatGPT encaminha à Transloadit, por você, os arquivos que você anexa no chat e mostra os resultados no widget de resultados.

Se preferir conectar por URL, acesse Settings → Apps & Connectors → Advanced, ative Developer mode e crie um aplicativo com a URL acima. Defina a autenticação como OAuth.

O plugin do diretório recebe novas ferramentas quando publicamos uma nova versão revisada. Um aplicativo em modo de desenvolvedor mantém uma cópia da lista de ferramentas do momento em que você o criou: depois que adicionarmos ferramentas, abra as configurações do aplicativo no ChatGPT e clique em Refresh tools para incluí-las.

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 vinculam o recurso MCP Apps ui://transloadit/assembly-result. Clientes que oferecem suporte a MCP Apps, como o ChatGPT e o Claude, mostram a Assembly como um cartão no chat. Outros clientes recebem os mesmos resultados como saída normal da ferramenta.

• Status: um rótulo legível, como Completed, Processing, Waiting for uploads ou Failed. Uma Assembly com falha também mostra sua mensagem de erro e seu código. Enquanto a Assembly é executada, uma nota informa que os arquivos de resultado aparecem quando ela é concluída.
• Assembly ID: leva à Assembly no Console.
• Atalho para Template: Save as Template abre um novo Template no Console, preenchido com as instruções da Assembly. O cartão não oferece o atalho para Assemblies com falha, Assemblies que ainda aguardam uploads ou Assemblies cujo status não pôde ser lido.
• Resultados: quando vários Steps geraram, cada um, um ou dois arquivos, todos os resultados compartilham uma única grade e cada cartão indica o Step que o gerou. Caso contrário, cada Step tem sua própria seção, com seu Robot e o número de arquivos. Um cartão mostra o nome do arquivo, suas dimensões e seu tamanho (ou seu tipo MIME), uma prévia e um botão de download. As prévias de imagem e vídeo mantêm o tamanho enquanto carregam, e os vídeos são reproduzidos inline.
• Áudio: cada arquivo de áudio é uma linha de largura total com um player.
• Uploads: os arquivos que você enviou ficam agrupados em uma linha Uploaded files na parte inferior.
• Resultados longos: um Step mostra até 8 arquivos e o cartão, até 12; o restante fica recolhido em Show N more. O cartão limita sua altura ao que o cliente permitir, ou a 720 pixels, e rola, com um esmaecimento que indica quantos arquivos há abaixo.
• Tema: o cartão segue o tema claro ou escuro do cliente.

CI e clientes sem interface

Quando ninguém puder aprovar o acesso em um navegador, como em tarefas 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⁠