Configuração do HeyGen MCP com Claude: servidor remoto para vídeos com avatar

Você digita uma frase no Claude, vai tomar um café e volta para um vídeo com avatar pronto, com um link que pode enviar para um cliente. Essa é a promessa do servidor MCP remoto da HeyGen, e a configuração leva cerca de cinco minutos porque não há nada para instalar. Nenhum servidor local, nenhuma credencial de API colada em um arquivo de configuração, nenhuma cobrança separada. Você faz login uma vez pelo OAuth e o Claude pode trabalhar dentro da sua conta na HeyGen.

Este passo a passo mostra como configurar o MCP da HeyGen no Claude para os três lugares onde as pessoas realmente usam o Claude: o aplicativo web, o aplicativo de desktop e o Claude Code. Você recebe o endpoint exato, o comando exato do terminal, prompts que geram vídeos que dá para usar, os fatos sobre créditos e limites de taxa da própria documentação da HeyGen e uma lista de correções para os erros que mais atrapalham. Perto do final há um tutorial curto para rodar o motor Avatar V da HeyGen diretamente no PicassoIA, para os dias em que você quer um apresentador falante sem abrir um assistente.

💡 Resposta rápida: o endpoint é https://mcp.heygen.com/mcp/v1/. Adicione-o ao Claude como um conector personalizado (ou execute um comando claude mcp add no Claude Code), aprove o login OAuth e então peça um vídeo.

O que o MCP remoto realmente faz

MCP significa Model Context Protocol, o padrão aberto que permite a um assistente de IA chamar ferramentas dentro de outros aplicativos. A HeyGen executa o servidor na própria infraestrutura, então o Claude se comunica com um endpoint hospedado, e não com um programa no seu notebook. Segundo a documentação, o uso consome os créditos já incluídos no seu plano da HeyGen, e o conector funciona em todos os planos.

Depois de conectado, o Claude pode fazer trabalho de produção real a partir de uma janela de chat:

• Escrever e renderizar a partir de um prompt. O Video Agent da HeyGen escolhe o avatar, redige o roteiro, monta as cenas e renderiza o resultado.
• Dirigir um avatar. Um avatar da HeyGen, ou uma imagem que você fornece, fala seu roteiro exato com sincronização labial.
• Traduzir vídeos prontos para outros idiomas mantendo o movimento da boca alinhado.
• Gerenciar a biblioteca. Listar, buscar e excluir vídeos, além de trabalhar com modelos, kits de marca e pastas.
• Lidar com vozes. Navegar por um catálogo com mais de 500 vozes, criar uma nova a partir de uma descrição em texto ou clonar uma a partir de um arquivo de áudio.

A HeyGen conta mais de 48 funções no servidor e lista suporte para Claude (web, desktop e Code), Cursor, Gemini CLI, Codex CLI, Lovable, Manus, Superhuman e agentes baseados em OpenAI, além de qualquer cliente MCP personalizado.

Hospedado, não instalado

Os servidores comunitários da HeyGen publicados antes rodam na sua própria máquina e exigem uma credencial de API guardada em uma variável de ambiente. O servidor remoto elimina as duas tarefas. A autenticação é OAuth, então nenhum segredo fica em um arquivo de configuração, e a HeyGen mantém as ferramentas do lado dela. Você cola uma URL e aprova uma tela de login.

Escolha o caminho de configuração

A HeyGen documenta três formas de permitir que um agente trabalhe com a plataforma. Os créditos vêm do seu plano em todos os casos.

💡 A recomendação da HeyGen para agentes é direta: tente primeiro o servidor MCP, recorra à CLI em seguida e use chamadas de API bruta por último. Nunca cole uma credencial de API em uma janela de chat.

Conecte a HeyGen ao Claude

Claude na web e no desktop

Os nomes dos menus mudam um pouco entre versões do aplicativo, mas o fluxo é sempre o mesmo.

1. Abra o Claude e vá em Configurações, depois em Conectores.
2. Pesquise por HeyGen. Se ela aparecer, clique em Conectar. Se não aparecer, escolha Adicionar conector personalizado.
3. Dê o nome HeyGen e cole https://mcp.heygen.com/mcp/v1/.
4. Clique em Conectar. Uma aba do navegador abrirá na tela de OAuth da HeyGen.
5. Entre na conta da HeyGen cujos créditos você quer usar e depois aprove o acesso.
6. Abra um novo chat e confirme que o conector da HeyGen está ativado nele.

A etapa do OAuth é a mais importante. Os créditos pertencem à conta que você aprova, então confira duas vezes se você entrou no workspace certo antes de avançar.

💡 Executando um agente personalizado no próprio domínio? A HeyGen pede que você envie esse domínio pelo formulário de integração para que ele seja incluído na lista de permissões.

Claude Code em um comando

Execute isto uma vez no seu terminal:

claude mcp add --transport http heygen https://mcp.heygen.com/mcp/v1/

Copiar prompt

Depois abra o Claude Code, digite /mcp, escolha heygen e conclua o login OAuth pelo navegador. Adicione --scope user se quiser que o servidor fique disponível em todos os projetos, e não apenas no atual.

Equipes que compartilham um repositório podem versionar uma configuração de projeto:

{
  "mcpServers": {
    "heygen": {
      "type": "http",
      "url": "https://mcp.heygen.com/mcp/v1/"
    }
  }
}

Copiar prompt

O arquivo não contém credenciais, então cada integrante se autentica sozinho e os créditos ficam vinculados à pessoa que pediu o vídeo.

Verifique a conexão

Pergunte ao Claude: "Chame a ferramenta get_current_user da HeyGen e diga qual conta está conectada." A própria documentação da HeyGen usa essa chamada como verificação de funcionamento. No Claude Code, a ferramenta aparece como mcp__heygen__get_current_user. Se o nome da conta corresponder ao que você espera, está tudo pronto. Se o Claude disser que não tem ferramentas da HeyGen, vá para a tabela de correções mais abaixo.

Faça seu primeiro vídeo com avatar

A renderização é assíncrona. A HeyGen diz que os vídeos normalmente ficam prontos em 1 a 5 minutos, e o Claude precisa chamar uma ferramenta de status para saber quando. Diga isso no seu prompt, senão o assistente pode entregar um ID e parar.

Prompts que funcionam

O Video Agent é o caminho mais curto da ideia até o vídeo. Ele tem dois modos: generate dispara e esquece, enquanto chat permite refinar ao longo de várias interações. Um prompt forte define seis coisas:

• Objetivo: o que o espectador deve fazer depois de assistir
• Público: quem está assistindo
• Duração: 15, 30 ou 60 segundos
• Tom: calmo, animado ou formal
• Formato: 16:9 widescreen ou vertical 9:16
• Estilo: uma escolha da lista de estilos

"Use o HeyGen Video Agent para criar um vídeo explicativo de 30 segundos sobre uma mesa em pé. Apresentadora simpática, tom calmo, vertical 9:16, estilo de escritório limpo. Continue verificando o status até o vídeo ficar pronto e então me envie o link."

Antes de renderizar, peça ao Claude para chamar list_video_agent_styles. Os estilos são modelos curados que controlam a composição das cenas, o ritmo e a aparência, e você pode filtrá-los por tags como "cinematográfico" ou "retro-tech".

Vídeos com avatar direcionados

Quando o texto precisa ser exato, como uma lista de preços ou um aviso de conformidade, pule o agente e use create_video. Um avatar escolhido ou uma imagem fixa fala seu roteiro ou áudio com sincronização labial. Você escolhe Avatar III, Avatar IV ou Avatar V como motor, e o Avatar IV é o padrão. O Avatar V funciona apenas com avatares que o suportam.

"Use create_video com meu avatar de marca e este roteiro exato. Motor Avatar V, 1080p, 16:9. Retorne o video_url quando estiver pronto."

A ferramenta get_video retorna o status, video_url, thumbnail_url, a duração e os detalhes de qualquer falha, então é ela que você deve chamar quando uma renderização parecer travada.

Traduza com sincronização labial

A tradução usa três ferramentas: list_video_translate_languages para códigos válidos, create_video_translate para iniciar o trabalho e get_video_translate_caption para buscar as legendas depois. A HeyGen oferece modos de velocidade e de precisão, então um rascunho rápido e uma versão final caprichada podem sair do mesmo vídeo de origem. O PicassoIA traz a mesma família de modelos, com o Video Translate para dublagem em mais de 150 idiomas, além de Lipsync Precision e Lipsync Speed.

Os lotes de tradução aceitam até 100 itens por requisição, o que torna possível localizar uma biblioteca inteira de treinamentos em uma tarde.

O que as ferramentas oferecem e custam

Grupos de ferramentas em resumo

Créditos, prazos e limites

• Créditos: nenhuma cobrança extra além do seu plano. O uso consome os créditos do plano, e clones de voz profissionais custam 1 crédito por geração de look.
• Remoção de palavras de preenchimento: US$ 0,30 por minuto de origem, com um mínimo de um minuto.
• Prazo: a maioria das renderizações termina em 1 a 5 minutos. Consulte o status com backoff exponencial e respeite qualquer cabeçalho Retry-After.
• Limite de taxa: 30 requisições por minuto por membro do workspace no endpoint profissional de síntese de voz.
• Tamanho do lote: 100 itens por requisição em todos os tipos de lote.
• Vídeos de referência: até 12 no modo de referência a vídeo, com proporções de 1:4 a 4:1.
• Modelos: excluir um deles é uma exclusão lógica, e os vídeos já gerados permanecem intactos.

Corrija problemas comuns

Sintomas e correções

Hábitos que economizam créditos

• Peça ao Claude para repetir o roteiro, o avatar e o formato antes de renderizar, e responda "vai".
• Teste um clipe de 10 a 15 segundos antes de um longo.
• Corrija o roteiro primeiro. Renderizar de novo por causa de um erro de digitação queima créditos à toa.
• Rode um lote só depois que uma amostra tiver sido aprovada.

Onde o PicassoIA entra

Os motores da HeyGen não estão presos dentro do aplicativo da HeyGen. O PicassoIA lista vários deles ao lado de outros modelos de vídeo falante, o que ajuda em testes A/B com o mesmo roteiro.

Roteiros importam tanto quanto as renderizações. Os modelos de linguagem no PicassoIA, como Claude Sonnet 5, Claude Fable 5 e Claude Opus 4.7, podem redigir e enxugar um roteiro antes que ele chegue a qualquer ferramenta de avatar. Isso dá uma divisão clara: escreva com um modelo de linguagem, renderize com um modelo de avatar e mantenha cada etapa fácil de repetir.

Como usar o Avatar V no PicassoIA

O caminho pelo MCP serve para quem vive dentro do Claude. Se você prefere preencher um formulário, o Avatar V no PicassoIA transforma um roteiro digitado em um vídeo de apresentador falante, sem câmera, estúdio ou atores.

Passo a passo

1. Abra a página do Avatar V no PicassoIA.
2. Cole seu roteiro em input_text. O limite é de menos de 5.000 caracteres por execução.
3. Adicione um voice_id e um avatar_id. Ambos são obrigatórios, e o avatar precisa oferecer suporte ao Avatar V. Esses IDs vêm dos catálogos da HeyGen, e o conector remoto consegue listar vozes, então o Claude é uma boa forma de montar uma lista curta.
4. Escolha o aspect_ratio: 16:9 para widescreen ou 9:16 para vertical.
5. Escolha uma resolution: 720p, 1080p (o padrão) ou 4k.
6. Defina voice_speed entre 0,5 e 1,5, e ative caption se quiser legendas embutidas.
7. Execute a geração e baixe o arquivo final. A execução de exemplo na galeria do modelo levou cerca de 137 segundos em 1080p.

Configurações que vale ajustar

💡 Dois hábitos de roteiro que compensam: mantenha frases curtas o bastante para falar em um fôlego só e escreva por extenso números e siglas do jeito como quer que sejam falados.

Experimente no PicassoIA hoje

Agora você tem dois caminhos para o mesmo resultado. Conecte a HeyGen ao Claude quando quiser que a criação de vídeo aconteça dentro de uma conversa, com uma frase iniciando a renderização. Use o PicassoIA quando preferir escolher as configurações você mesmo e comparar motores lado a lado.

Escolha um roteiro curto que você já tenha, talvez uma introdução de produto ou uma etapa de treinamento, e rode-o no Avatar V em 720p. Depois envie o mesmo material pelo Video Translate para ouvi-lo em um segundo idioma. Dez minutos de experimentos no PicassoIA vão dizer mais sobre o seu fluxo de trabalho do que qualquer ficha técnica. Abra a plataforma, teste um modelo e crie seu primeiro vídeo com avatar hoje.