通过 MCP 连接你的智能体

选择接入方式

FreeLipSync 的远程 MCP 地址为 https://freelipsync.com/mcp。智能体通过它使用与 REST API 相同的视频生成能力和购买点数。必须有已注册的 FreeLipSync 账号，不支持匿名访问。在 staging 测试时，请替换为 staging 的站点域名。

API Key 配置文件和 OAuth 两种方式都支持。 每条服务配置只选一种凭据来源；已有配置文件接法仍然可用，不强制改成 OAuth。

Key 创建后只展示一次，请立即复制保存；OAuth 不需要手动复制 Key。每个账号最多 5 个 API Key、5 条独立 OAuth 授权连接。用 Key 接入只占 Key 名额，不占 OAuth 连接名额。两者共用账号余额、模型能力和限制。

OAuth 授权流程

1. 在客户端添加远程 HTTPS 地址，不设置 Authorization 请求头或 API Key。
2. 根据客户端界面选择连接、Authenticate 或 Sign in。
3. 在打开的浏览器中登录 FreeLipSync，核对请求授权的客户端与权限。
4. 默认创建新连接；也可以明确选择替换旧连接。另一设备独立授权通常会单独计数。
5. 允许智能体使用购买的 API 点数，确认授权后返回客户端，按下文验证工具。

你可以拒绝授权。5 条连接满额时，需明确替换旧连接，或先到智能体控制台撤销；不会静默踢掉旧连接。刷新 token 或恢复原连接不新增名额。授权后的智能体可以在提交生成任务时消费账号点数。

OAuth 需要客户端兼容：FreeLipSync 支持公开客户端身份文档 CIMD 和预注册客户端，不提供开放动态注册端点。请使用兼容版本，或在客户端支持时配置已分配的 client ID。若客户端只支持动态注册、登录时报注册错误，可先用 API Key，或联系支持核对客户端注册。

客户端兼容性与 OAuth 差异

客户端身份登记和换取 token 的认证方式是两件事。FreeLipSync 支持 CIMD 或预登记 Client ID，支持 none＋PKCE 和 private_key_jwt；兼容 CIMD 新的多方法数组和旧单值字段。签名客户端的公钥由服务端自动获取，用户无需上传私钥。

当前不提供开放动态登记（DCR）、共享 client secret 认证或 client_credentials grant。若某版本只支持 DCR，可在它支持的情况下使用预登记 public Client ID，或改用支持自定义 Bearer 请求头的客户端配置 API Key。预登记需先取得分配的 ID、登记实际回调；Client ID 与 API Key 不能混用。

Codex：配置文件与 OAuth

在 Codex 的 Plugins → MCPs 中添加或编辑远程 HTTP 服务；有些版本的入口在 Settings → MCP servers。这里的本地 MCP 配置可以使用 API Key，与上文的托管插件 OAuth 入口不同。

先选一种认证方式，按对应小节填写，不要同时设置多个 Authorization 来源。 下文默认 URL 为 https://freelipsync.com/mcp；测试 staging 时统一改成 https://staging.freelipsync.com/mcp，并使用 staging 账号创建的 Key。生产与 staging 的 Key 不能混用。

方式 A：桌面界面直接填写 API Key

适合不想设置环境变量的桌面用户。先在智能体控制台创建并复制完整 Key，再填写：

Bearer 后只有一个空格，Key 本身不带 Bearer 前缀。不要把 FLS_API_KEY 当作 Header 的 Key，也不要把真实密钥粘进 Bearer token env var。保存后重新连接 MCP；若客户端仍使用旧配置，再重启客户端或新建会话。

如果直接编辑个人 ~/.codex/config.toml，等价配置是：

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

方式 B：通过环境变量提供 API Key

Bearer token env var 填的是变量名，不是密钥值。 例如填 FLS_API_KEY；实际启动 Codex 的进程必须能读到该变量，变量内容是完整 Key，不含 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
# 在新会话中用 /mcp 检查连接。

在另一个终端执行 export，不会把变量传给已经运行的桌面应用；从 Dock／开始菜单启动的应用也不一定继承终端变量。桌面用户不确定如何传递进程环境时，使用方式 A。

Headers 只创建 HTTP 请求头；Headers from environment variables 从已经存在的环境变量读取请求头值，两者都不会创建系统环境变量。在 Headers 中添加 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 操作：

# 仅在尚未添加同名服务时执行下一条；已有配置请直接编辑。
codex mcp add freelipsync --url https://freelipsync.com/mcp
codex mcp login freelipsync
codex mcp list

命令中的 freelipsync 必须与你保存的服务名一致。上面的三个 TOML 配置块是互相替代的方式，合并时只保留同一个服务的一份配置。切换到 OAuth 前移除 API Key 配置，不能靠重新登录修复一个仍然存在的错误 Authorization 请求头。

保存后确认是否接通

在新会话中让智能体执行：“调用 FreeLipSync 的 get_capabilities 和 get_usage，检查可用模型和点数，不生成视频。” 成功返回账号信息才表示连接可用；列表中出现服务名称并不足以证明认证成功。

如果仍返回 401，依次检查：URL 和 Key 是否属于同一个环境、密钥是否完整、静态 Header 是否为 Authorization: Bearer YOUR_API_KEY、有没有遗留的 Bearer 环境变量或另一条 Authorization 配置。走环境变量方式时，还要确认变量属于实际启动客户端的进程。

字段含义与配置文件选项见 OpenAI 官方 MCP 说明和配置参考。

Claude Code：配置文件与 OAuth

API Key 方式可放在个人/本地 MCP 配置，或合并到项目 .mcp.json。Claude Code 会展开环境变量，不要把真实 Key 写入共享项目配置；启动前设置环境变量。

{
  "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 方式先移除带 Key 的配置或 Authorization 请求头，再添加仅 URL 的 HTTP 服务。在交互式 Claude Code 会话中通过 /mcp 完成授权：

claude mcp add --transport http --scope user freelipsync https://freelipsync.com/mcp
claude
# 在 Claude Code 中输入 /mcp，为 freelipsync 选择 Authenticate。

同一个服务只保留一种凭据来源。配置了无效 Bearer header 时，走另一条登录流程不能修复这个请求头。参见 Claude Code 官方接入说明。

Claude Desktop 与 Claude 网页版

OAuth 方式在 Claude 的 Connectors / 连接器 管理页添加自定义 Web/远程连接，名称可填 FreeLipSync，URL 为 https://freelipsync.com/mcp。选择登录方式，并在可用时使用 Claude 公开客户端身份；随后完成 FreeLipSync 授权。团队环境可能需要管理员先启用连接器。远程连接从 Claude 云端访问公网 HTTPS 服务，不能访问你电脑的 localhost。操作入口见 Claude 官方远程连接器说明。

旧的 Claude Desktop 配置文件方式也保留：仅支持 stdio 的客户端，需要本地桥接程序连接远程服务，不能直接把 url 填入 stdio 配置。安装 Node.js / npx 后，在 Desktop 的开发者设置中打开 claude_desktop_config.json，合并下方条目并重启。请在本机替换占位 Key，并保持该个人文件私密。

{
  "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 提供的软件包。使用前核对维护者说明和安装版本。它支持在 header 参数中展开环境变量，上面的格式也避免了参数内部空格问题。客户端有原生 HTTP 支持时可优先使用。这个 Desktop 文件不是 Claude 网页版的配置方式。

Cursor：配置文件与 OAuth

API Key 方式使用个人 ~/.cursor/mcp.json，或项目 .cursor/mcp.json。在本地替换占位符；包含真实 Key 的文件不要提交到仓库。不要假定其他客户端的环境变量展开语法适用于你安装的 Cursor 版本。

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

OAuth 使用相同条目但仅保留 url、删除 headers。在 Cursor 的 MCP 设置中连接/认证，按提示完成浏览器授权。修改后重新加载或重启客户端，在 Agent 模式检查工具。若该版本的注册流程不兼容，使用上方 Key 配置。见 Cursor 官方 MCP 说明。

VS Code 与 GitHub Copilot

原生 VS Code MCP 配置文件为 .vscode/mcp.json。建议用密码输入变量，不在文件中写真实 Key：

{
  "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，只保留 type 与 url。启动/连接服务后按认证提示操作，客户端注册需满足前述兼容条件。在 Copilot 的 Agent 模式选择工具，用下方提示验证。VS Code 的顶层键为 servers，不是其他客户端的 mcpServers；交互输入变量也并非每个 Copilot 运行环境或可移植配置都支持。参见 VS Code MCP 配置说明。

验证工具与首次使用

先对智能体说：“使用 FreeLipSync 查询我的可用模型和点数余额，先不要创建视频。” 应调用 get_capabilities 与 get_usage，不会消费点数。配置文件中能看到服务名称，不等于已经认证成功。

再试：“用我的图片和音频制作一条简短的 Image Fast 说话视频。先获取报价并告知点数，等我确认再提交。如果不能上传本地文件，就给我网页上传链接。” 建议保留客户端对消费类工具的确认。

智能体如何上传本地文件

本地文件有两条路径，另外也支持 HTTPS 导入。不要把本地路径传给 import_asset。

• 能读取文件并发 HTTP PUT 的客户端，调用 create_asset_upload，传 kind、filename、content_type、size_bytes、idempotency_key，按返回的地址与 headers 上传真实字节，再调用 confirm_asset_upload。不要把 API Key 转发给签名存储地址。
• 无法读取本地文件或上传的客户端，对图片/视频/音频分别调用 create_asset_upload_session。你打开 browser_upload_url，登录同一个 FreeLipSync 账号并上传，智能体保留 asset_id 并查询 get_asset，不需要你手动复制 ID 回去。不要公开上传 ticket。
• 已有公网 HTTPS 文件时，调用 import_asset，传 kind、url、idempotency_key，等待导入 ready 后再报价。

使用远程 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 计费与恢复规则。

提交结果不明时保留同一个 quote 与幂等键；保存返回的任务 ID 并查询，不要让智能体通过新建任务“再试一次”。按照 poll_after_seconds 轮询，遇到 Retry-After 退避，多个任务优先用 list_generations 合并查询。API/MCP 共用读取桶；网页、API、MCP 共用提交频率与视频执行资源；网页和 API/MCP 分别拥有 Free 1、Starter 3、Pro 10 个未完成任务名额。REST/MCP 的所有 Key 和连接共用 API/MCP 组。参见为什么用 API/MCP。

在智能体控制台可撤销 Key 或 OAuth 连接。撤销 Key 会停止所有共用该 Key 的客户端和 REST 后续调用；撤销 OAuth 只影响那条连接，两者均不取消已接单任务。仅删除客户端本地配置不会撤销 FreeLipSync 上的凭据。需要独立撤销时才分配不同 Key 或独立授权，而不是通过它们增加并发。

常见问题

客户端设置可能会随版本变化，以各客户端链接的官方说明为准。直接做 HTTP 集成可继续读 API 开发文档。