Conecte seu Agent via MCP

Escolha seu método de conexão

FreeLipSync expõe um terminal MCP remoto em https://freelipsync.com/mcp. Ele oferece ao agente os mesmos recursos de geração de vídeo e créditos de conta que o REST API. Você deve ter uma conta FreeLipSync registrada; o acesso anônimo não é suportado. Use sua origem de teste ao testar no teste.

A configuração API Key e OAuth são suportadas. Escolha uma origem de credencial por entrada de servidor. Um arquivo de configuração existente continua sendo uma forma válida de conexão; você não precisa usar OAuth.

Crie uma chave e copie o segredo completo na janela de criação. OAuth não exige copiar uma chave. Cada conta aceita até 5 API Keys e 5 conexões OAuth independentes. Usar API Key ocupa uma vaga de chave, não de conexão OAuth. Os dois métodos compartilham o saldo, os modelos e os limites da conta.

Fluxo de autorização OAuth

1. Adicione o HTTPS URL remoto em seu cliente, sem um cabeçalho Authorization ou configuração API Key.
2. Escolha Connect/Authenticate/Sign in, conforme apropriado para o cliente.
3. No navegador, faça login em sua conta FreeLipSync e revise o cliente solicitante e as permissões.
4. Crie uma nova conexão (padrão) ou escolha explicitamente uma conexão existente para substituir. Uma autorização bem-sucedida em outro dispositivo normalmente conta separadamente.
5. Permita que o agente gaste seus créditos de API adquiridos e depois autorize. Retorne ao cliente e verifique as ferramentas abaixo.

Você pode negar o pedido. Se todos os slots de conexão 5 forem usados, substitua ou revogue explicitamente uma conexão antiga no console Agent; a nova autorização não remove silenciosamente uma conexão. A atualização do token e a reconexão de uma autorização existente não adicionam um slot. Uma conexão OAuth pode gastar os créditos da sua conta quando a geração for enviada.

A compatibilidade do cliente OAuth é importante: FreeLipSync suporta metadados de identidade de cliente publicados (CIMD) e clientes pré-registrados, em vez de um endpoint de registro dinâmico aberto. Use uma versão de cliente compatível ou um ID de cliente atribuído quando houver suporte. Se um cliente oferecer suporte apenas ao registro dinâmico e a entrada falhar, use o método API Key ou entre em contato com o suporte para verificar o registro do cliente.

Compatibilidade do cliente e diferenças OAuth

O registro OAuth e a autenticação de token são separados. FreeLipSync suporta CIMD ou um ID de cliente pré-registrado, com none + PKCE ou private_key_jwt. Ele compreende a matriz CIMD mais recente de métodos suportados, bem como o campo de método único mais antigo. Os clientes assinados usam suas chaves públicas publicadas automaticamente; os usuários não carregam uma chave privada.

FreeLipSync não oferece registro dinâmico aberto (DCR), autenticação secreta do cliente ou concessão client_credentials. Se um cliente exigir DCR, use sua opção de cliente público pré-registrado, quando disponível, ou use a configuração API Key em um cliente que suporte cabeçalhos Bearer personalizados. Obtenha um ID atribuído e registre o retorno de chamada real antes de configurá-lo. Um ID de cliente API Key e OAuth são credenciais diferentes.

Codex: arquivo de configuração ou OAuth

Adicione ou edite um servidor HTTP remoto em Plugins → MCPs em Codex; algumas versões usam servidores Settings → MCP. Esta entrada MCP local suporta a configuração API Key e é separada da entrada OAuth do plug-in hospedado descrita acima.

Escolha uma origem de credencial. Os exemplos usam https://freelipsync.com/mcp. Para teste, substitua-o por https://staging.freelipsync.com/mcp e crie a chave em sua conta de teste. As chaves de produção e de teste não são intercambiáveis.

Opção A: cole um API Key nas configurações da área de trabalho

Use esta opção quando não desejar configurar variáveis de ambiente. Crie uma chave no console Agent, copie o segredo completo e preencha:

Utilize um espaço após Bearer; a chave em si não tem prefixo de portador. Não nomeie o cabeçalho FLS_API_KEY nem cole o segredo em Bearer token env var. Salve e reconecte; se o cliente ainda usar uma configuração antiga, reinicie-o ou abra uma nova sessão.

A entrada ~/.codex/config.toml pessoal equivalente é:

[mcp_servers.freelipsync]
url = "https://freelipsync.com/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

Opção B: forneça API Key por meio de uma variável de ambiente

Bearer token env var usa um nome de variável, não um segredo. Defina-o como FLS_API_KEY. Essa variável deve existir no ambiente do processo em execução Codex. Seu valor é a chave completa sem Bearer ; Codex adiciona o prefixo.

O arquivo de configuração pessoal correspondente é:

[mcp_servers.freelipsync]
url = "https://freelipsync.com/mcp"
bearer_token_env_var = "FLS_API_KEY"

Para Codex CLI iniciado a partir de um terminal:

export FLS_API_KEY='YOUR_API_KEY'
codex mcp list
codex
# Inspect /mcp in the new session.

Exportar uma variável em outro terminal não atualiza um aplicativo de desktop já em execução. Um aplicativo iniciado no menu Dock ou Iniciar também pode não herdar variáveis de terminal. Se você não tiver certeza de como fornecer o ambiente de processo de desktop, use a opção A.

Headers cria cabeçalhos de solicitação HTTP. Headers from environment variables lê valores de cabeçalho de variáveis de ambiente existentes. Nenhum dos campos cria uma variável de ambiente do sistema. Um cabeçalho denominado FLS_API_KEY não preenche a configuração Bearer e um espaço reservado cinza como MCP_BEARER_TOKEN não significa que a variável foi configurada.

Opção C: autorizar no navegador com OAuth

Insira apenas URL. Deixe Bearer token env var, Headers e Headers from environment variables vazios, incluindo a remoção de qualquer linha Authorization anterior. Salve, escolha Authenticate / Sign in quando oferecido, faça login em FreeLipSync e aprove a conexão. Nenhum API Key precisa ser criado ou colado.

Para um arquivo de configuração, mantenha apenas:

[mcp_servers.freelipsync]
url = "https://freelipsync.com/mcp"

Comandos CLI:

# Run the next line only if this server name does not exist; otherwise edit it.
codex mcp add freelipsync --url https://freelipsync.com/mcp
codex mcp login freelipsync
codex mcp list

Substitua freelipsync nos comandos pelo nome do servidor salvo. Os três blocos TOML acima são alternativas; mantenha uma entrada para o servidor. Remova a configuração codificada antes de mudar para OAuth: o login não repara um cabeçalho Authorization incorreto que ainda está configurado.

Verifique a conexão depois de salvar

Em uma nova sessão, pergunte: "Ligue para FreeLipSync get_capabilities e get_usage para verificar meus modelos e créditos. Não gere um vídeo." Uma resposta bem-sucedida da conta confirma a conexão; um nome de servidor que aparece sozinho na lista não aparece.

Para HTTP 401, verifique se URL e a chave pertencem ao mesmo ambiente, a chave está completa, o cabeçalho estático é Authorization: Bearer YOUR_API_KEY e nenhuma configuração Authorization antiga ou duplicada permanece. Com a opção B, verifique também o ambiente do processo que realmente lança o cliente.

Consulte o guia oficial OpenAI MCP e referência de configuração para definições de campo.

Claude Code: arquivo de configuração ou OAuth

Para acesso API Key, coloque esta entrada em uma configuração MCP pessoal/local ou mescle-a em .mcp.json para o projeto. A variável de ambiente é expandida por Claude Code. Mantenha a chave real fora da configuração compartilhada e inicie Claude Code com a variável definida.

{
  "mcpServers": {
    "freelipsync": {
      "type": "http",
      "url": "https://freelipsync.com/mcp",
      "headers": {"Authorization": "Bearer ${FLS_API_KEY}"}
    }
  }
}

export FLS_API_KEY='YOUR_API_KEY'
claude mcp list

Para OAuth, remova primeiro a entrada codificada ou seu cabeçalho Authorization, adicione um servidor HTTP somente URL e autentique via /mcp em uma sessão Claude Code interativa:

claude mcp add --transport http --scope user freelipsync https://freelipsync.com/mcp
claude
# In Claude Code, run /mcp and choose Authenticate for freelipsync.

Use um método de cada vez. Um cabeçalho de portador inválido configurado não será corrigido ao fazer login por meio de um fluxo diferente. Consulte o guia MCP oficial do Claude Code.

Claude Desktop e Claude web

Para OAuth, abra a página de gerenciamento Connectors de Claude, adicione um conector web/remoto personalizado chamado FreeLipSync e insira https://freelipsync.com/mcp. Escolha entrar e usar a identidade de cliente publicada de Claude, quando disponível; preencha a página de autorização FreeLipSync. Uma organização pode exigir que seu proprietário habilite o conector primeiro. Os conectores remotos devem alcançar um terminal HTTPS público; localhost não pode ser acessado pela nuvem de Claude. Consulte o guia do conector remoto de Claude.

No método antigo de arquivo de configuração do Claude Desktop, um cliente que só aceita stdio precisa de uma ponte local para o servidor remoto; colar uma url remota em uma configuração stdio não basta. Com Node.js / npx instalado, adicione esta entrada a claude_desktop_config.json (abra-o nas configurações de desenvolvedor do Desktop) e reinicie o Desktop. Substitua o marcador localmente e mantenha esse arquivo pessoal privado.

{
  "mcpServers": {
    "freelipsync": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://freelipsync.com/mcp",
        "--header", "Authorization:${FLS_AUTH_HEADER}"
      ],
      "env": {"FLS_AUTH_HEADER": "Bearer YOUR_API_KEY"}
    }
  }
}

mcp-remote é uma ponte de compatibilidade de terceiros, não um pacote FreeLipSync. Revise suas instruções do mantenedor e sua versão instalada. Seu argumento de cabeçalho oferece suporte à expansão do ambiente; o formato acima também evita espaços dentro do argumento. Prefira o suporte HTTP nativo do cliente, quando disponível. Este arquivo Desktop não é o mecanismo de configuração para Claude web.

Cursor: arquivo de configuração ou OAuth

Para acesso API Key, use seu ~/.cursor/mcp.json pessoal (ou um projeto .cursor/mcp.json mantido fora do controle de origem quando contém uma chave). Substitua o espaço reservado localmente. Não presuma que a expansão do ambiente a partir do formato de outro cliente funciona na versão Cursor instalada.

{
  "mcpServers": {
    "freelipsync": {
      "url": "https://freelipsync.com/mcp",
      "headers": {"Authorization": "Bearer YOUR_API_KEY"}
    }
  }
}

Para OAuth, utilize a mesma entrada apenas com url, removendo o objeto de cabeçalhos. Nas configurações MCP do Cursor, conecte/autentique e conclua a autorização do navegador, se oferecido. Recarregue ou reinicie o cliente após alterar sua configuração e verifique as ferramentas no modo Agent. Se o fluxo de registro dessa versão for incompatível, use a configuração Key acima. Consulte as instruções MCP oficiais do Cursor.

VS Code e GitHub Copilot

Para uma configuração VS Code MCP nativa, crie .vscode/mcp.json com uma entrada de senha em vez de uma chave real no arquivo:

{
  "inputs": [
    {"type":"promptString","id":"fls-key","description":"FreeLipSync API Key","password":true}
  ],
  "servers": {
    "freelipsync": {
      "type":"http",
      "url":"https://freelipsync.com/mcp",
      "headers":{"Authorization":"Bearer ${input:fls-key}"}
    }
  }
}

Para OAuth, remova inputs e headers, mantendo o tipo de servidor e URL. Inicie/conecte o servidor e siga o prompt de autenticação; o registro do cliente deve ser compatível conforme descrito acima. Selecione suas ferramentas no modo Agent do Copilot e tente o prompt de verificação abaixo. O formato VS Code usa servers, não o mcpServers de outro cliente; entradas interativas não são suportadas por todos os chicotes Copilot ou configurações portáteis. Consulte a referência VS Code MCP.

Verifique as ferramentas e tente um prompt

Primeiro pergunte ao seu agente: "Use FreeLipSync para verificar meus modelos disponíveis e saldo de créditos. Não crie um vídeo ainda." Deverá ligar para get_capabilities e get_usage, sem gastar créditos. Um servidor listado em um arquivo de configuração não é evidência suficiente de que a autenticação funcionou.

Em seguida, tente: "Faça uma pequena foto falada Image Fast a partir da minha imagem e áudio. Faça um orçamento primeiro e me diga os créditos. Aguarde minha confirmação antes de enviar. Se você não conseguir carregar meus arquivos locais, forneça links de upload do navegador." Mantenha a aprovação do cliente para ferramentas de gastos habilitada.

Fazendo upload de arquivos locais de um agente

Existem dois caminhos de arquivo local, além da importação HTTPS. Não passe um caminho local como import_asset URL.

• Um cliente que consegue ler arquivos e enviar requisições HTTP PUT chama create_asset_upload com kind, filename, content_type, size_bytes e idempotency_key. Ele envia os bytes do arquivo à URL retornada, usando os cabeçalhos indicados, e chama confirm_asset_upload. Nunca envie sua API Key a URLs de armazenamento assinadas.
• Um cliente sem acesso a arquivo local/HTTP chama create_asset_upload_session para cada imagem/vídeo/áudio. Você abre browser_upload_url, entra na mesma conta FreeLipSync e faz upload no navegador. O agente retém asset_id e pesquisa get_asset; você não precisa copiar o ID de volta. Não compartilhe o ticket de upload publicamente.
• Para um arquivo HTTPS público existente, import_asset com kind, url, idempotency_key inicia a importação. Espere até estar pronto antes de fazer uma cotação.

Um conector somente URL/nuvem não obtém acesso aos arquivos da área de trabalho simplesmente usando MCP. Por exemplo, os conectores remotos de Claude são executados em sua nuvem, portanto, use links de upload do navegador quando o cliente não puder transferir seu anexo para o URL assinado.

Créditos, novas tentativas e gerenciamento de conexão

API e MCP usam as mesmas taxas: Video Lip Sync / Image Fast, 1 crédito/s; Image Max, 2; Image Super / Music Video, 3. A duração verificada do áudio é arredondada para cima, até o próximo segundo inteiro, com mínimo de 5 segundos. estimate_generation retorna total_points e um ID de cotação; create_generation recebe esse quote_id e uma idempotency_key. Enviar arquivos, consultar uso e estimar não gasta créditos. Uma geração aceita não pode ser cancelada; apenas falha no processamento devolve a reserva original. Veja cobrança e recuperação da API.

Mantenha a mesma cotação e chave de idempotência após um envio incerto. Salve o ID do trabalho retornado e consulte-o; não peça ao agente para “tentar novamente” realizando outra tarefa. Pesquise usando poll_after_seconds, recue em Retry-After e use list_generations para consultar vários trabalhos ativos juntos. API e MCP compartilham o intervalo de leitura da conta, enquanto todos os três pontos de entrada de site/API/MCP compartilham frequência de envio e capacidade de execução de vídeo. O site e API/MCP têm permissões separadas para tarefas inacabadas: Free 1, Starter 3, Pro 10 em cada pool. Todas as credenciais REST/MCP compartilham o pool API/MCP. Consulte por que usar API/MCP para obter exemplos.

Revogue uma conexão Key ou OAuth do console Agent. A revogação de uma chave interrompe o uso futuro dela em todos os clientes que a compartilham, incluindo REST; revogar uma conexão OAuth afeta apenas essa conexão. Nenhuma das operações cancela tarefas já aceitas. A exclusão de uma entrada de cliente local por si só não revoga uma credencial em FreeLipSync. Use chaves separadas ou autorizações independentes quando precisar de revogação separada, para não aumentar a simultaneidade.

Solução de problemas

As configurações do cliente podem mudar entre as versões. Consulte a documentação oficial vinculada de cada cliente para obter as instruções atuais. Precisa de integração direta com HTTP? Leia a documentação da API.