Plugins & Extensions

Sync MCP Server — Use Sync from Claude, ChatGPT & AI Assistants via MCP

What Is the Sync MCP Server?

The Sync MCP server is an open-source Model Context Protocol server that connects AI assistants — including Claude Desktop, Cursor, and Windsurf — to the Sync lipsync API. Instead of writing code or using the Studio, describe what you want in plain English and your AI assistant handles the API calls for you.

The Sync MCP server auto-generates tools from the Sync API spec at startup. As new API endpoints ship, they become available to your AI assistant automatically — no update needed.

Which AI Clients Support the Sync MCP Server?

The Sync MCP server supports these AI clients, with more being added as the MCP ecosystem grows:

ClientStatus
Claude DesktopSupported
ChatGPT DesktopNot yet supported
Claude CodeSupported
CursorSupported
WindsurfSupported
Codex CLISupported
Claude Web (claude.ai)Coming soon
Any MCP-compatible clientSupported

How Do I Set Up the Sync MCP Server?

Setting up the Sync MCP server takes under 2 minutes. You need:

Choose your AI client below and follow the instructions to get started.

Add the following to your claude_desktop_config.json:

1{
2  "mcpServers": {
3    "sync": {
4      "command": "npx",
5      "args": ["-y", "@sync.so/mcp-server"],
6      "env": {
7        "SYNC_API_KEY": "your-api-key"
8      }
9    }
10  }
11}

Where to find this file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after saving.

ChatGPT Desktop does not yet support MCP servers. Once OpenAI enables MCP support, we’ll update this section with setup instructions.

Run this one-liner to add Sync to Claude Code:

$claude mcp add sync -- npx -y @sync.so/mcp-server --api-key YOUR_API_KEY

Or add to .mcp.json in your project root:

1{
2  "mcpServers": {
3    "sync": {
4      "command": "npx",
5      "args": ["-y", "@sync.so/mcp-server"],
6      "env": {
7        "SYNC_API_KEY": "your-api-key"
8      }
9    }
10  }
11}

Add to .cursor/mcp.json in your project:

1{
2  "mcpServers": {
3    "sync": {
4      "command": "npx",
5      "args": ["-y", "@sync.so/mcp-server"],
6      "env": {
7        "SYNC_API_KEY": "your-api-key"
8      }
9    }
10  }
11}

Any MCP-compatible client can use the Sync MCP server. The configuration is the same — point it at npx -y @sync.so/mcp-server with your API key set as SYNC_API_KEY in the environment.

See the MCP protocol docs for client-specific setup instructions.

Interactive Login (No API Key)

If you prefer not to set an API key in your config, omit SYNC_API_KEY and the Sync MCP server will start a device auth flow on first run:

1{
2  "mcpServers": {
3    "sync": {
4      "command": "npx",
5      "args": ["-y", "@sync.so/mcp-server"]
6    }
7  }
8}

You’ll be prompted to visit a URL and enter a code. After approval, the token is cached at ~/.config/sync/mcp-credentials.json.

What Can I Do with the Sync MCP Server?

Once connected, you can create lipsync videos, check generation status, estimate costs, and manage assets — all through natural language. Here are example prompts you can try with your AI assistant:

  • “Create a lipsync video with this video URL and audio URL”
  • “Check the status of generation gen-abc123”
  • “List available Sync models”
  • “Show me my recent generations”
  • “How much would it cost to generate a 30-second video?”
  • “Get the details of my latest completed generation and give me the output URL”
  • “Estimate the cost for a 45-second lipsync video, then create it if it’s under $1”

The Sync MCP server exposes all public Sync API endpoints as tools. Core tools include:

ToolDescription
generate_create-generationCreate a lipsync video from video + audio URL inputs
generate_get-generationGet generation status — poll until COMPLETED
models_get-publicList available lipsync models
assets_get-allList all assets in your organization
generations_estimateEstimate generation cost before creating

The Sync MCP server works with any model available through the API. Asset uploads are not yet available via the API — use publicly accessible URLs for video and audio inputs.

Sync MCP Server vs SDK vs REST API

The Sync MCP server is one of three ways to integrate with the Sync API. Choose the approach that best fits your workflow:

ApproachBest ForSetup TimeCode Required
Sync MCP ServerAI assistant workflows, prototyping, natural language controlUnder 2 minNone
Python/TypeScript SDKApplication integration, production pipelines~5 minYes
REST APICustom implementations, full control~10 minYes

The Sync MCP server is ideal when you want to explore the API, prototype workflows, or create lipsync videos without writing code. For production applications, the Sync SDKs or REST API give you full programmatic control.

CLI Options

The Sync MCP server accepts the following options when run directly:

OptionDescriptionDefault
--api-key <key>API key (or set SYNC_API_KEY env var)—
--base-url <url>API base URLhttps://api.sync.so
--transport <type>stdio or httpstdio
--port <port>HTTP port (only with --transport http)3002

Programmatic Usage

You can also use the Sync MCP server as a library in your own applications. This is useful when you want to embed Sync’s MCP tools into a custom AI agent or multi-tool pipeline:

1import { createSyncMcpServer, resolveConfig } from '@sync.so/mcp-server';
2
3const config = resolveConfig({ apiKey: 'your-key' });
4const server = await createSyncMcpServer(config);

The Sync MCP server exposes the same auto-generated tools when used programmatically, so your custom agents get access to every public Sync API endpoint.

Troubleshooting

  • Make sure you have Node.js 18+ installed
  • Verify your API key is valid at sync.so/settings/api-keys
  • Restart your AI client after updating the configuration
  • Check the terminal/logs for error messages
  • Double-check your API key is correct and has not been revoked
  • If using interactive login, try deleting ~/.config/sync/mcp-credentials.json and re-authenticating
  • Ensure your Sync account is active with a valid payment method

If you see sh: mcp-server: command not found or similar errors when using the npx configuration, this is typically caused by Node version managers (nvm, fnm, volta) not resolving npx bin paths correctly.

Fix: Install the package globally and reference it directly:

$npm install -g @sync.so/mcp-server

Then update your MCP config to use sync-mcp instead of npx:

1{
2  "mcpServers": {
3    "sync": {
4      "command": "sync-mcp",
5      "args": [],
6      "env": {
7        "SYNC_API_KEY": "your-api-key"
8      }
9    }
10  }
11}

If that still doesn’t work, use the full path to node:

1{
2  "mcpServers": {
3    "sync": {
4      "command": "node",
5      "args": ["node_modules/@sync.so/mcp-server/dist/cli.js"],
6      "env": {
7        "SYNC_API_KEY": "your-api-key"
8      }
9    }
10  }
11}

Frequently Asked Questions

No. The Sync MCP server runs via npx, which downloads the package automatically. Node.js 18+ is the only prerequisite. You can also install it globally with npm install -g @sync.so/mcp-server if you prefer.

Yes. The Sync MCP server fetches the latest OpenAPI spec from the Sync API on every startup. When new endpoints are added to the Sync API, they become available as MCP tools automatically — just restart the server.

Yes. If you omit the SYNC_API_KEY environment variable, the Sync MCP server starts an interactive device auth flow. You’ll be prompted to visit a URL and enter a code to authenticate with your Sync account.

The Sync MCP server supports 8 AI clients: Claude Desktop, ChatGPT Desktop, Claude Code, Cursor, Windsurf, Codex CLI, Claude Web (coming soon), and any MCP-compatible client. See the supported clients table for details.

Asset uploads are not yet available through the Sync API, so they are not available through the Sync MCP server either. Use publicly accessible URLs for your video and audio inputs. Once uploads are added to the Sync API, they will automatically become available through the Sync MCP server.