Conecte a Transloadit ao ChatGPT, Claude e Codex com uma URL

Kevin van Zonneveld

Cofundador · Amsterdã, Países Baixos · Mostrar biografia

Em fevereiro, lançamos o servidor MCP da Transloadit EN (English), mas conectá-lo exigia gerar um token bearer e colá-lo em um arquivo de configuração. Aplicativos de chat hospedados que não podiam enviar cabeçalhos personalizados nem sequer conseguiam se conectar. A partir de hoje, basta colar uma URL. Seu cliente abre uma tela de consentimento da Transloadit, você aprova, e seu agente pode fazer upload, codificar e transformar arquivos com nossos Robots, seja por meio de ferramentas de atalho para tarefas comuns, como legendar um vídeo, seja compondo uma Assembly por conta própria.

Testamos esse fluxo de ponta a ponta com ChatGPT, Claude, Claude Code e Codex. A seguir, veja como conectar cada um, quais permissões a tela de consentimento concede e como os arquivos saem da conversa, ou do sandbox de um agente, e chegam a uma Assembly.

Cole uma URL

O endpoint hospedado é o mesmo para todos os clientes:

https://api2.transloadit.com/mcp

• Claude Code: execute claude mcp add --transport http transloadit https://api2.transloadit.com/mcp, depois abra /mcp em uma sessão e escolha Authenticate.
• Claude: em Settings → Connectors, escolha Add custom connector, cole a URL e clique em Continue. O Claude detecta que deve solicitar seu login e como se identificar.
• ChatGPT: com o modo de desenvolvedor ativado, crie um novo plugin usando a URL como URL do servidor e OAuth como autenticação. Ele aparecerá em Settings → Plugins: clique em Connect e, depois, em Continue to Transloadit.
• Codex: execute codex mcp add transloadit --url https://api2.transloadit.com/mcp. O Codex inicia o login no navegador para você.

Você não precisa copiar nada da sua conta: nenhuma chave, nenhum segredo, nenhum token. Cada cliente descobre nosso servidor de autorização pela URL, se identifica e leva você à tela de consentimento.

Por que não simplesmente colar uma Auth Key?

Você ainda pode fazer isso. Para seu próprio backend, scripts, CI ou uma integração como o Zapier, uma Auth Key é a ferramenta certa. Mas colar uma chave em um aplicativo de chat é como entregar uma cópia da chave da sua casa: ele pode fazer tudo o que essa chave permite até você excluí-la, não conseguimos saber qual aplicativo a possui, e excluí-la corta o acesso de todas as ferramentas que a compartilham. A conexão por URL funciona de outra forma. O aplicativo solicita acesso, você o aprova para um Workspace, e ele recebe sua própria autorização apenas com as permissões de que precisa. Você vê cada aplicativo em Apps conectados e pode revogar o acesso de um sem alterar mais nada. A documentação do servidor MCP compara as duas formas lado a lado.

Uma tela de consentimento

A tela de consentimento fica na Transloadit Console. Se você não tiver feito login, primeiro entre ou cadastre-se e, em seguida, voltará à mesma solicitação.

Ela mostra qual aplicativo está solicitando acesso (nome, site, logo e endereço de retorno), permite escolher o Workspace e lista as permissões: criar Assemblies, ler Assemblies e ler Templates. Isso é tudo de que o servidor MCP precisa, então é tudo o que a tela concede, mesmo quando um cliente pede mais. O Codex, por exemplo, solicita todas as permissões que nossa API reconhece e, ainda assim, recebe apenas essas três.

Aplicativos executados no seu próprio computador, como Codex e Claude Code, retornam a um endereço local, e a tela de consentimento informa isso:

A aprovação cria uma Auth Key dedicada nesse Workspace, limitada a essas permissões. Para revogar o acesso depois, abra Apps conectados na Console: a seção lista todos os aplicativos que você aprovou, e revogar um deles encerra seu acesso imediatamente. Suas outras chaves continuam funcionando. No Claude, a solicitação seguinte pede que você se conecte novamente:

Seu Auth Secret nunca sai da sua conta. O cliente recebe um token de acesso para o servidor MCP que expira após uma semana, além de um token de atualização que dura 30 dias e é substituído a cada uso. Se um token de atualização já usado aparecer novamente, por exemplo, uma cópia roubada, revogamos toda a cadeia.

Peça o que você quer

Depois de se conectar, você conversa com seu agente como conversaria com um colega:

• “Liste meus Templates da Transloadit.”
• “Transforme esta palestra em um reel vertical com legendas incorporadas permanentemente à imagem do vídeo.”
• “Remova o fundo destas fotos de produtos.”
• “Redimensione esta imagem, codifique este vídeo em 720p, crie um MP3 de 64 kbps deste áudio e renderize a primeira página deste PDF como PNG, tudo em uma única Assembly.”

Ferramentas de atalho para tarefas comuns

Para as tarefas mais solicitadas, o servidor oferece ferramentas prontas junto das ferramentas gerais: Legendar vídeo, Capturar página da web, Converter para PDF, Codificar vídeo, Extrair texto, Preparar imagem, Remover fundo, Transcrever e Capas de vídeo. Cada uma executa um Builtin Template que mantemos, então o agente só fornece o arquivo e algumas opções, em vez de escrever Assembly Instructions do zero. Veja o Codex legendando um clipe de um discurso com uma delas, em um exemplo abreviado:

$ codex exec "Use the transloadit MCP server. Turn ./jfk-we-choose-to-go-to-the-moon.mp4 into a vertical social reel with burned-in captions, using the Caption video tool. …"
mcp: transloadit/transloadit_get_robot_help (completed)
mcp: transloadit/transloadit_list_templates (completed)
mcp: transloadit/transloadit_lint_assembly_instructions (completed)
mcp: transloadit/transloadit_create_assembly (completed)
mcp: transloadit/transloadit_wait_for_assembly (completed)
mcp: transloadit/transloadit_caption_video (completed)
mcp: transloadit/transloadit_wait_for_assembly (completed)
codex
Finished: 1080 × 1920 (9:16), 55.018 seconds, with burned-in captions.

First three caption lines:

1. “and master, without feeding the fires of war,”
2. “without repeating the mistakes that man”
3. “has made in extending his writ around this globe of ours.”

Ou deixe o agente compor uma Assembly

Quando nenhum atalho se encaixa, o agente escreve a própria Assembly, e é aí que fica interessante. Demos uma frase ao Claude:

Usando a Transloadit: pegue o discurso de domínio público do presidente Kennedy na Rice University em https://upload.wikimedia.org/…/President_Kennedy%27s_Speech_at_Rice_University.ogv, recorte o trecho de 8:44 a 9:34 (de “Mas por que, dizem alguns, a Lua?” até “Escolhemos ir à Lua”) em uma única Assembly e, depois, transforme esse clipe em um reel vertical para redes sociais com legendas incorporadas permanentemente à imagem do vídeo.

O Claude encadeou quatro Robots em uma única Assembly. 🤖 /http/import buscou a gravação de 18 minutos no Wikimedia Commons, 🤖 /video/encode recortou o trecho e o reenquadrou em 1080 × 1920, 🤖 /speech/transcribe fez a transcrição, e 🤖 /video/subtitle incorporou permanentemente à imagem do vídeo legendas que destacam cada palavra conforme ela é falada. A Assembly terminou em menos de um minuto. O Claude então leu a transcrição, percebeu que nossos timestamps estavam defasados em alguns segundos e ofereceu um corte mais preciso, que termina em “não porque são fáceis, mas porque são difíceis”. Após um “sim”, o resultado foi este:

A criação de uma Assembly pode gravar arquivos no seu próprio armazenamento, por exemplo, por meio de um Robot como o 🤖 /s3/store. Por isso, marcamos essa ferramenta e as ferramentas de atalho como ferramentas que fazem alterações. Os clientes que respeitam essa indicação pedem sua confirmação primeiro. Listar Templates, consultar o status de uma Assembly e consultar a documentação de Robots são operações marcadas como somente leitura. Quando uma ferramenta precisa da sua aprovação, o Claude mostra o que está prestes a enviar:

Em clientes que renderizam MCP Apps, como ChatGPT e Claude, uma Assembly concluída aparece como um cartão na própria conversa. Ele mostra o status da Assembly e uma grade de resultados, cada um identificado pelo Step que o gerou, com uma prévia de imagem ou vídeo, um reprodutor de áudio e um botão de download. Enquanto a Assembly ainda está em execução, o cartão continua consultando seu status e preenche os resultados quando ficam prontos. Assim, o agente pode acompanhá-la em vez de começar de novo. Veja o reel de Kennedy no Claude:

E uma solicitação com quatro arquivos no ChatGPT, com uma imagem, um vídeo, um arquivo de áudio e um PDF processados em uma única Assembly:

Clientes sem MCP Apps, como o Codex em um terminal, recebem os mesmos resultados na saída da ferramenta.

Envie arquivos à Transloadit, onde quer que estejam

Os arquivos costumam ser o ponto em que os agentes ficam travados, então o servidor MCP os aceita de várias formas:

• Uma URL pública. Peça ao agente para processar https://example.com/talk.mp4, e a própria Transloadit busca o arquivo nesse endereço.
• Um anexo no ChatGPT. Anexe um arquivo à sua mensagem, e o ChatGPT fornece à Transloadit um link temporário de download para ele, de modo que o arquivo nunca passa pela conversa.
• Um arquivo no sandbox do próprio agente. Claude, Claude Code e Codex podem executar comandos. Quando um arquivo existe apenas nessa máquina, o agente solicita à Transloadit um espaço para upload e recebe um comando curl pronto para executar, que transmite o arquivo diretamente para a Assembly via tus⁠, o protocolo de upload retomável que mantemos. Depois, ele aguarda o resultado.

Esse comando de upload não contém credenciais, apenas o endereço de uma Assembly que está aguardando seus arquivos. Ainda assim, mantenha esse endereço privado: quem o tiver também poderá ler o status e os resultados da Assembly e cancelá-la. No Claude, o sandbox precisa de acesso de saída à rede para alcançar a Transloadit: em Settings → Capabilities, permita a saída de tráfego de rede e adicione *.transloadit.com aos domínios permitidos. Para permitir que o Claude busque os resultados e os traga de volta ao sandbox, adicione *.transloadit.net também.

Para plataformas que chamam nossa API diretamente

O mesmo fluxo de autorização também emite tokens para a própria REST API da Transloadit, para plataformas que chamam a API em nome de um usuário em vez de passar pelo MCP. Um token desse tipo nunca inclui permissões de gerenciamento de credenciais: ele não pode criar Auth Keys nem ler Credenciais de Template armazenadas, mesmo que a chave usada para aprovar o acesso pudesse.

Por dentro

Para quem tem curiosidade, isso é OAuth 2.1 padrão, conforme descrito na especificação de autorização do MCP⁠:

• O servidor MCP responde a solicitações não autenticadas com um 401 que aponta para seus metadados do recurso protegido⁠, que identificam nosso servidor de autorização.
• Os clientes se identificam com um documento público de metadados do cliente, como fazem ChatGPT, Claude, Claude Code e Codex, ou se registram no momento da conexão com o registro dinâmico de clientes⁠.
• Toda autorização usa PKCE⁠, e os tokens são vinculados ao recurso para o qual foram solicitados.

Fazer quatro clientes concordarem com tudo isso nos ensinou algumas coisas, que vamos detalhar separadamente.

Conheça os limites

• O ChatGPT só oferece plugins personalizados quando o modo de desenvolvedor está disponível no seu plano e ativado. A inclusão nos diretórios do ChatGPT e do Claude vem a seguir; até lá, conecte-se pela URL, como mostrado acima.
• Arquivos enviados diretamente em uma chamada de ferramenta, como base64, têm limite de 512 KB. Para arquivos maiores, use uma URL ou um upload do sandbox. Uma solicitação pode preparar até 100 uploads do sandbox.
• No plano gratuito Community, os resultados de imagem recebem marca-d’água, e os resultados de áudio e vídeo têm a duração reduzida. Nossa FAQ explica o motivo.
• O ChatGPT mantém uma cópia das ferramentas de um plugin. Quando adicionarmos ferramentas, abra o plugin nas configurações do ChatGPT e clique em Refresh tools para obtê-las. O Codex obtém a lista atual quando se conecta.

Experimente

Cole https://api2.transloadit.com/mcp no seu cliente e aprove a tela de consentimento. Ainda não tem uma conta? Cadastre-se na página que abrir ou crie uma antes. A documentação do servidor MCP cobre todos os clientes e a configuração em hospedagem própria, e nossas agent skills ensinam os agentes a usar bem a Transloadit. Conte o que está faltando no rastreador de issues do node-sdk⁠.