Connect your Agent with MCP

Choose your connection method

FreeLipSync exposes a remote MCP endpoint at https://freelipsync.com/mcp. It gives an agent the same video generation capabilities and account credits as the REST API. You must have a registered FreeLipSync account; anonymous access is not supported. Use your staging origin instead when testing on staging.

Both API Key configuration and OAuth are supported. Choose one credential source per server entry. An existing configuration file remains a valid way to connect; you do not have to use OAuth.

Create a key once and copy it from the creation dialog. OAuth does not require copying a key. The account supports up to 5 API Keys and 5 independent OAuth authorization connections. API Key access uses a key slot, not an OAuth connection slot. Both methods share the account's balance, models and limits.

OAuth authorization flow

1. Add the remote HTTPS URL in your client, without an Authorization header or API Key setting.
2. Choose Connect / Authenticate / Sign in, as appropriate for the client.
3. In the browser, sign into your FreeLipSync account and review the requesting client and permissions.
4. Create a new connection (default), or explicitly choose an existing connection to replace. A successful authorization on another device normally counts separately.
5. Allow the agent to spend your purchased API credits, then authorize. Return to the client and verify the tools below.

You can deny the request. If all 5 connection slots are used, explicitly replace or revoke an old connection in Agent console; new authorization does not silently evict a connection. Token refresh and reconnecting an existing authorization do not add a slot. An OAuth connection can spend your account's credits when generation is submitted.

Client OAuth compatibility matters: FreeLipSync supports published client identity metadata (CIMD) and pre-registered clients, rather than an open dynamic-registration endpoint. Use a compatible client version or an assigned client ID where supported. If a client only supports dynamic registration and sign-in fails, use the API Key method or contact support to check client registration.

Client compatibility and OAuth differences

OAuth registration and token authentication are separate. FreeLipSync supports CIMD or a pre-registered client ID, with none + PKCE or private_key_jwt. It understands the newer CIMD array of supported methods as well as the older single-method field. Signed clients use their published public keys automatically; users do not upload a private key.

FreeLipSync does not offer open dynamic registration (DCR), client-secret authentication, or the client_credentials grant. If a client requires DCR, use its pre-registered public-client option where available, or use API Key configuration in a client that supports custom Bearer headers. Obtain an assigned ID and register the actual callback before configuring it. An API Key and an OAuth client ID are different credentials.

Codex: config file or OAuth

Add or edit a remote HTTP server under Plugins → MCPs in Codex; some versions use Settings → MCP servers. This local MCP entry supports API Key configuration and is separate from the hosted-plugin OAuth entry described above.

Choose one credential source. The examples use https://freelipsync.com/mcp. For staging, replace it with https://staging.freelipsync.com/mcp and create the key in your staging account. Production and staging keys are not interchangeable.

Option A: paste an API Key in the desktop settings

Use this option when you do not want to configure environment variables. Create a key in Agent console, copy the complete secret, then fill in:

Use one space after Bearer; the key itself has no Bearer prefix. Do not name the header FLS_API_KEY or paste the secret into Bearer token env var. Save and reconnect; if the client still uses an old configuration, restart it or open a new session.

The equivalent personal ~/.codex/config.toml entry is:

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

Option B: supply the API Key through an environment variable

Bearer token env var takes a variable name, not a secret. Set it to FLS_API_KEY. That variable must exist in the environment of the process running Codex. Its value is the complete key without Bearer ; Codex adds the prefix.

The corresponding personal configuration file is:

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

For Codex CLI launched from a terminal:

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

Exporting a variable in another terminal does not update an already running desktop app. An app launched from the Dock or Start menu may not inherit terminal variables either. If you are unsure how to provide the desktop process environment, use option A.

Headers creates HTTP request headers. Headers from environment variables reads header values from existing environment variables. Neither field creates a system environment variable. A header named FLS_API_KEY does not populate the Bearer setting, and a gray placeholder such as MCP_BEARER_TOKEN does not mean that variable has been configured.

Option C: authorize in the browser with OAuth

Enter only the URL. Leave Bearer token env var, Headers and Headers from environment variables empty, including removing any previous Authorization row. Save, choose Authenticate / Sign in where offered, sign into FreeLipSync and approve the connection. No API Key needs to be created or pasted.

For a configuration file, keep only:

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

CLI commands:

# 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

Replace freelipsync in the commands with your saved server name. The three TOML blocks above are alternatives; keep one entry for the server. Remove keyed configuration before switching to OAuth: logging in does not repair an incorrect Authorization header that is still configured.

Check the connection after saving

In a new session, ask: “Call FreeLipSync get_capabilities and get_usage to check my models and credits. Do not generate a video.” A successful account response confirms the connection; a server name appearing in the list alone does not.

For HTTP 401, check that the URL and key belong to the same environment, the key is complete, the static header is Authorization: Bearer YOUR_API_KEY, and no old Bearer-variable or duplicate Authorization setting remains. With option B, also check the environment of the process that actually launches the client.

See the official OpenAI MCP guide and configuration reference for field definitions.

Claude Code: config file or OAuth

For API Key access, put this entry in a personal/local MCP configuration or merge it into .mcp.json for the project. The environment variable is expanded by Claude Code. Keep the actual key out of shared configuration and start Claude Code with the variable set.

{
  "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

For OAuth, remove the keyed entry or its Authorization header first, add a URL-only HTTP server, and authenticate via /mcp in an interactive Claude Code session:

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

Use one method at a time. A configured invalid Bearer header will not be fixed by signing in through a different flow. See Claude Code's official MCP guide.

Claude Desktop and Claude web

For OAuth, open Claude's Connectors management page, add a custom web/remote connector named FreeLipSync, and enter https://freelipsync.com/mcp. Choose sign-in and use Claude's published client identity where available; complete the FreeLipSync authorization page. An organization may require its owner to enable the connector first. Remote connectors must reach a public HTTPS endpoint; localhost is not reachable from Claude's cloud. See Claude's remote connector guide.

For the older Claude Desktop configuration-file route, a stdio-only client needs a local bridge to the remote endpoint; pasting a remote url into a stdio configuration is not sufficient. With Node.js / npx installed, merge this entry into claude_desktop_config.json (open it from Desktop's developer settings) and restart Desktop. Replace the placeholder locally and keep this personal file private.

{
  "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 is a third-party compatibility bridge, not a FreeLipSync package. Review its maintainer's instructions and your installed version. Its header argument supports environment expansion; the format above also avoids spaces inside the argument. Prefer a client's native HTTP support when available. This Desktop file is not the configuration mechanism for Claude web.

Cursor: config file or OAuth

For API Key access, use your personal ~/.cursor/mcp.json (or a project .cursor/mcp.json kept out of source control when it contains a key). Replace the placeholder locally. Do not assume that environment expansion from another client's format works in your installed Cursor version.

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

For OAuth, use the same entry with only url, removing the headers object. In Cursor's MCP settings, connect/authenticate and complete the browser authorization if offered. Reload or restart the client after changing its configuration, then verify the tools in Agent mode. If that version's registration flow is incompatible, use the Key configuration above. See Cursor's official MCP instructions.

VS Code and GitHub Copilot

For a native VS Code MCP configuration, create .vscode/mcp.json with a password input rather than a real key in the file:

{
  "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}"}
    }
  }
}

For OAuth, remove inputs and headers, retaining the server's type and URL. Start/connect the server and follow the authentication prompt; client registration must be compatible as described above. Select its tools in Copilot's Agent mode and try the verification prompt below. The VS Code format uses servers, not another client's mcpServers; interactive inputs are not supported by every Copilot harness or portable configuration. See the VS Code MCP reference.

Verify tools and try a prompt

First ask your agent: “Use FreeLipSync to check my available models and credit balance. Do not create a video yet.” It should call get_capabilities and get_usage, without spending credits. A server listed in a config file is not sufficient evidence that authentication worked.

Then try: “Make a short Image Fast talking photo from my image and audio. Get a quote first and tell me the credits. Wait for my confirmation before submitting. If you cannot upload my local files, give me browser upload links.” Keep the client's approval for spending tools enabled.

Uploading local files from an agent

There are two local-file paths, plus HTTPS import. Do not pass a local path as an import_asset URL.

• A client that can read files and send HTTP PUT calls create_asset_upload with kind, filename, content_type, size_bytes, idempotency_key; it uploads the actual bytes to the returned URL using its headers, then calls confirm_asset_upload. Never forward your API Key to signed storage URLs.
• A client without local file/HTTP access calls create_asset_upload_session for each image/video/audio. You open browser_upload_url, sign into the same FreeLipSync account and upload in the browser. The agent retains asset_id and polls get_asset; you do not have to copy the ID back. Do not share the upload ticket publicly.
• For an existing public HTTPS file, import_asset with kind, url, idempotency_key starts import. Wait until ready before quoting.

A URL-only/cloud connector does not gain access to your desktop files simply by using MCP. For example, Claude's remote connectors run from its cloud, so use browser upload links when the client cannot transfer your attachment to the signed URL.

Credits, retries and connection management

API and MCP use the same rates: Video Lip Sync / Image Fast 1 credit/sec; Image Max 2; Image Super / Music Video 3. The verified audio duration rounds up to seconds, minimum 5 seconds. estimate_generation returns total_points and a quote ID; create_generation takes that quote_id plus idempotency_key. Uploading, checking usage and estimating do not spend credits. Accepted generation cannot be cancelled; only processing failure returns the original hold. See API billing and recovery.

Keep the same quote and idempotency key after an uncertain submission. Save the returned job ID and query it; do not ask the agent to “try again” by making another task. Poll using poll_after_seconds, back off on Retry-After, and use list_generations to query several active jobs together. API and MCP share the account read bucket, while all three website/API/MCP entry points share submission frequency and video execution capacity. The website and API/MCP have separate unfinished-task allowances: Free 1, Starter 3, Pro 10 in each pool. All REST/MCP credentials share the API/MCP pool. See why use API/MCP for examples.

Revoke a Key or OAuth connection from the Agent console. Revoking a key stops future use of it in every client that shares it, including REST; revoking an OAuth connection affects only that connection. Neither operation cancels already accepted tasks. Deleting a local client entry alone does not revoke a credential on FreeLipSync. Use separate keys or independent authorizations when you need separate revocation, not to increase concurrency.

Troubleshooting

Client settings may change between versions. Refer to each client's linked official documentation for the current instructions. Need direct HTTP integration? Read the API documentation.