Servidor MCP

O servidor MCP da Transloadit permite que clientes de agentes chamem ferramentas da Transloadit diretamente: criar e monitorar Assemblies, fazer lint de Assembly Instructions e descobrir Robots e Templates.

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

Escolha um modo de implantação

Auto-hospedado (recomendado): o caminho mais simples e direto para a maioria das equipes. Seu processo MCP tem acesso a TRANSLOADIT_KEY e TRANSLOADIT_SECRET, então pode cuidar da autenticação das chamadas de API automaticamente.
Endpoint hospedado: use https://api2.transloadit.com/mcp quando você não puder executar npx onde seu agente é executado.

Início rápido (auto-hospedado)

Stdio (recomendado)

TRANSLOADIT_KEY=MY_AUTH_KEY 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

Docker

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

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

Observação

Se você vincular o modo HTTP a um host que não seja localhost, defina TRANSLOADIT_MCP_TOKEN para exigir autenticação Bearer nas requisições MCP.

`TRANSLOADIT_MCP_TOKEN` explicado

TRANSLOADIT_MCP_TOKEN é um token de transporte MCP auto-hospedado. 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 pelo 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 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

Endpoint hospedado

Se você não puder auto-hospedar, aponte seu cliente de agente para:

https://api2.transloadit.com/mcp

A descoberta de Robots, a ajuda de Robots e o lint de Assembly Instructions funcionam sem credenciais. Ações da conta, incluindo listar Templates e criar ou monitorar Assemblies, exigem autenticação. Para essas ações, use Authorization: Bearer <token> e emita o token via:

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

Gere este token em um ambiente confiável (backend, CI ou shell local) e depois entregue-o ao runtime 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' })

Usando o token

Envie o token como Authorization: Bearer <access_token> nas requisições à API. Quando uma requisição é autenticada com um Bearer token válido, a API2 considera a Signature Authentication como satisfeita e pula a validação da assinatura. A Signature Authentication só é exigida em requisições com chave/segredo. As verificações de escopo continuam valendo. A audiência padrão api2 é aceita pelos endpoints comuns da API2 e é válida por 21.600 segundos por padrão. A audiência mcp é aceita pelo servidor MCP, rejeitada pelos endpoints comuns da API2 e válida por 604.800 segundos por padrão. Trate o valor expires_in da resposta como a fonte autoritativa.

Exemplos de configuração de clientes

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

Claude Code

Use esta entrada de servidor remoto no .mcp.json do projeto do Claude Code. O valor de transporte HTTP dela é http. Defina TRANSLOADIT_MCP_TOKEN no ambiente que inicia o Claude Code; a configuração abaixo expande essa variável em tempo de execução. Veja a documentação de MCP do Claude Code.

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

Claude Desktop

O Claude Desktop usa uma configuração separada. Configure o servidor stdio auto-hospedado acima como um servidor MCP local usando a configuração claude_desktop_config.json dele. Servidores remotos são gerenciados em Settings → Connectors; o JSON do Claude Code acima não é uma configuração do Claude Desktop. Veja a documentação de conectores personalizados do Claude para as opções de autenticação remota compatíveis. O exemplo hospedado aqui exige um cliente capaz de enviar o cabeçalho Bearer especificado.

VS Code / Copilot

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

Cursor

Use a mesma URL de HTTP streamable e o cabeçalho Authorization nas configurações de MCP.

Ferramentas expostas

O servidor MCP expõe estas ferramentas:

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 aceita include_builtin (all, latest, exclusively-all, exclusively-latest) e um include_content opcional.

Arquivos de entrada e limites

transloadit_create_assembly aceita três tipos de entrada:

path: arquivos locais legíveis pelo processo do servidor MCP
url: arquivos remotos
base64: payloads inline para arquivos pequenos

Limites e padrões:

Limite padrão do corpo da requisição no modo hospedado: 1 MB
Limite padrão do corpo da requisição no modo auto-hospedado: 10 MB (configurável)
maxBase64Bytes padrão: 512.000 bytes decodificados

Para arquivos maiores, prefira entradas path ou url.

Comportamento de URL e Template

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

Se existir um Step /http/import, ele define/sobrescreve o url desse Step.
Se o Template espera uploads (:original ou /upload/handle), ele faz o download e depois o upload via tus.
Se o Template não recebe arquivos de entrada, as entradas de URL são ignoradas com um aviso.
Se um Template proíbe sobrescritas de Step e só aceita /http/import, as entradas de URL são rejeitadas.

Acesso a arquivos: local vs. hospedado

Entradas path só funcionam quando o processo MCP consegue ler o mesmo sistema de arquivos (stdio/HTTP local). O MCP hospedado não consegue ler seu disco.

Para fluxos de trabalho remotos, use url, base64 pequeno ou faça o upload fora de banda com a CLI da Transloadit. Use expected_uploads quando quiser que uma Assembly permaneça aberta para uploads tus posteriores.

Métricas e cartão do servidor

Implantações HTTP incluem:

Métricas do Prometheus em GET /metrics (padrão)
Autenticação opcional das métricas via TRANSLOADIT_MCP_METRICS_USER e TRANSLOADIT_MCP_METRICS_PASSWORD
Cartão público do servidor MCP em /.well-known/mcp/server-card.json

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

Usando 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 automaticamente e injetar um token Bearer de curta duração e escopo limitado para URLs MCP elegíveis hospedadas pela Transloadit. Se você já fornece Authorization em mcp_servers[].headers, a API2 não o altera.