Geração de vídeo com Claude Code e MCP: configuração passo a passo

Você está no terminal, no meio de uma landing page, e precisa de três clipes de produto de 5 segundos, uma imagem hero e uma locução de 20 segundos. O caminho de sempre são quatro abas do navegador, três logins, uma pasta de downloads cheia de arquivos chamados output(7).mp4 e nenhuma ideia clara de quanto a tarde custou. O outro caminho é uma frase digitada no Claude Code, com os arquivos caindo no seu projeto, cada um etiquetado com o modelo usado e o custo.

O segundo caminho roda sobre o Model Context Protocol. O Claude Code fala MCP nativamente, então qualquer serviço de geração que exponha um servidor MCP hospedado vira um conjunto de ferramentas que o agente pode chamar. A seguir: a configuração, os ajustes de permissão que vale mudar no primeiro dia, como formular os pedidos para o agente escolher o modelo e a duração certos, e as contas de quanto custam lotes reais.

O que acontece quando o Claude Code chama uma ferramenta de vídeo

O transporte

Um servidor MCP hospedado usa o transporte Streamable HTTP. A especificação do MCP (2025-06-18) define dois transportes padrão, stdio e Streamable HTTP, e exige que o servidor exponha um único caminho de endpoint que aceite POST e GET, como https://example.com/mcp. O cliente envia cada mensagem JSON-RPC como um POST, e o servidor responde com JSON simples ou com um fluxo de eventos.

Na prática, um servidor hospedado é uma URL mais uma credencial, sem nada para rodar localmente, e funciona no Claude Code, no Cursor ou em qualquer outro cliente MCP.

Descoberta e chamadas

Segundo a especificação de ferramentas do MCP, o cliente lista o que um servidor oferece com tools/list e invoca uma ferramenta com tools/call. Cada ferramenta tem um nome, uma descrição e um esquema de entrada. Quando você pede "um clipe de 5 segundos de uma caneca de cerâmica girando sobre uma mesa de nogueira", o Claude lê as descrições das ferramentas, preenche os argumentos e faz a chamada. A Anthropic descreve a regra de acionamento na documentação do conector MCP: o Claude chama uma ferramenta MCP quando o pedido corresponde à capacidade descrita dela, você citando ou não a ferramenta, e não chama ferramentas para responder perguntas de conhecimento geral.

O que volta

O resultado de uma ferramenta pode trazer texto, uma imagem (dados em base64 mais um tipo MIME), áudio, um resource_link ou um recurso incorporado, e opcionalmente um objeto structuredContent que siga um esquema de saída. A especificação pede que servidores que devolvem conteúdo estruturado incluam também os mesmos dados como JSON serializado em um bloco de texto. Na geração, essa é a parte que importa. Um servidor bem construído devolve um link para o arquivo e um pequeno registro estruturado do job (modelo, duração, resolução, custo), e mantém o vídeo em si fora da conversa.

Passo a passo: conectando um servidor MCP hospedado

A documentação de MCP do Claude Code traz a forma geral para um servidor remoto: claude mcp add --transport http <name> <url>, com um --header "Authorization: Bearer your-token" opcional para servidores que autenticam com uma chave estática.

Crie uma chave. Uma chave por projeto ou por agente, para revogar uma sem quebrar as outras.
Escolha um escopo. Local é o padrão e fica em ~/.claude.json apenas para o projeto atual. Project grava o servidor em um arquivo .mcp.json feito para ser compartilhado pelo repositório. User o deixa disponível em todos os projetos da sua máquina. Defina com -s ou --scope.
Adicione o servidor. Para a Aitachyon: claude mcp add --transport http aitachyon https://aitachyon.com/api/mcp --header "Authorization: Bearer ait_..."
Verifique. claude mcp list mostra todos os servidores configurados e claude mcp get aitachyon inspeciona este. Dentro de uma sessão, /mcp mostra o status da conexão e as ferramentas expostas.
Faça uma primeira chamada barata. Peça uma imagem antes de qualquer vídeo. Isso testa a chave e suas permissões por alguns centavos.

Servidores com OAuth seguem um caminho um pouco diferente: adicione o servidor sem header e depois entre com claude mcp login <name> ou por /mcp dentro do Claude Code. Por baixo, a especificação de autorização do MCP se apoia em OAuth 2.1 com PKCE, registro dinâmico de clientes (RFC 7591), metadados de recurso protegido (RFC 9728) e indicadores de recurso RFC 8707. Os dois caminhos terminam com um token bearer em cada requisição.

Três armadilhas de configuração

Escopo project e chaves em texto puro não combinam. Um arquivo .mcp.json foi feito para ser commitado. Coloque um token bearer nele, faça push, e a chave fica no seu histórico do git. Mantenha servidores com chave nos escopos local ou user.
Variáveis de ambiente com nome de segredo são lidas como vazias. A documentação do Claude Code informa que variáveis cujo nome contém TOKEN, SECRET, PASSWORD, KEY ou AUTH são lidas como vazias quando usadas na URL ou nos headers de um servidor remoto. Um header montado a partir de AITACHYON_API_KEY sai em branco e o servidor rejeita a chamada. Passe a chave direto no comando add.
Chaves ficam fora da URL. A especificação de autorização exige tokens de acesso no header Authorization a cada requisição e os proíbe na query string, onde iriam parar nos logs de proxies e servidores.

Permissões: decida o que o agente pode gastar sem perguntar

Uma ferramenta de geração gasta dinheiro a cada chamada, então merece mais atenção do que uma de leitura de arquivos. A especificação de ferramentas do MCP diz que deve sempre haver uma pessoa no circuito capaz de negar invocações, e que os clientes devem mostrar as entradas antes de chamar. O Claude Code implementa isso com regras de permissão que apontam para ferramentas MCP pelo prefixo mcp__.

mcp__aitachyon em uma regra allow deixa o servidor inteiro rodar sem confirmações.
mcp__aitachyon em uma regra deny o bloqueia em um projeto, útil em repositórios onde ninguém deveria gerar mídia.
mcp__* como regra deny bloqueia todas as ferramentas MCP de uma vez.

Dois detalhes poupam tempo de depuração. O Claude Code ignora qualquer regra mcp__ escrita com parênteses e a lista na caixa de configurações inválidas e no claude doctor. Para casar com o valor de um parâmetro específico em uma ferramenta MCP, passe uma regra deny por --disallowedTools.

Uma regra de decisão para aprovações

Primeira semana com um servidor novo: aprove cada chamada à mão e leia o modelo, a duração e a resolução que o Claude preencheu, porque são eles que definem o preço.
Depois de dez chamadas seguidas com argumentos sensatos: libere as ferramentas de imagem e mantenha as de vídeo sob aprovação. Imagens custam centavos; um lote de vídeo custa dólares.
Execuções sem supervisão: libere tudo, mas só com uma chave dedicada, que tenha seu próprio alerta de gasto e possa ser revogada com um clique.

Pedindo mídia em linguagem normal

O Claude escolhe padrões razoáveis, e esses padrões costumam ser mais longos, mais nítidos ou mais barulhentos do que a cena precisa. Todo pedido de vídeo deve fixar quatro coisas: o modelo (ou o equilíbrio que importa para você), a duração, a resolução ou proporção de tela, e se você precisa de áudio.

Antes e depois

Antes: "Faça um vídeo da nossa caneca para a página inicial."

Modelo, duração, formato e áudio ficam a critério do agente, que pode ligar um áudio nativo que você vai silenciar de qualquer jeito.

Depois: "Gere um clipe de 5 segundos em 16:9 no Kling v3, sem áudio: uma caneca de cerâmica branca fosca girando devagar sobre uma mesa de nogueira, luz suave de janela vinda da esquerda, pouca profundidade de campo. Salve em public/media/hero-mug.mp4 e informe a ref e o custo."

O segundo prompt fixa o preço antes da chamada. No momento da escrita, o Kling v3 na Aitachyon custa US$ 0,16 por segundo sem áudio e US$ 0,32 por segundo com áudio nativo, então esse clipe sai por 5 × US$ 0,16 = US$ 0,80. Acrescentar "com áudio" leva a US$ 1,60 por um som que vai tocar mudo na maioria das páginas iniciais.

Um modelo de pedido reutilizável

Cole isto no CLAUDE.md do seu projeto para que todo pedido leve as mesmas restrições:

Ativo: imagem, clipe ou locução, e quantos
Modelo: um modelo pelo nome, ou "o mais barato que suporte X"
Especificações: duração em segundos, resolução, proporção (9:16, 16:9, 1:1)
Áudio: nenhum, nativo ou uma locução separada
Conteúdo: assunto, ação, cenário, luz, câmera
Saída: caminho de destino e padrão de nome de arquivo
Orçamento: "pare e pergunte se o lote passar de US$ X"
Relatório: "liste cada arquivo com ref, modelo e custo, depois o total"

As duas últimas linhas são as que as pessoas pulam, e são elas que deixam os números no histórico do terminal ao lado dos arquivos.

Escolhendo o modelo por plano, com as trocas explícitas

Com uma conta por trás de um servidor MCP, o modelo passa a ser um argumento por plano em vez de um compromisso por assinatura. Os preços abaixo são os preços por chamada da Aitachyon no momento da escrita; a tabela completa está em aitachyon.com/models e em JSON em https://aitachyon.com/api/pricing.

Vídeo

Hailuo 02, US$ 0,085/s. A opção de vídeo mais barata da lista. Use para rascunhos, testes de gancho e tudo em que volume importa mais que acabamento.
Kling v3, US$ 0,16/s sem áudio, US$ 0,32/s com áudio nativo. O áudio dobra o preço, então decida clipe a clipe. As trocas em relação ao Seedance estão na comparação Kling v3 contra Seedance 2.5.
Veo 3.1 Fast, a partir de US$ 0,19/s. Como referência, a página de preços da API Gemini do Google lista o Veo 3.1 Fast a US$ 0,10 por segundo em 720p, US$ 0,12 em 1080p e US$ 0,30 em 4K, o Veo 3.1 Standard a US$ 0,40 por segundo e um nível Lite a partir de US$ 0,05. Se o Veo é o único modelo que você vai chamar, ir direto ao Google sai mais barato por segundo. Um agregador ganha a margem com os outros modelos na mesma chave e com o registro de custo por job. Mais no guia da API do Veo 3.1 Fast.
Wan 2.7, US$ 0,19/s. Uma segunda tentativa útil em um plano que outro modelo insiste em errar.
Seedance 2.5, US$ 0,20/s em 480p, US$ 0,44/s em 720p. A resolução mais que dobra o preço, então faça rascunhos em 480p e renderize de novo em 720p só os que ficarem.

Imagens

Seedream 4.0 a US$ 0,057 por imagem e FLUX.2 [pro] de US$ 0,057 a US$ 0,086: a faixa baixa, boa para fotos de produto e fundos.
Nano Banana, US$ 0,13 por imagem. Nano Banana contra FLUX.2 Pro para imagens de produto mostra quando o preço maior vale a pena.
gpt-image-2, de US$ 0,10 a US$ 0,40 por imagem. A maior variação de preço, então fixe o tamanho no prompt.

Voz

A locução da ElevenLabs custa de US$ 0,043 a US$ 0,086 por 450 caracteres no momento da escrita. Os modelos por baixo diferem em limites e cobertura de idiomas: a ElevenLabs documenta o eleven_v3 com 5.000 caracteres e mais de 70 idiomas, o eleven_multilingual_v2 com 10.000 caracteres e 29 idiomas, e o eleven_flash_v2_5 com 40.000 caracteres e 32 idiomas. Em roteiros do tamanho de um anúncio o limite de caracteres raramente pesa, mas a lista de idiomas pesa assim que você localiza. A conta por minuto está no detalhamento do custo de locução com a API da ElevenLabs.

As contas de três lotes reais

Preços por segundo e por imagem tornam um lote previsível, desde que você multiplique antes de apertar enter. Todos os valores usam os preços da Aitachyon no momento da escrita.

Lote 1: 20 clipes de gancho para teste de criativos

Vinte aberturas de 5 segundos, cada uma testando uma primeira frase diferente de uma lista como estas fórmulas de gancho.

Hailuo 02: 20 × 5 s × US$ 0,085 = US$ 8,50
Kling v3, sem áudio: 20 × 5 s × US$ 0,16 = US$ 16,00
Seedance 2.5 em 720p: 20 × 5 s × US$ 0,44 = US$ 44,00

A sequência sensata: rascunhe os vinte no modelo mais barato, fique com os três que funcionam melhor e renderize de novo só esses no modelo que você entregaria. Três vencedores no Seedance em 720p somam 3 × US$ 2,20 = US$ 6,60, num total de US$ 15,10 contra US$ 44,00 para renderizar tudo no nível mais alto.

Lote 2: 50 fotos de produto

Seedream 4.0: 50 × US$ 0,057 = US$ 2,85
FLUX.2 [pro]: 50 × US$ 0,057 a US$ 0,086 = US$ 2,85 a US$ 4,30
Nano Banana: 50 × US$ 0,13 = US$ 6,50

Lote 3: uma semana de shorts

Sete shorts, cada um montado com três clipes de 5 segundos do Kling v3 (sem áudio), três keyframes do Seedream e uma locução de 900 caracteres.

Clipes: 15 s × US$ 0,16 = US$ 2,40 por short
Keyframes: 3 × US$ 0,057 = US$ 0,171 por short
Locução: 2 × 450 caracteres a no máximo US$ 0,086 = até US$ 0,172 por short
Por short: cerca de US$ 2,74. Na semana: cerca de US$ 19,20

As mesmas contas para todos os modelos estão em preços de APIs de geração de vídeo com IA em 2026.

Renders longos, limites de saída e como receber os arquivos

Tamanho da saída

O Claude Code tem um orçamento rígido para o que uma ferramenta pode devolver. Segundo a documentação de MCP do Claude Code, ele avisa quando a saída de uma ferramenta MCP passa de 10.000 tokens e a limita a 25.000 tokens por padrão, ajustável pela variável de ambiente MAX_MCP_OUTPUT_TOKENS (por exemplo 50000). Um servidor que devolvesse vídeo cru em base64 bateria nesse teto já no primeiro clipe. Um link e um registro estruturado curto mantêm cada resultado pequeno e deixam a janela de contexto para o seu trabalho de verdade.

Timeouts

Vídeo demora mais que uma chamada de ferramenta comum. A mesma documentação permite definir um timeout de ferramenta por servidor no .mcp.json, em milissegundos com mínimo de 1000, e observa que conexões HTTP e SSE caem por inatividade após 5 minutos por padrão. Se um lote longo morrer no meio, confira isso antes de culpar o modelo. Peça os renders em grupos pequenos e faça o agente reportar após cada grupo, assim uma conexão perdida só custa o status do grupo em andamento.

Refs estáveis como passagem de bastão

Na Aitachyon, cada arquivo gerado recebe uma ref estável (img_, scn_, vo_ e assim por diante) que o código pode buscar com GET /api/generations/{ref}. Isso traça uma fronteira limpa entre o agente e o seu build:

No Claude Code, gere o ativo e peça a ref no relatório.
Registre a ref em um arquivo de manifesto no repositório, ao lado do prompt que a produziu e do custo.
Um script de build ou etapa de CI busca cada ref pela API HTTP simples com a mesma chave bearer.
Ao regenerar um plano, troque uma ref no manifesto e o pipeline a assume.

O manifesto serve também como livro de custos por plano. A versão mais longa desse pipeline, com roteirização por cima, está em automatizando a produção de vídeo com agentes de IA.

Rodando sem o Claude Code

O mesmo servidor hospedado pode ser chamado do seu próprio backend. O conector MCP da Anthropic permite que a Messages API alcance servidores MCP remotos sem um cliente MCP separado. Está em beta sob o header mcp-client-2025-11-20, aceita listas de ferramentas permitidas e bloqueadas, aceita tokens bearer OAuth e vários servidores por requisição, e não é elegível para retenção zero de dados. A lista de ferramentas permitidas é a parte útil aqui: exponha as ferramentas de imagem a um recurso voltado ao cliente e mantenha as de vídeo desligadas até calcular o custo.

Controle de gastos quando um agente segura a chave

Um agente que pode chamar uma ferramenta paga em loop também pode gastar dinheiro em loop. Uma instrução mal lida, "faça variações" entendido como cinquenta em vez de cinco, é uma falha realista. Os controles que ajudam, ordenados por quão cedo pegam o problema:

Orçamento no prompt. "Pare e pergunte se o lote custar mais de US$ 10" é uma regra que o agente consegue checar com os preços por segundo.
Aprovação nas ferramentas de vídeo, como definido na seção de permissões.
Uma chave por agente ou projeto. A Aitachyon acompanha o gasto por chave de API, dispara um alerta quando uma chave gasta rápido demais e revoga uma chave com um clique.
Saldo pré-pago. Quando acaba, as chamadas param. É um teto que um loop descontrolado não consegue cruzar.
Reembolso automático em caso de falha. Um render que falha é reembolsado ao centavo, então novas tentativas não cobram em dobro em silêncio.

A Anthropic acrescenta a regra básica em sua nota sobre servidores MCP remotos: são serviços de terceiros, então conecte-se apenas a servidores em que você confia e revise as práticas de segurança e os termos de cada um.

FAQ

Como adiciono um servidor MCP ao Claude Code?

Execute claude mcp add --transport http <name> <url>, acrescentando --header "Authorization: Bearer <key>" para servidores com chave. Use -s para escolher o escopo local, project ou user e confirme com claude mcp list ou /mcp dentro de uma sessão. Para servidores OAuth, adicione sem o header e entre com claude mcp login <name>.

O Claude Code consegue gerar vídeo sozinho?

O Claude Code passa a renderização para uma ferramenta de um servidor MCP conectado, que executa o modelo de vídeo. Com esse servidor conectado, você pede em linguagem normal e o Claude preenche os argumentos da ferramenta, faz a chamada e devolve o resultado.

Por que meu servidor MCP rejeita a chave que coloquei em uma variável de ambiente?

O Claude Code lê como vazias as variáveis de ambiente cujo nome contém TOKEN, SECRET, PASSWORD, KEY ou AUTH quando aparecem na URL ou nos headers de um servidor remoto, então o header sai em branco. Passe a chave direto no comando claude mcp add e mantenha o servidor no escopo local ou user.

Quanto custa um clipe de vídeo com IA de 5 segundos?

Depende do modelo e das configurações. Nos preços da Aitachyon no momento da escrita, 5 segundos custam cerca de US$ 0,43 no Hailuo 02, US$ 0,80 no Kling v3 sem áudio, US$ 1,60 com áudio nativo, e US$ 1,00 ou US$ 2,20 no Seedance 2.5 em 480p ou 720p.

Fontes

Se você quer esta configuração sem cinco contas separadas, a Aitachyon reúne os modelos de vídeo, imagem e voz acima atrás de uma chave, um servidor MCP hospedado e um saldo pré-pago, com cada job detalhado por modelo e custo. O comando de uma linha para o Claude Code e a API HTTP estão na página para desenvolvedores.