Servidor MCP

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

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

Escolha um modo de implantação

Hospedagem própria (recomendada): o caminho mais simples para a maioria das equipes quando tudo funciona como esperado. Seu processo MCP tem acesso a TRANSLOADIT_KEY e TRANSLOADIT_SECRET, então pode cuidar automaticamente da autenticação nas chamadas de API.
Endpoint hospedado: use https://api2.transloadit.com/mcp quando não puder executar npx no ambiente em que seu agente é executado.

Início rápido (hospedagem própria)

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 o caminho /mcp por padrão.

Observação

Se vincular o modo HTTP a um host diferente de localhost, defina TRANSLOADIT_MCP_TOKEN para exigir autenticação Bearer nas requisições MCP.

Entenda `TRANSLOADIT_MCP_TOKEN`

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 você mesmo o valor como um segredo de alta entropia de sua escolha.
Envie-o a partir 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 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 não puder usar hospedagem própria, aponte seu cliente de agente para:

https://api2.transloadit.com/mcp

Use Authorization: Bearer <token> e emita o token via:

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

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

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

Use esta entrada de servidor remoto no .mcp.json do projeto no Claude Code. O valor do transporte HTTP é 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. Consulte 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 com hospedagem própria mostrado acima como um servidor MCP local usando a configuração claude_desktop_config.json. Os servidores remotos são gerenciados em Settings → Connectors; o JSON do Claude Code acima não é uma configuração do Claude Desktop. Consulte a documentação de conectores personalizados do Claude para conhecer as opções de autenticação remota compatíveis. O exemplo hospedado aqui exige um cliente que possa 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 com suporte a streaming e o mesmo cabeçalho Authorization nas configurações de MCP.

Ferramentas disponíveis

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 oferece suporte a include_builtin (all, latest, exclusively-all, exclusively-latest) e, opcionalmente, a include_content.

Arquivos de entrada e limites

transloadit_create_assembly oferece suporte a três tipos de entrada:

path: arquivos locais que o processo do servidor MCP pode ler
url: arquivos remotos
base64: payloads embutidos para arquivos pequenos

Limites e valores padrão:

Limite padrão do corpo da requisição no endpoint hospedado: 1 MB
Limite padrão do corpo da requisição na hospedagem própria: 10 MB (configurável)
Valor padrão de maxBase64Bytes: 512.000 bytes decodificados

Para arquivos maiores, prefira entradas path ou url.

Comportamento de URLs e Templates

Para entradas de URL, o servidor escolhe um caminho seguro com base nas Instructions ou no Template de destino:

Se existir um Step /http/import, o servidor define ou sobrescreve o valor de url desse Step.
Se o Template esperar uploads (:original ou /upload/handle), o servidor faz o download e depois o upload via tus.
Se o Template não aceitar arquivos de entrada, as entradas de URL são ignoradas, com um aviso.
Se um Template proibir sobrescritas de Steps e aceitar apenas /http/import, as entradas de URL serão rejeitadas.

Acesso a arquivos local e hospedado

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

Para fluxos de trabalho remotos, use url, base64 de tamanho reduzido ou faça o upload por um canal separado com a CLI da Transloadit. Use expected_uploads quando quiser que uma Assembly permaneça aberta para uploads posteriores via tus.

Métricas e cartão do servidor

As implantações HTTP incluem:

Métricas do Prometheus em GET /metrics (padrão)
Autenticação opcional para 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.

Uso do 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 com escopo definido e de curta duração para URLs elegíveis de MCP hospedado pela Transloadit. Se você já fornecer Authorization em mcp_servers[].headers, a API2 não altera esse valor.