sync. labs

npx add-mcp 'https://mcp.sync.so/mcp'

servidor MCP do sync. labs

Conecte seu agente de IA ao sync. para sincronizar os lábios de vídeos, traduzi-los e dublá-los para outros idiomas, clonar vozes e gerenciar recursos e projetos em um chat ou sessão de programação.

O sync. hospeda este servidor em https://mcp.sync.so/mcp. Você entra com sua conta do sync., então não há nada para instalar nem chave de API para copiar. Cada merge para o main deste repositório faz o deploy lá.

Conecte seu agente

ChatGPT

Abra sync. no ChatGPT e conecte sua conta. No ChatGPT, o sync. Studio também abre dentro do chat.

Claude (claude.ai e Claude Desktop)

1. Abra Configurações → Conectores e escolha Adicionar conector personalizado.
2. Dê o nome sync. e defina a URL como https://mcp.sync.so/mcp.
3. Clique em Conectar e entre no sync.

Claude Code

claude mcp add --transport http sync https://mcp.sync.so/mcp

Em seguida, execute /mcp no Claude Code, selecione sync e entre. Adicione --scope user para usá-lo em todos os projetos.

Codex

codex mcp add sync --url https://mcp.sync.so/mcp
codex mcp login sync

Cursor

Adicione a .cursor/mcp.json em um projeto ou a ~/.cursor/mcp.json para todos os projetos:

{
  "mcpServers": {
    "sync": { "url": "https://mcp.sync.so/mcp" }
  }
}

O Cursor solicitará que você entre no sync. na primeira vez que se conectar.

VS Code

Adicione a .vscode/mcp.json:

{
  "servers": {
    "sync": { "type": "http", "url": "https://mcp.sync.so/mcp" }
  }
}

Outros clientes

Qualquer cliente compatível com servidores MCP remotos por HTTP Streamable com OAuth pode usar https://mcp.sync.so/mcp. O cliente se registra, e você entra no sync. pelo navegador.

O servidor está listado no Registro oficial do MCP como io.github.synchronicity-labs/mcp-server, então clientes e diretórios que consultam o registro podem encontrá-lo e adicioná-lo. server.json é essa listagem.

Servidor local com uma chave de API

Para clientes sem suporte a MCP remoto, além de scripts e CI, execute o servidor localmente por stdio com uma chave de API do sync.:

claude mcp add sync -e SYNC_API_KEY=your-api-key -- npx -y @sync.so/mcp-server@latest

Ou em uma configuração JSON do cliente:

{
  "mcpServers": {
    "sync": {
      "command": "npx",
      "args": ["-y", "@sync.so/mcp-server@latest"],
      "env": { "SYNC_API_KEY": "your-api-key" }
    }
  }
}

Sem SYNC_API_KEY, o servidor inicia um login por dispositivo na primeira execução: acesse a URL exibida e insira o código. O token fica armazenado em cache em ~/.config/sync/mcp-credentials.json.

As versões do npm são publicadas separadamente do deploy hospedado e podem ficar defasadas, então prefira o servidor hospedado quando seu cliente for compatível. @latest faz o npx buscar a versão mais recente quando o cliente reinicia o servidor; sem isso, o npx pode continuar executando uma cópia antiga em cache.

Aviso de atualização

Na inicialização, um servidor local consulta o registro do npm para verificar a versão mais recente, no máximo uma vez por dia (a resposta fica em cache em ~/.config/sync/mcp-update-check.json). A verificação é executada em segundo plano, com limite de dois segundos, e nunca atrasa a inicialização nem uma chamada de ferramenta; se falhar, nada é exibido. Quando há uma versão mais recente, as instruções do servidor e o primeiro resultado de ferramenta da sessão orientam o agente a pedir que você reinicie com npx -y @sync.so/mcp-server@latest ou mude para o servidor hospedado.

Para desativar, defina SYNC_MCP_UPDATE_CHECK=off ou passe --no-update-check. A verificação também é ignorada quando CI está definido, e o servidor hospedado nunca verifica atualizações.

O que pedir

Cole prompts como estes no seu agente. Os IDs dos recursos vêm da sua biblioteca do sync. Os links podem ser URLs públicas de mídia ou vídeos do YouTube, TikTok, Instagram e Facebook.

Pedido	O que o agente faz
"Sincronize os lábios do vídeo <video-asset-id> com o áudio do recurso <audio-asset-id>."	lipsync_create com os recursos salvos e, em seguida, aguarda o resultado
"Sincronize os lábios de https://example.com/talk.mp4 para https://example.com/voiceover.wav."	lipsync_create com URLs públicas
"Traduza https://www.youtube.com/watch?v=… para espanhol."	Importa o link com assets_create, informa o custo e, após sua confirmação, executa dubbing_create
"Faça o vídeo do recurso <video-asset-id> dizer “obrigado por assistir” com uma voz de narrador calma."	Escolhe uma voz com voices_list, informa o texto e, em seguida, lipsync_create com script
"Quantos créditos ainda tenho?"	account_get-usage
"Quanto custou minha última geração?"	Encontra o valor no histórico e consulta generations_get-costs

Traduções, dublagens, prévias de fala e clones de voz têm o custo informado e são confirmados com você antes de começarem.

Habilidades do agente

Fluxos de trabalho passo a passo para essas ferramentas (sincronização labial, fotos falantes, dublagem, Edit Dialogue, campanhas, lotes, solução de problemas e API) são habilidades de agente em synchronicity-labs/skills. Instale-as em qualquer agente com npx skills add synchronicity-labs/skills. O plugin do ChatGPT e do Codex as inclui a partir de um commit fixado desse repositório; consulte docs/chatgpt-plugin.md.

Ferramentas

O servidor hospedado disponibiliza um conjunto selecionado de ferramentas para todos os clientes:

Área	Ferramentas
Sincronização labial	lipsync_create, lipsync_create-timeline¹, generations_estimate-cost, generations_get, generations_list, generations_get-continuation, generations_get-costs, models_list
Tradução e dublagem	dubbing_create, dubbing_get-options, translation-previews_estimate, translation-previews_create, translation-previews_get
Fala e vozes	speech-previews_create, speech-previews_get-options, speech-previews_get, voices_list, voices_clone
Edit Dialogue	dialogue_get-options, dialogue_upload-source, dialogue-transcriptions_create, dialogue-transcriptions_get, dialogue-previews_create, dialogue-previews_get, dialogue-videos_estimate, dialogue-videos_create
Recursos	assets_create, assets_create-upload-url, assets_get, assets_list, assets_count, assets_get-download-url, assets_update, assets_delete, assets_get-playback-metadata, audio-trims_get, audio-trims_create
Projetos	projects_create, projects_get, projects_list, projects_list-generations, projects_rename
Vários trabalhos	jobs_create-many², jobs_get-many²
Lotes	batches_create², batches_get², batches_list²
Conta	account_get-context, account_get-usage, organizations_list, organizations_select

¹ Não disponível no app do ChatGPT, cujo Studio integrado não tem linha do tempo.

² Ainda não aparece na lista do app do ChatGPT. jobs_create-many inicia até 50 trabalhos independentes de uma só vez, como dublar um vídeo em vários idiomas, executando uma ferramenta de criação (lipsync_create, dubbing_create, dialogue-videos_create e outras) uma vez por item, com a mesma API, os mesmos limites e a mesma cobrança das chamadas individuais em qualquer plano; jobs_get-many acompanha o conjunto. Consulte Trabalhos. Um lote é um pipeline separado da API, com fila, para execuções grandes (20 a 500 gerações) nos planos Scale e superiores, que podem aguardar horas. Quando o plano da conta não inclui lotes, a API responde com 402 e requiredPlan e billingUrl, que as ferramentas repassam.

Organizações com o recurso correspondente também recebem scenes_detect (cortes de câmera em um vídeo) e stems_separate (vocais e áudio de fundo), fora do app do ChatGPT. Eles estão nos conjuntos de ferramentas lipsync e assets localmente.

Clientes com suporte a apps também recebem as ferramentas por trás do app Studio integrado: visualizações e rascunhos do Studio, o widget de upload e auxiliares do app. São clientes cujo nome de handshake MCP seleciona o perfil do app ChatGPT ou Codex (openai-mcp, openai-mcp (Codex); consulte src/client-profile.ts). Outros clientes não veem essas ferramentas, e as chamadas a elas são recusadas.

Conjuntos de ferramentas locais

O servidor stdio local também pode oferecer uma ferramenta para cada outra operação pública da API na especificação OpenAPI, mais de 65 no total. Por padrão, ele lista o conjunto hospedado acima, sem as ferramentas administrativas (assets_delete e voices_clone), além de jobs_get, jobs_wait e das ferramentas transcriptions_*, cujas trilhas faciais dos locutores alimentam os clipes lipsync_create-timeline.

Para listar mais ferramentas, defina SYNC_MCP_TOOLSETS ou passe --toolsets com uma lista separada por vírgulas:

Conjunto de ferramentas	Adiciona
default	O conjunto padrão acima; assim, default,admin adiciona as ferramentas administrativas a ele
lipsync	Ferramentas de sincronização labial, linha do tempo, Edit Dialogue, corte de áudio e lotes, além de generate_*, generations_* e dialogue-edits_* brutos
dubbing	Ferramentas de tradução e dublagem, além das ferramentas de lotes
assets	assets_* (exceto exclusões) e as ferramentas de upload
projects	projects_* (exceto exclusões) e projects_rename
transcription	transcriptions_*
voices	voices_* (exceto clonagem e exclusões), prévias de fala e tts_*
admin	Todas as exclusões (assets_delete, projects_delete, generations_delete, voices_delete) e voices_clone
all	Todas as ferramentas, como antes da existência desta opção

Leituras de trabalhos, conta e gerações (jobs_get, jobs_wait, jobs_get-many, generations_get, account_get-context, organizations_list, organizations_select e similares) acompanham todas as seleções, assim como jobs_create-many sempre que uma ferramenta de criação executada por ele estiver listada. Nomear conjuntos de ferramentas substitui o padrão, em vez de adicioná-los a ele. Para recuperar todas as ferramentas:

claude mcp add sync -e SYNC_API_KEY=your-api-key -e SYNC_MCP_TOOLSETS=all -- npx -y @sync.so/mcp-server@latest

A menos que liste tudo, as instruções do servidor informam ao agente quais conjuntos de ferramentas estão listados e como obter os demais, para que ele possa pedir que você reinicie o servidor com um conjunto mais amplo. O servidor hospedado ignora essa configuração.

Fluxos de trabalho das ferramentas descreve o funcionamento das ferramentas pagas e com várias etapas.

Os nomes das ferramentas seguem um esquema <noun>_<verb> (lipsync_create, generations_get). Os nomes usados antes dele (create-lipsync, generate_get-generation) continuam funcionando durante um período de descontinuação: chamadas feitas por eles executam a mesma ferramenta e exibem um aviso de uma linha com o novo nome. Nomes das ferramentas contém a tabela completa de nomes antigos → novos.

Opções da CLI

Usage: sync-mcp [options]

Options:
  --api-key <key>     API key (or set SYNC_API_KEY env var)
  --base-url <url>    API base URL (default: https://api.sync.so)
  --transport <type>  stdio (default) or http
  --port <port>       HTTP port (default: 3002, only with --transport http)
  --no-spend-confirmation
                      Unattended automation: drop the cost-quote and confirm-before-paying
                      instructions (or set SYNC_MCP_SPEND_CONFIRMATION=off)
  --no-update-check   Skip the daily npm check for a newer version (or set
                      SYNC_MCP_UPDATE_CHECK=off; skipped when CI is set)
  --toolsets <list>   stdio only: comma-separated tools to list (or set SYNC_MCP_TOOLSETS):
                      default, lipsync, dubbing, assets, projects, transcription,
                      voices, admin or all (default: the hosted set without admin)
  -h, --help          Show this help message

Automação sem supervisão

Por padrão, as ferramentas orientam o agente a informar o custo de uma ação paga e aguardar a aprovação do usuário. Quando o servidor executa um pipeline ou um agente agendado cujo operador já aprovou os gastos, inicie-o com --no-spend-confirmation (ou SYNC_MCP_SPEND_CONFIRMATION=off). Assim, o agente cria trabalhos sem informar o custo nem pedir aprovação, e as ferramentas de estimativa continuam disponíveis. Os agentes não podem alterar essa configuração.

As ferramentas de trabalhos aceitam wait: true para aguardar no servidor (até cerca de 50 segundos por chamada, com notificações de progresso quando o cliente envia um progressToken): generations_get, translation-previews_get, transcriptions_get e importações de redes sociais por meio de assets_create. No servidor local, jobs_wait e jobs_get fazem o mesmo para todos os tipos de trabalho (geração, transcrição, análise de locutores, prévia de tradução, importação) com uma entrada, {kind, id, projectId?}, e um único formato de resultado e conjunto de status; consulte Trabalhos. jobs_get-many lê até 50 trabalhos dessa forma de uma só vez, em ambos os servidores.

Quando a API oferece esse recurso, feedback_send permite que os agentes relatem erros confusos, resultados incorretos e recursos ausentes à equipe do Sync.

As variáveis de ambiente e os limites de sessão, memória, upload e diagnóstico do servidor HTTP estão em Configuração do servidor HTTP.

Como funciona

1. Na inicialização, o servidor busca a especificação OpenAPI pública em {baseUrl}/api-json e transforma cada operação em uma ferramenta MCP com um esquema de entrada Zod.
2. Ferramentas escritas manualmente adicionam fluxos de trabalho com várias etapas na mesma API, como tradução e dublagem, Edit Dialogue, prévias de fala e consultas de custos.
3. Cada chamada de ferramenta é uma solicitação autenticada à API do sync., com seu token OAuth (hospedado) ou chave de API (local).

Por stdio, uma nova operação da API pública se torna uma ferramenta na próxima reinicialização. O servidor hospedado só expõe as ferramentas da lista de permissões, então uma nova ferramenta hospedada é lançada com uma versão deste repositório.

Uso programático

Você também pode usar o servidor como uma biblioteca:

import { createSyncMcpServer, resolveConfig } from '@sync.so/mcp-server';

const config = resolveConfig({ apiKey: 'your-key' });
const server = await createSyncMcpServer(config);

Desenvolvimento

Os testes de origem HTTPS usam o comando local openssl para criar uma identidade de teste autoassinada, válida por um dia. Os arquivos temporários de certificado e chave são removidos antes da execução dos testes.

# Install dependencies
pnpm install

# Build
pnpm run build

# Run tests
pnpm test

# Lint
pnpm run lint

# Type check
pnpm run typecheck

# Script tests (monitor, smoke check, pre-commit size check)
pnpm run test:scripts

O desenvolvimento requer Node 26 ou mais recente (.nvmrc); devEngines em package.json impõe esse requisito durante a instalação. pnpm install instala um hook de pre-commit. Ele executa Oxlint e Oxfmt nos arquivos preparados e bloqueia arquivos de origem preparados que ultrapassem 5.000 tokens (20.000 bytes). Arquivos que já excedem esse tamanho ficam isentos até que alguém os divida.

Teste do transporte HTTP local

Para testar o transporte HTTP (fluxo OAuth) localmente:

1. Copie .env.example para .env e preencha os valores
2. Inicie um túnel para expor o localhost:

   ngrok http 3002
   

3. Atualize MCP_ISSUER_URL em .env com a URL do ngrok
4. Inicie o servidor:

   source .env
   node dist/cli.js --transport http --base-url $SYNC_BASE_URL --port 3002
   

5. Verifique se funciona:

   curl https://<ngrok-url>/health
   curl https://<ngrok-url>/.well-known/oauth-authorization-server
   

Quando um login isolado do Studio exigir o proxy web de mesma origem, defina SYNC_OAUTH_AUTHORIZATION_URL como a URL /api-proxy/v2/oauth/authorize, mantendo SYNC_BASE_URL no listener direto da API isolada. Somente a navegação do browser usa o proxy web. O registro, a troca de código, a renovação, a revogação, o userinfo e as chamadas de ferramentas usam a API direta e mantêm os prazos, o PKCE e as verificações de cliente confidencial existentes. A URL opcional deve usar HTTP(S), sem credenciais, consulta ou fragmento. Implantações existentes não precisam de uma nova configuração.

6. Adicione https://<ngrok-url>/mcp como um conector personalizado no Claude Web

Saiba mais

• Fluxos de trabalho das ferramentas — Como as ferramentas de várias etapas e pagas se comportam
• Configuração do servidor HTTP — Variáveis de ambiente e limites de execução
• Notas para mantenedores — Compatibilidade com hospedagem, cancelamento, proxy OAuth, uploads e monitoramento
• Preparação para o diretório do Claude — Lista de verificação e trabalho restante para o envio
• Documentação do Sync — Referência completa da API e guias
• Referência da API do Sync — Documentação dos endpoints
• Protocolo MCP — Saiba mais sobre o Model Context Protocol
• Site do Sync — Cadastre-se e comece

Licença

MIT