Connecter votre Agent avec MCP

Choisissez votre méthode de connexion

FreeLipSync expose un point de terminaison MCP distant sur https://freelipsync.com/mcp. Il offre à un agent les mêmes capacités de génération vidéo et les mêmes crédits de compte que le REST API. Vous devez avoir un compte FreeLipSync enregistré ; l'accès anonyme n'est pas pris en charge. Utilisez plutôt votre origine staging lors des tests sur staging.

Les configurations API Key et OAuth sont prises en charge. Choisissez une source d'informations d'identification par entrée de serveur. Un fichier de configuration existant reste un moyen valable de se connecter ; vous n'êtes pas obligé d'utiliser OAuth.

Créez une clé et copiez sa valeur complète depuis la fenêtre de création. OAuth ne nécessite aucune copie de clé. Chaque compte accepte jusqu’à 5 API Keys et 5 connexions OAuth indépendantes. Un accès par API Key utilise un emplacement de clé, pas un emplacement de connexion OAuth. Les deux méthodes partagent le solde, les modèles et les limites du compte.

Flux d'autorisation OAuth

1. Ajoutez le HTTPS URL distant dans votre client, sans en-tête Authorization ni paramètre API Key.
2. Choisissez Connect / Authenticate / Sign in, selon le client.
3. Dans le navigateur, connectez-vous à votre compte FreeLipSync et vérifiez le client demandeur et les autorisations.
4. Créez une nouvelle connexion (par défaut) ou choisissez explicitement une connexion existante à remplacer. Une autorisation réussie sur un autre appareil compte normalement séparément.
5. Autorisez l'agent à dépenser vos crédits API achetés, puis autorisez-le. Revenez au client et vérifiez les outils ci-dessous.

Vous pouvez refuser la demande. Si tous les emplacements de connexion 5 sont utilisés, remplacez ou révoquez explicitement une ancienne connexion dans Console Agent ; une nouvelle autorisation n’élimine pas silencieusement une connexion. L'actualisation du jeton et la reconnexion d'une autorisation existante n'ajoutent pas d'emplacement. Une connexion OAuth peut dépenser les crédits de votre compte lorsque la génération est soumise.

La compatibilité du client OAuth est importante : FreeLipSync prend en charge les métadonnées d'identité du client publiées (CIMD) et les clients préenregistrés, plutôt qu'un point de terminaison d'enregistrement dynamique ouvert. Utilisez une version client compatible ou un ID client attribué lorsque cela est pris en charge. Si un client prend uniquement en charge l'enregistrement dynamique et que la connexion échoue, utilisez la méthode API Key ou contactez l'assistance pour vérifier l'enregistrement du client.

Compatibilité client et différences OAuth

L'enregistrement OAuth et l'authentification par jeton sont distincts. FreeLipSync prend en charge CIMD ou un ID client préenregistré, avec none + PKCE ou private_key_jwt. Il comprend le nouveau tableau de méthodes prises en charge CIMD ainsi que l'ancien champ à méthode unique. Les clients signés utilisent automatiquement leurs clés publiques publiées ; les utilisateurs ne téléchargent pas de clé privée.

FreeLipSync n'offre pas d'enregistrement dynamique ouvert (DCR), d'authentification secrète client ou de subvention client_credentials. Si un client nécessite DCR, utilisez son option de client public préenregistré lorsqu'elle est disponible, ou utilisez la configuration API Key dans un client qui prend en charge les en-têtes Bearer personnalisés. Obtenez un ID attribué et enregistrez le rappel réel avant de le configurer. Un ID client API Key et un ID client OAuth sont des informations d’identification différentes.

Codex : fichier de configuration ou OAuth

Ajoutez ou modifiez un serveur HTTP distant sous Plugins → MCPs dans Codex ; certaines versions utilisent des serveurs Settings → MCP. Cette entrée locale MCP prend en charge la configuration API Key et est distincte de l'entrée OAuth du plug-in hébergé décrite ci-dessus.

Choisissez une source d'informations d'identification. Les exemples utilisent https://freelipsync.com/mcp. Pour staging, remplacez-le par https://staging.freelipsync.com/mcp et créez la clé dans votre compte staging. Les clés de production et staging ne sont pas interchangeables.

Option A : collez un API Key dans les paramètres du bureau

Utilisez cette option lorsque vous ne souhaitez pas configurer de variables d'environnement. Créez une clé dans Console Agent, copiez le secret complet, puis renseignez :

Utilisez un espace après Bearer ; la clé elle-même n'a pas de préfixe Bearer. Ne nommez pas l'en-tête FLS_API_KEY et ne collez pas le secret dans Bearer token env var. Enregistrez et reconnectez-vous ; si le client utilise toujours une ancienne configuration, redémarrez-le ou ouvrez une nouvelle session.

L’entrée personnelle équivalente ~/.codex/config.toml est :

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

Option B : fournir le API Key via une variable d'environnement

Bearer token env var prend un nom de variable, pas un secret. Définissez-le sur FLS_API_KEY. Cette variable doit exister dans l'environnement du processus exécutant Codex. Sa valeur est la clé complète sans Bearer  ; Codex ajoute le préfixe.

Le fichier de configuration personnel correspondant est :

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

Pour la Codex CLI lancée depuis un terminal :

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

L'exportation d'une variable dans un autre terminal ne met pas à jour une application de bureau déjà en cours d'exécution. Une application lancée à partir du menu Dock ou Démarrer ne peut pas non plus hériter des variables du terminal. Si vous ne savez pas comment fournir l'environnement de processus de bureau, utilisez l'option A.

Headers crée des en-têtes de requête HTTP. Headers from environment variables lit les valeurs d'en-tête des variables d'environnement existantes. Aucun des deux champs ne crée de variable d'environnement système. Un en-tête nommé FLS_API_KEY ne remplit pas le paramètre Bearer et un espace réservé gris tel que MCP_BEARER_TOKEN ne signifie pas que la variable a été configurée.

Option C : autoriser dans le navigateur avec OAuth

Entrez uniquement le URL. Laissez Bearer token env var, Headers et Headers from environment variables vides, y compris en supprimant toute ligne Authorization précédente. Enregistrez, choisissez Authenticate / Sign in là où cela est proposé, connectez-vous à FreeLipSync et approuvez la connexion. Aucun API Key ne doit être créé ou collé.

Pour un fichier de configuration, conservez uniquement :

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

Commandes CLI :

# 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

Remplacez freelipsync dans les commandes par le nom de votre serveur enregistré. Les trois blocs TOML ci-dessus sont des alternatives ; conserver une entrée pour le serveur. Supprimez la configuration à clé avant de passer à OAuth : la connexion ne répare pas un en-tête Authorization incorrect qui est toujours configuré.

Vérifiez la connexion après avoir enregistré

Dans une nouvelle session, demandez : "Appelez FreeLipSync get_capabilities et get_usage pour vérifier mes modèles et mes crédits. Ne générez pas de vidéo. " Une réponse réussie du compte confirme la connexion ; un nom de serveur apparaissant seul dans la liste ne le fait pas.

Pour HTTP 401, vérifiez que le URL et la clé appartiennent au même environnement, que la clé est complète, que l'en-tête statique est Authorization: Bearer YOUR_API_KEY et qu'il ne reste aucune ancienne variable Bearer ou paramètre Authorization en double. Avec l'option B, vérifiez également l'environnement du processus qui lance réellement le client.

Consultez le guide officiel OpenAI MCP et la référence de configuration pour les définitions de champs.

Claude Code : fichier de configuration ou OAuth

Pour l'accès à API Key, placez cette entrée dans une configuration MCP personnelle/locale ou fusionnez-la dans .mcp.json pour le projet. La variable d'environnement est étendue par Claude Code. Conservez la clé réelle en dehors de la configuration partagée et démarrez Claude Code avec l'ensemble de variables.

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

Pour OAuth, supprimez d'abord l'entrée saisie ou son en-tête Authorization, ajoutez un serveur HTTP uniquement URL et authentifiez-vous via /mcp dans une session Claude Code interactive :

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

Utilisez une méthode à la fois. Un en-tête Bearer non valide configuré ne sera pas corrigé en vous connectant via un flux différent. Voir le guide officiel MCP de Claude Code.

Claude Desktop et Claude web

Pour OAuth, ouvrez la page de gestion Connectors de Claude, ajoutez un connecteur Web/à distance personnalisé nommé FreeLipSync et saisissez https://freelipsync.com/mcp. Choisissez de vous connecter et utilisez l'identité client publiée de Claude si disponible ; complétez la page d'autorisation FreeLipSync. Une organisation peut demander à son propriétaire d’activer d’abord le connecteur. Les connecteurs distants doivent atteindre un point de terminaison public HTTPS ; localhost n'est pas accessible depuis le cloud de Claude. Voir le Guide du connecteur à distance de Claude.

Pour l'ancienne route du fichier de configuration Claude Desktop, un client stdio uniquement a besoin d'un pont local vers le point de terminaison distant ; coller un url distant dans une configuration stdio n'est pas suffisant. Une fois Node.js / npx installé, fusionnez cette entrée dans claude_desktop_config.json (ouvrez-la à partir des paramètres de développement de Desktop) et redémarrez Desktop. Remplacez l'espace réservé localement et gardez ce fichier personnel privé.

{
  "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 est un pont de compatibilité tiers et non un package FreeLipSync. Consultez ses instructions du responsable et votre version installée. Son argument d'en-tête prend en charge l'expansion de l'environnement ; le format ci-dessus évite également les espaces à l'intérieur de l'argument. Préférez le support HTTP natif d’un client lorsqu’il est disponible. Ce fichier Desktop n'est pas le mécanisme de configuration pour Claude web.

Cursor : fichier de configuration ou OAuth

Pour l'accès à API Key, utilisez votre ~/.cursor/mcp.json personnel (ou un projet .cursor/mcp.json maintenu hors du contrôle de source lorsqu'il contient une clé). Remplacez l'espace réservé localement. Ne présumez pas que l'extension de l'environnement à partir du format d'un autre client fonctionne dans votre version Cursor installée.

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

Pour OAuth, utilisez la même entrée avec uniquement url, en supprimant l'objet en-têtes. Dans les paramètres MCP de Cursor, connectez-vous/authentifiez-vous et complétez l'autorisation du navigateur si proposée. Rechargez ou redémarrez le client après avoir modifié sa configuration, puis vérifiez les outils en mode Agent. Si le flux d'enregistrement de cette version est incompatible, utilisez la configuration de clé ci-dessus. Voir Instructions officielles MCP de Cursor.

VS Code et GitHub Copilot

Pour une configuration native VS Code MCP, créez .vscode/mcp.json avec une saisie de mot de passe plutôt qu'une vraie clé dans le fichier :

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

Pour OAuth, supprimez inputs et headers, en conservant le type de serveur et URL. Démarrez/connectez le serveur et suivez l'invite d'authentification ; l’enregistrement du client doit être compatible comme décrit ci-dessus. Sélectionnez ses outils en mode Agent de Copilot et essayez l'invite de vérification ci-dessous. Le format VS Code utilise servers, et non le mcpServers d'un autre client ; les entrées interactives ne sont pas prises en charge par tous les faisceaux Copilot ou configurations portables. Voir la référence VS Code MCP.

Vérifiez les outils et essayez une invite

Demandez d'abord à votre agent : "Utilisez FreeLipSync pour vérifier mes modèles disponibles et mon solde de crédit. Ne créez pas encore de vidéo. " Il doit appeler get_capabilities et get_usage, sans dépenser de crédits. Un serveur répertorié dans un fichier de configuration ne constitue pas une preuve suffisante que l'authentification a fonctionné.

Essayez ensuite : "Faites une courte photo parlante Image Fast à partir de mon image et de mon audio. Obtenez d'abord un devis et indiquez-moi les crédits. Attendez ma confirmation avant de soumettre. Si vous ne pouvez pas télécharger mes fichiers locaux, donnez-moi les liens de téléchargement du navigateur. " Gardez l'approbation du client pour les outils de dépenses activés.

Télécharger des fichiers locaux à partir d'un agent

Il existe deux chemins de fichiers locaux, plus l'importation HTTPS. Ne transmettez pas de chemin local en tant que import_asset URL.

• Un client capable de lire des fichiers et d’envoyer des requêtes HTTP PUT appelle create_asset_upload avec kind, filename, content_type, size_bytes et idempotency_key. Il envoie les octets du fichier à l’URL reçue avec les en-têtes indiqués, puis appelle confirm_asset_upload. Ne transmettez jamais votre API Key aux URL de stockage signées.
• Un client sans accès au fichier local/HTTP appelle create_asset_upload_session pour chaque image/vidéo/audio. Vous ouvrez browser_upload_url, vous connectez au même compte FreeLipSync et téléchargez dans le navigateur. L'agent conserve asset_id et interroge get_asset ; vous n’êtes pas obligé de recopier l’ID. Ne partagez pas publiquement le ticket de téléchargement.
• Pour un fichier HTTPS public existant, import_asset avec kind, url, idempotency_key démarre l'importation. Attendez d'être prêt avant de citer.

Un connecteur URL uniquement/cloud n'accède pas à vos fichiers de bureau simplement en utilisant MCP. Par exemple, les connecteurs distants de Claude fonctionnent à partir de son cloud, utilisez donc les liens de téléchargement du navigateur lorsque le client ne peut pas transférer votre pièce jointe vers le URL signé.

Gestion des crédits, des tentatives et des connexions

API et MCP utilisent les mêmes tarifs : Video Lip Sync / Image Fast, 1 crédit/s ; Image Max, 2 ; Image Super / Music Video, 3. La durée audio vérifiée est arrondie à la seconde supérieure, avec un minimum de 5 secondes. estimate_generation renvoie total_points et un identifiant de devis ; create_generation reçoit ce quote_id et une idempotency_key. L’envoi de fichiers, la consultation et les devis ne consomment pas de crédits. Une génération acceptée ne peut pas être annulée ; seul un échec de traitement restitue la réserve initiale. Voir facturation et récupération de l’API.

Conservez la même citation et la même clé d'idempotence après une soumission incertaine. Enregistrez l'ID de travail renvoyé et interrogez-le ; ne demandez pas à l'agent de « réessayer » en effectuant une autre tâche. Interrogez à l’aide de poll_after_seconds, reculez sur Retry-After et utilisez list_generations pour interroger plusieurs tâches actives ensemble. L'API et MCP partagent le compartiment de lecture du compte, tandis que les trois points d'entrée site Web/API/MCP partagent la fréquence de soumission et la capacité d'exécution vidéo. Le site Web et l'API/MCP ont des allocations de tâches inachevées distinctes : Free 1, Starter 3, Pro 10 dans chaque pool. Toutes les informations d'identification REST/MCP partagent le pool API/MCP. Voir pourquoi utiliser API/MCP pour des exemples.

Révoquer une clé ou une connexion OAuth à partir de la console Agent. La révocation d'une clé arrête son utilisation future dans chaque client qui la partage, y compris REST ; la révocation d'une connexion OAuth affecte uniquement cette connexion. Aucune des deux opérations n’annule les tâches déjà acceptées. La suppression d'une entrée de client local à elle seule ne révoque pas les informations d'identification sur FreeLipSync. Utilisez des clés distinctes ou des autorisations indépendantes lorsque vous avez besoin d'une révocation distincte, et non pour augmenter la simultanéité.

Dépannage

Les paramètres du client peuvent changer d'une version à l'autre. Reportez-vous à la documentation officielle liée à chaque client pour les instructions actuelles. Besoin d’une intégration directe HTTP ? Lisez la documentation API.