Sync MCP Server

An open-source Model Context Protocol (MCP) server for the Sync API. Gives AI agents the ability to create lipsync videos, manage assets, check generation status, and more.

Tools are auto-generated from the Sync OpenAPI spec at startup. As new API endpoints ship, they become available to agents automatically — no server update needed.

Supported Clients

Client	Status	Transport
Claude Web (claude.ai)	Supported	Remote (HTTP + OAuth)
Claude Desktop	Supported	Local (stdio)
ChatGPT Desktop	Supported	Local (stdio)
Claude Code	Supported	Local (stdio)
Cursor	Supported	Local (stdio)
Windsurf	Supported	Local (stdio)
Codex CLI	Supported	Local (stdio)
Any MCP-compatible client	Supported	Local (stdio)

Quick Start

Claude Web (claude.ai)

No installation required — connect directly from your browser.

1. Go to claude.ai → Settings → Integrations
2. Click Add custom connector
3. Enter Name: Sync and URL: https://mcp.sync.so/mcp
4. Click Add, then Connect
5. Log in with your Sync account when prompted

No API key needed — authentication is handled via OAuth.

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:

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

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor

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

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

Without an API key (interactive login)

Omit SYNC_API_KEY and the server will start a device auth flow on first run:

{
  "mcpServers": {
    "sync": {
      "command": "npx",
      "args": ["-y", "@sync.so/mcp-server"]
    }
  }
}

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

Getting an API Key

1. Sign up at sync.so
2. Go to your dashboard settings
3. Generate an API key

See the authentication guide for details.

Available Tools

Tools are dynamically generated from the Sync API. Core tools include:

Tool	Description
generate_create-generation	Create a lipsync video from video + audio inputs
generate_get-generation	Get generation status — poll until COMPLETED
generate_get-generations	List recent generations
models_get	List available lipsync models
assets_get-all	List all assets in your organization
assets_get	Get a specific asset by ID
generations_estimate-cost	Estimate generation cost before creating
generations_get-by-id	Get a generation by ID

Example Prompts

Once configured, ask your AI agent:

• "List available Sync models"
• "Create a lipsync video with this video URL and audio URL using the lipsync-2 model"
• "Check the status of generation gen-abc123"
• "Show me my recent generations"
• "How much would it cost to generate a 30-second video?"

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)
  -h, --help          Show this help message

Environment Variables

Variable	Description	Default
SYNC_API_KEY	Your Sync API key (stdio transport)	—
SYNC_BASE_URL	API base URL	https://api.sync.so
MCP_ISSUER_URL	OAuth issuer URL (HTTP transport only)	—
OAUTH_REGISTRATION_SECRET	Shared secret for client registration (HTTP transport only)	—

How It Works

1. On startup, the server fetches the OpenAPI spec from {baseUrl}/api-json
2. Parses all public endpoints into operation definitions
3. Converts each operation into an MCP tool with a Zod input schema
4. Registers tools on the MCP server
5. Each tool call makes an authenticated HTTP request to the Sync API

This means new API endpoints are automatically available — just restart the MCP server.

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

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Type check
npm run typecheck

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
   

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

Learn More

• 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