Подключение Agent через MCP

Выберите способ подключения

FreeLipSync предоставляет удаленную конечную точку MCP по адресу https://freelipsync.com/mcp. Он дает агенту те же возможности создания видео и кредиты на счете, что и REST API. У вас должна быть зарегистрированная учетная запись FreeLipSync; анонимный доступ не поддерживается. Вместо этого используйте источник staging при тестировании на staging.

Поддерживаются как конфигурация API Key, так и OAuth. Выберите один источник учетных данных для каждой записи сервера. Существующий файл конфигурации остается допустимым способом подключения; вам не обязательно использовать OAuth.

Создайте ключ и скопируйте его полное значение из диалога создания. Для OAuth копировать ключ не нужно. Аккаунт поддерживает до 5 API Keys и 5 независимых подключений OAuth. Доступ по API Key занимает слот ключа, а не подключения OAuth. Оба способа используют общие баланс, модели и ограничения аккаунта.

Порядок авторизации OAuth

1. Добавьте удаленный HTTPS URL в свой клиент без заголовка Authorization или настройки API Key.
2. Выберите Connect / Authenticate / Sign in, соответствующий клиенту.
3. В браузере войдите в свою учетную запись FreeLipSync и просмотрите запрашивающий клиент и разрешения.
4. Создайте новое соединение (по умолчанию) или явно выберите существующее соединение для замены. Успешная авторизация на другом устройстве обычно засчитывается отдельно.
5. Разрешите агенту потратить приобретенные вами кредиты API, а затем авторизируйтесь. Вернитесь к клиенту и проверьте инструменты ниже.

Вы можете отклонить запрос. Если все слоты подключения 5 используются, явно замените или отмените старое соединение в консоли Agent; новая авторизация не удаляет соединение автоматически. Обновление токена и повторное подключение существующей авторизации не добавляют слот. Соединение OAuth может потратить кредиты вашей учетной записи при отправке генерации.

Совместимость клиента OAuth имеет значение: FreeLipSync поддерживает опубликованные метаданные идентификации клиента (CIMD) и предварительно зарегистрированных клиентов, а не открытую конечную точку динамической регистрации. Используйте совместимую версию клиента или назначенный идентификатор клиента, если это поддерживается. Если клиент поддерживает только динамическую регистрацию и вход в систему не удался, используйте метод API Key или обратитесь в службу поддержки, чтобы проверить регистрацию клиента.

Совместимость клиентов и различия OAuth

Регистрация OAuth и аутентификация токена разделены. FreeLipSync поддерживает CIMD или предварительно зарегистрированный идентификатор клиента с none + PKCE или private_key_jwt. Он понимает новый массив поддерживаемых методов CIMD, а также старое поле с одним методом. Подписанные клиенты автоматически используют свои опубликованные открытые ключи; пользователи не загружают закрытый ключ.

FreeLipSync не предлагает открытую динамическую регистрацию (DCR), аутентификацию по секрету клиента или грант client_credentials. Если клиенту требуется DCR, используйте предварительно зарегистрированный вариант общедоступного клиента, если он доступен, или используйте конфигурацию API Key в клиенте, который поддерживает пользовательские заголовки Bearer. Получите назначенный идентификатор и зарегистрируйте фактический обратный вызов перед его настройкой. API Key и идентификатор клиента OAuth — это разные учетные данные.

Codex: файл конфигурации или OAuth.

Добавьте или отредактируйте удаленный сервер HTTP в разделе Plugins → MCPs в Codex; некоторые версии используют серверы Settings → MCP. Эта локальная запись MCP поддерживает конфигурацию API Key и отделена от записи OAuth размещенного плагина, описанной выше.

Выберите один источник учетных данных. В примерах используется https://freelipsync.com/mcp. Для staging замените его на https://staging.freelipsync.com/mcp и создайте ключ в своей учетной записи staging. Производственные ключи и ключи staging не являются взаимозаменяемыми.

Вариант А: вставьте API Key в настройки рабочего стола.

Используйте эту опцию, если вы не хотите настраивать переменные среды. Создайте ключ в консоли Agent, скопируйте полный секрет, затем заполните:

Используйте один пробел после Bearer; сам ключ не имеет префикса Bearer. Не называйте заголовок FLS_API_KEY и не вставляйте секрет в Bearer token env var. Сохраните и повторно подключитесь; если клиент все еще использует старую конфигурацию, перезапустите его или откройте новый сеанс.

Эквивалентная личная запись ~/.codex/config.toml:

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

Вариант Б: укажите API Key через переменную среды.

Bearer token env var принимает имя переменной, а не секрет. Установите для него значение FLS_API_KEY. Эта переменная должна существовать в среде процесса, выполняющего Codex. Его значение — полный ключ без Bearer ; Codex добавляет префикс.

Соответствующий файл личной конфигурации:

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

Для Codex CLI, запускаемого с терминала:

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

Экспорт переменной в другой терминал не приводит к обновлению уже запущенного настольного приложения. Приложение, запущенное из меню Dock или «Пуск», также может не наследовать переменные терминала. Если вы не знаете, как обеспечить среду рабочего стола, используйте вариант А.

Headers создает заголовки запроса HTTP. Headers from environment variables считывает значения заголовков из существующих переменных среды. Ни одно из полей не создает переменную системной среды. Заголовок с именем FLS_API_KEY не заполняет параметр Bearer, а серый заполнитель, например MCP_BEARER_TOKEN, не означает, что переменная настроена.

Вариант C: авторизоваться в браузере с помощью OAuth.

Введите только URL. Оставьте Bearer token env var, Headers и Headers from environment variables пустыми, включая удаление любой предыдущей строки Authorization. Сохраните, выберите Authenticate / Sign in там, где предлагается, войдите в FreeLipSync и подтвердите подключение. Никакой API Key не нужно создавать или вставлять.

Для файла конфигурации сохраните только:

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

Команды 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

Замените freelipsync в командах на сохраненное имя сервера. Три приведенных выше блока TOML являются альтернативами; оставьте одну запись для сервера. Удалите конфигурацию с ключами перед переключением на OAuth: вход в систему не исправляет неправильный заголовок Authorization, который все еще настроен.

Проверьте соединение после сохранения

В новом сеансе спросите: "Позвоните FreeLipSync get_capabilities и get_usage, чтобы проверить мои модели и кредиты. Не создавать видео". Успешный ответ учетной записи подтверждает соединение; имя сервера, появляющееся в списке само по себе, не имеет значения.

Для HTTP 401, убедитесь, что URL и ключ принадлежат одной и той же среде, ключ завершен, статический заголовок — Authorization: Bearer YOUR_API_KEY, и не осталось старых переменных Bearer или повторяющихся настроек Authorization. При выборе варианта Б также проверьте среду процесса, который фактически запускает клиент.

Определения полей см. в официальном руководстве OpenAI MCP и справке по настройке.

Claude Code: файл конфигурации или OAuth.

Для доступа к API Key поместите эту запись в личную/локальную конфигурацию MCP или объедините ее с .mcp.json для проекта. Переменная среды расширяется Claude Code. Не допускайте использования текущего ключа в общей конфигурации и запустите Claude Code с набором переменных.

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

Для OAuth сначала удалите ключевую запись или ее заголовок Authorization, добавьте сервер HTTP только для URL и выполните аутентификацию через /mcp в интерактивном сеансе Claude Code:

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

Используйте один метод за раз. Настроенный недопустимый заголовок Bearer не будет исправлен при входе через другой поток. См. Официальное руководство Claude Code по MCP.

Claude Desktop и Claude web

Для OAuth откройте страницу управления Connectors Клода, добавьте пользовательский веб-/удаленный соединитель с именем FreeLipSync и введите https://freelipsync.com/mcp. Выберите вход и используйте опубликованную учетную запись клиента Клода, если она доступна; заполните страницу авторизации FreeLipSync. Организация может потребовать от своего владельца сначала включить соединитель. Удаленные соединители должны достигать общедоступной конечной точки HTTPS; localhost недоступен из облака Клода. См. Руководство по удаленному разъему Клода.

Для более старого маршрута Claude Desktop файла конфигурации клиенту, использующему только stdio, требуется локальный мост к удаленной конечной точке; вставки удаленного url в конфигурацию stdio недостаточно. Установив Node.js/npx, объедините эту запись с claude_desktop_config.json (откройте ее в настройках разработчика рабочего стола) и перезапустите рабочий стол. Замените заполнитель локально и сохраните конфиденциальность этого личного файла.

{
  "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 — это сторонний мост совместимости, а не пакет FreeLipSync. Просмотрите его инструкции сопровождающего и установленную версию. Его аргумент заголовка поддерживает расширение среды; приведенный выше формат также позволяет избежать пробелов внутри аргумента. Предпочитайте встроенную поддержку HTTP клиента, если она доступна. Этот файл рабочего стола не является механизмом настройки Claude web.

Cursor: файл конфигурации или OAuth.

Для доступа к API Key используйте свой личный ~/.cursor/mcp.json (или проект .cursor/mcp.json, который не подлежит контролю версий, если он содержит ключ). Замените заполнитель локально. Не предполагайте, что расширение среды из формата другого клиента работает в установленной вами версии Cursor.

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

Для OAuth используйте ту же запись только с url, удалив объект заголовков. В настройках MCP Cursor подключитесь/аутентифицируйтесь и завершите авторизацию браузера, если она предлагается. Перезагрузите или перезапустите клиент после изменения его конфигурации, затем проверьте инструменты в режиме Agent. Если процесс регистрации этой версии несовместим, используйте конфигурацию ключа, указанную выше. См. Официальные инструкции Cursor для MCP.

VS Code и GitHub Copilot

Для собственной конфигурации VS Code MCP создайте .vscode/mcp.json с вводом пароля, а не реального ключа в файле:

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

Для OAuth удалите inputs и headers, сохранив тип сервера и URL. Запустите/подключите сервер и следуйте инструкциям по аутентификации; регистрация клиента должна быть совместима, как описано выше. Выберите его инструменты в режиме Agent Copilot и попробуйте воспользоваться подсказкой проверки ниже. Формат VS Code использует servers, а не mcpServers другого клиента; интерактивные входы поддерживаются не всеми жгутами или портативными конфигурациями Copilot. См. Справочник VS Code MCP.

Проверьте инструменты и попробуйте запрос

Сначала спросите своего агента: "Используйте FreeLipSync, чтобы проверить мои доступные модели и кредитный баланс. Пока не создавайте видео". Он должен вызывать get_capabilities и get_usage, не тратя кредиты. Сервер, указанный в файле конфигурации, не является достаточным доказательством того, что аутентификация сработала.

Затем попробуйте: "Сделайте короткую говорящую фотографию Image Fast из моего изображения и аудио. Сначала узнайте цену и сообщите мне кредиты. Прежде чем отправлять, дождитесь моего подтверждения. Если вы не можете загрузить мои локальные файлы, дайте мне ссылки для загрузки в браузере". Оставьте одобрение клиента для инструментов расходования включенным.

Загрузка локальных файлов из агента

Существует два пути к локальным файлам, а также импорт HTTPS. Не передавайте локальный путь как import_asset URL.

• Клиент с доступом к файлам и HTTP PUT вызывает create_asset_upload с kind, filename, content_type, size_bytes и idempotency_key. Затем он загружает байты файла по полученному URL с указанными заголовками и вызывает confirm_asset_upload. Никогда не передавайте API Key на подписанные URL хранилища.
• Клиент без доступа к локальному файлу/HTTP вызывает create_asset_upload_session для каждого изображения/видео/аудио. Вы открываете browser_upload_url, входите в ту же учетную запись FreeLipSync и загружаете в браузер. Агент сохраняет asset_id и опрашивает get_asset; вам не нужно копировать идентификатор обратно. Не делитесь билетом на загрузку публично.
• Для существующего общедоступного файла HTTPS import_asset с kind, url, idempotency_key запускает импорт. Прежде чем цитировать, дождитесь готовности.

Коннектор только для URL/облако не обеспечивает доступ к файлам вашего рабочего стола просто с помощью MCP. Например, удаленные соединители Claude запускаются из его облака, поэтому используйте ссылки для загрузки в браузере, когда клиент не может передать ваше вложение на подписанный URL.

Кредиты, повторные попытки и управление соединениями

API и MCP используют одинаковые ставки: Video Lip Sync / Image Fast — 1 кредит/с, Image Max — 2, Image Super / Music Video — 3. Проверенная длительность аудио округляется вверх до целой секунды, минимум 5 секунд. estimate_generation возвращает total_points и ID расчёта; create_generation принимает этот quote_id и idempotency_key. Загрузка, проверка использования и расчёт не расходуют кредиты. Принятую генерацию нельзя отменить; только сбой обработки возвращает исходную зарезервированную сумму. См. оплату и восстановление API.

Сохраняйте ту же кавычку и ключ идемпотентности после неуверенной отправки. Сохраните возвращенный идентификатор задания и запросите его; не просите агента «попробовать еще раз», поставив другое задание. Опросите с помощью poll_after_seconds, вернитесь к Retry-After и используйте list_generations для совместного запроса нескольких активных заданий. API и MCP совместно используют корзину чтения учетной записи, в то время как все три точки входа веб-сайт/API/MCP имеют общую частоту отправки и производительность выполнения видео. Веб-сайт и API/MCP имеют отдельные разрешения на незавершенные задачи: Free 1, Starter 3, Pro 10 в каждом пуле. Все учетные данные REST/MCP совместно используют пул API/MCP. Примеры см. в разделе зачем использовать API/MCP.

Отмените соединение ключа или OAuth с консоли Agent. Отзыв ключа останавливает его дальнейшее использование всеми клиентами, которые его используют, включая REST; отзыв соединения OAuth влияет только на это соединение. Ни одна операция не отменяет уже принятые задачи. Удаление только записи локального клиента не приводит к аннулированию учетных данных на FreeLipSync. Используйте отдельные ключи или независимые авторизации, когда вам нужен отдельный отзыв, а не для увеличения параллелизма.

Поиск неисправностей

Настройки клиента могут меняться в разных версиях. Текущие инструкции можно найти в официальной документации каждого клиента. Нужна прямая интеграция HTTP? Прочтите документацию API.