MCP 连接设置

连接需要账户身份验证的工具,然后核验组织和工具清单。

将助手连接到你的 Lingo.dev 账户,然后通过读取请求确认目标组织。服务器以已登录的 Lingo.dev 用户身份执行操作。

账户连接 #

将远程服务器 URL 设置为 https://mcp.lingo.dev/mcp,并选择支持 OAuth 的 Streamable HTTP。启动客户端的授权流程,登录目标 Lingo.dev 账户并批准连接。客户端会通过 MCP 端点发现授权服务器,并管理访问凭据和刷新凭据。

MCP 请求在 Authorization: Bearer <access-token> 中携带用户访问令牌。该令牌不是永久的个人 API 密钥,也不与某个组织绑定。后端会检查用户是否有权访问各工具指定的资源。账户凭据介绍了这一权限机制及凭据处理方式。

在 x-api-key 中提供 API 密钥,或将 API 密钥用作持有者令牌的值,都无法通过此托管服务器的身份验证。请使用支持其 OAuth 连接的客户端,不要将 API 密钥复制到静态标头中。

连接所需的值汇总如下。这份配置表并非特定客户端的配置文件:

json
{
  "endpoint": "https://mcp.lingo.dev/mcp",
  "transport": "Streamable HTTP",
  "authentication": "OAuth user session"
}

将这些值对应到客户端支持的字段。身份验证信息的存储方式和配置语法因版本而异。该端点接受 MCP POST 请求:没有有效令牌时,会返回 401 及 OAuth 发现元数据;通过身份验证的 GET 请求会返回 405 Method Not Allowed。在浏览器中打开 URL,并不能测试已初始化的 MCP 连接。

现有托管 URL #

https://mcp.lingo.dev/main 提供相同的工具和用户权限。其 OAuth 发现流程与 /mcp 不同,因此正常运行的 /main 连接可以保留现有授权配置。迁移到 /mcp 时,请将其添加为新连接,并完成该 URL 的 OAuth 流程;不要将旧连接保存的授权设置与新 URL 混用。

旧版 https://mcp.lingo.dev/account 地址在收到有效用户令牌前会返回 401,收到后则通过 308 重定向到 /main,同时保留请求方法和请求正文。此重定向不会恢复 API 密钥身份验证,也不会恢复旧版与组织绑定的工具目录。迁移原先使用 API 密钥的连接时,请通过 OAuth 重新连接。

完成新组织设置 #

连接时,新账户需要在网页应用中为组织命名。随后,组织创建者还需在网页应用中完成三个步骤:集成、团队成员和首个引擎。网页应用会根据组织网站填充首个引擎的内容。集成和团队成员步骤可以跳过。在这三个步骤全部完成前,每个指定该组织的工具都会返回错误,列出未完成的步骤,并提供指向 https://lingo.dev/orgs/<orgId> 的链接;该链接会打开创建者当前所在的步骤。members_listMemberships 仍会列出该组织,方便助手找到其 ID。

打开链接,完成这些步骤,然后再次调用。完成后,助手即可正常工作,并可通过 engines_create 或 provisioningJobs_create 创建更多引擎。受邀成员以及在此设置流程推出前创建的组织不受影响。

核验账户访问范围 #

  1. 打开客户端的工具清单,找到 members_listMemberships 和 engines_list。
  2. 调用 members_listMemberships 读取用户所属的组织。如果只有一个组织,就使用该组织;如果有多个可用组织,请选择目标组织,并保留其 ID 供本任务使用。
  3. 使用该组织的 orgId 调用 engines_list,然后从返回的 data 中选择一个引擎 ID。
  4. 使用所选工具前,先阅读各工具公布的参数结构。组织级工具需要显式指定组织字段;对象级工具则可以使用资源 ID。写入操作应限定在任务约定的范围内。

在同一成员关系列表中的组织之间切换,无需另建 OAuth 连接。请在工具声明的字段中传入所选 ID,例如 orgId 或组织的 id。服务器不会根据令牌自动指定一个固定组织。如果登录的用户不正确,请通过客户端的账户管理重新连接。

members_listMemberships #

此调用不需要组织 ID。intent 为可选项,用于描述任务:

json
{
  "intent": "Find the organization whose French translation guidance I should inspect."
}

响应中的 data 包含可访问的组织及其 ID 和名称。可选的 ssoRequired 条目列出需要 SSO 登录的成员关系,而当前会话尚未完成相应的 SSO 登录。请通过该组织的身份提供商登录 Lingo.dev,然后重新连接。ssoRequired 中的组织暂时无法通过普通的组织级调用访问。

如果两个列表都为空,请打开 https://lingo.dev/orgs/start 设置首个组织,然后再次执行此读取操作。不要编造组织 ID,也不要仅因现有成员关系需要 SSO 就创建第二个组织。

engines_list #

将 org_example 替换为成员关系响应中的一个 ID:

json
{
  "orgId": "org_example",
  "intent": "Find the localization engine used for French translations."
}

后续执行引擎级读取操作时,请使用返回的 data 中的引擎 ID。这些是完整的工具参数,而非 HTTP 请求数据的封装结构。除了各项操作专用的字段,工具还支持可选的 intent。有关账户操作,请参阅功能。

各客户端的配置位置 #

请查阅客户端的最新文档,了解其配置语法和支持的传输方式。即使两个客户端使用同一端点,这些配置选择也很重要。

Claude Code #

为 /mcp 选择使用 OAuth 的远程 HTTP 连接。保存前,请确定将连接放在用户配置还是项目配置中。项目共享设置不得包含凭据;每位用户都应授权自己的账户连接。启用后,请核验工具清单。

Codex #

Codex 使用 TOML 配置,通常位于 ~/.codex/config.toml。请使用当前版本支持的远程 MCP 功能配置账户 URL。不要将其他客户端的 JSON 直接移植到 TOML 中。如果你的版本需要传输桥接程序,请在使用前检查桥接程序自身的身份验证和令牌存储方式;桥接程序也是一个持有凭据的进程。

Cursor #

请根据需要明确选择用户级设置或项目中的 .cursor/mcp.json。项目连接可让团队成员发现服务器定义,但不得共享明文账户密钥。每位用户都应授权自己的账户连接。

Claude Desktop 和 claude.ai #

Lingo.dev 已列入 Claude 连接器目录,因此无需提供 URL 或配置文件。Claude Desktop 和 claude.ai 上的操作步骤相同:

  1. 打开设置 > 自定义 > 发现。
  2. 搜索 Lingo.dev,然后点击 Lingo.dev 连接器上的连接。
  3. 在 Lingo.dev 授权页面上,登录目标账户并点击批准。

Claude 会存储并续期凭据。连接后,请核验工具清单。

ChatGPT #

远程自定义应用是否可用、是否支持 OAuth,取决于账户及客户端版本。如果支持这些功能,请使用 /mcp URL,并授权目标 Lingo.dev 用户。

给智能体一个范围明确的首个任务 #

首个请求可以这样写:

检查所选本地化引擎的法语术语表和指令。说明已附加哪些资源,以及这些资源是否涵盖我提供的产品术语。应用任何更改前,请先提出建议。本任务不授权执行翻译、生成建议、创建密钥或管理成员。

请将该指令与客户端审批机制或适当的工具允许列表配合使用。提示词规定了请求执行的工作,但不会撤销凭据的写入权限。

如果工具发现或首次读取失败,请先参阅故障排查解决问题,再继续操作。