sync. labs

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

sync. MCP server

Connect your AI agent to sync. to lip-sync videos, translate and dub them into other languages, clone voices, and manage assets and projects from a chat or a coding session.

sync. hosts this server at https://mcp.sync.so/mcp. You sign in with your sync. account, so there is nothing to install and no API key to copy. Every merge to this repository's main deploys there.

Connect your agent

ChatGPT

Open sync. in ChatGPT and connect your account. In ChatGPT, sync. Studio also opens inside the chat.

Claude (claude.ai and Claude Desktop)

1. Open Settings → Connectors and choose Add custom connector.
2. Name it sync. and set the URL to https://mcp.sync.so/mcp.
3. Click Connect and sign in to sync.

Claude Code

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

Then run /mcp in Claude Code, select sync and sign in. Add --scope user to use it in every project.

Codex

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

Cursor

Add to .cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects:

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

Cursor asks you to sign in to sync. the first time it connects.

VS Code

Add to .vscode/mcp.json:

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

Other clients

Any client that supports remote MCP servers over Streamable HTTP with OAuth can use https://mcp.sync.so/mcp. The client registers itself, and you sign in to sync. in the browser.

The server is listed in the official MCP Registry as io.github.synchronicity-labs/mcp-server, so clients and directories that read the registry can find and add it. server.json is that listing.

Local server with an API key

For clients without remote MCP support, and for scripts and CI, run the server locally over stdio with a sync. API key:

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

Or in a client's JSON config:

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

Without SYNC_API_KEY, the server starts a device login on first run: visit the URL it prints and enter the code. The token is cached at ~/.config/sync/mcp-credentials.json.

npm releases are published separately from the hosted deploy and can lag behind it, so prefer the hosted server when your client supports it. @latest makes npx fetch the newest release when the client restarts the server; without it, npx can keep running an old cached copy.

Update notice

At startup a local server asks the npm registry for the latest version, at most once a day (the answer is cached in ~/.config/sync/mcp-update-check.json). The check runs in the background with a two-second limit and never delays startup or a tool call; if it fails, nothing is shown. When a newer version exists, the server's instructions and the first tool result of the session tell the agent to ask you to restart with npx -y @sync.so/mcp-server@latest or switch to the hosted server.

To turn it off, set SYNC_MCP_UPDATE_CHECK=off or pass --no-update-check. It is also skipped when CI is set, and the hosted server never checks.

What to ask

Paste prompts like these into your agent. Asset IDs come from your sync. library. Links can be public media URLs or YouTube, TikTok, Instagram and Facebook videos.

Ask	What the agent does
"Lipsync video asset <video-asset-id> with audio asset <audio-asset-id>."	lipsync_create with the saved assets, then waits for the result
"Lipsync https://example.com/talk.mp4 to https://example.com/voiceover.wav."	lipsync_create with public URLs
"Translate https://www.youtube.com/watch?v=… to Spanish."	Imports the link with assets_create, quotes the cost, and after you confirm runs dubbing_create
"Make video asset <video-asset-id> say “thanks for watching” in a calm narrator voice."	Picks a voice with voices_list, quotes the script, then lipsync_create with script
"How many credits do I have left?"	account_get-usage
"What did my last generation cost?"	Finds it in history and reads generations_get-costs

Translation, dubbing, speech previews and voice clones are quoted and confirmed with you before they start.

Agent skills

Step-by-step workflows for these tools (lipsync, talking photos, dubbing, Edit Dialogue, campaigns, batches, troubleshooting and the API) are agent skills in synchronicity-labs/skills. Install them in any agent with npx skills add synchronicity-labs/skills. The ChatGPT and Codex plugin ships them from a pinned commit of that repository; see docs/chatgpt-plugin.md.

Tools

The hosted server exposes a curated set of tools to every client:

Area	Tools
Lip sync	lipsync_create, lipsync_create-timeline¹, generations_estimate-cost, generations_get, generations_list, generations_get-continuation, generations_get-costs, models_list
Translation and dubbing	dubbing_create, dubbing_get-options, translation-previews_estimate, translation-previews_create, translation-previews_get
Speech and voices	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
Assets	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
Projects	projects_create, projects_get, projects_list, projects_list-generations, projects_rename
Batches	batches_create², batches_get², batches_list²
Account	account_get-context, account_get-usage, organizations_list, organizations_select

¹ Not offered to the ChatGPT app, whose embedded Studio has no timeline.

² Not in the ChatGPT app listing yet. A batch runs 20 or more independent generations (500 per batch by default), such as one campaign video localized into many languages. Where the account's plan doesn't include batch, the API answers 402 with requiredPlan and billingUrl, which the tools pass on.

Organizations with the matching feature also get scenes_detect (camera cuts in a video) and stems_separate (vocals and background audio), outside the ChatGPT app. They are in the lipsync and assets toolsets locally.

Clients with app support also get the tools behind the embedded Studio app: Studio views and drafts, the upload widget and app helpers. Those are clients whose MCP handshake name selects the ChatGPT or Codex app profile (openai-mcp, openai-mcp (Codex); see src/client-profile.ts). Other clients don't see these tools, and their calls to them are refused.

Local toolsets

The local stdio server can also offer a tool for every other public API operation in the OpenAPI spec, 65+ in all. By default it lists the hosted set above, without its admin tools (assets_delete and voices_clone), plus jobs_get and jobs_wait and the transcriptions_* tools, whose speaker face tracks feed lipsync_create-timeline clips.

To list more, set SYNC_MCP_TOOLSETS or pass --toolsets with a comma-separated list:

Toolset	Adds
default	The default above, so default,admin adds the admin tools to it
lipsync	Lip sync, timeline, Edit Dialogue, audio trim and batch tools, plus raw generate_*, generations_* and dialogue-edits_*
dubbing	Translation and dubbing tools, and the batch tools
assets	assets_* (except deletes) and the upload tools
projects	projects_* (except deletes) and projects_rename
transcription	transcriptions_*
voices	voices_* (except cloning and deletes), speech previews and tts_*
admin	Every delete (assets_delete, projects_delete, generations_delete, voices_delete) and voices_clone
all	Every tool, as before this option existed

Job, account and generation reads (jobs_get, jobs_wait, generations_get, account_get-context, organizations_list, organizations_select and similar) come with every selection. Naming toolsets replaces the default rather than adding to it. To get every tool back:

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

Unless it lists everything, the server's instructions tell the agent which toolsets are listed and how to get the rest, so it can ask you to restart the server with a wider set. The hosted server ignores this setting.

Tool workflows describes how the multi-step and paid tools behave.

Tool names follow one <noun>_<verb> scheme (lipsync_create, generations_get). The names used before it (create-lipsync, generate_get-generation) still work for a deprecation period: calls through them run the same tool and add a one-line notice naming the new one. Tool names has the full old → new table.

CLI Options

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

Unattended automation

By default the tools tell the agent to quote a paid action and wait for the user's approval. When the server runs a pipeline or a scheduled agent whose operator has already approved spending, start it with --no-spend-confirmation (or SYNC_MCP_SPEND_CONFIRMATION=off). The agent then creates jobs without quoting or asking, and estimate tools stay available. Agents cannot change this setting.

Job tools take wait: true to wait on the server (up to about 50 seconds per call, with progress notifications when the client sends a progressToken): generations_get, translation-previews_get, transcriptions_get and social imports through assets_create. On the local server, jobs_wait and jobs_get do the same for every kind of job (generation, transcription, speaker analysis, translation preview, import) with one input, {kind, id, projectId?}, and one result shape and status set; see Jobs.

When the API offers it, feedback_send lets agents report confusing errors, wrong results and missing capabilities to the Sync team.

Environment variables and the HTTP server's session, memory, upload and diagnostics limits are in HTTP server configuration.

How It Works

1. At startup, the server fetches the public OpenAPI spec from {baseUrl}/api-json and turns each operation into an MCP tool with a Zod input schema.
2. Hand-written tools add multi-step workflows on the same API, such as translate and dub, Edit Dialogue, speech previews and cost lookups.
3. Each tool call is an authenticated request to the sync. API, with your OAuth token (hosted) or API key (local).

Over stdio, a new public API operation becomes a tool on the next restart. The hosted server only exposes tools on its allowlist, so a new hosted tool ships with a release of this repository.

Programmatic Usage

You can also use the server as a library:

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

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

Development

HTTPS source tests use the local openssl command to create a one-day, self-signed test identity. Temporary certificate and key files are removed before the tests run.

# 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

Development needs Node 26 or newer (.nvmrc); devEngines in package.json enforces it on install. pnpm install installs a pre-commit hook. It runs Oxlint and Oxfmt on staged files, and blocks a staged source file that grows past 5,000 tokens (20,000 bytes). Files already over that size are exempt until someone splits them.

Local HTTP Transport Testing

To test the HTTP transport (OAuth flow) locally:

1. Copy .env.example to .env and fill in the values
2. Start a tunnel to expose localhost:

   ngrok http 3002
   

3. Update MCP_ISSUER_URL in .env with the ngrok URL
4. Start the server:

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

5. Verify it works:

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

When an isolated Studio login requires the same-origin web proxy, set SYNC_OAUTH_AUTHORIZATION_URL to its /api-proxy/v2/oauth/authorize URL, while keeping SYNC_BASE_URL on the direct isolated API listener. Only browser navigation uses the web proxy. Registration, code exchange, refresh, revocation, userinfo and tool calls use the direct API and retain existing deadlines, PKCE and confidential-client checks. The optional URL must use HTTP(S), with no credentials, query or fragment. Existing deployments need no new setting.

6. Add https://<ngrok-url>/mcp as a custom connector in Claude Web

Learn More

• Tool workflows — How multi-step and paid tools behave
• HTTP server configuration — Environment variables and runtime limits
• Maintainer notes — Hosted compatibility, cancellation, OAuth proxy, uploads and monitoring
• Claude directory readiness — Review checklist and remaining submission work
• Sync Documentation — Full API reference and guides
• Sync API Reference — Endpoint documentation
• MCP Protocol — Learn about the Model Context Protocol
• Sync Website — Sign up and get started

License

MIT