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 密钥复制到静态标头中。
连接所需的值汇总如下。这份配置表并非特定客户端的配置文件:
{
"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 创建更多引擎。受邀成员以及在此设置流程推出前创建的组织不受影响。
核验账户访问范围 #
- 打开客户端的工具清单,找到
members_listMemberships和engines_list。 - 调用
members_listMemberships读取用户所属的组织。如果只有一个组织,就使用该组织;如果有多个可用组织,请选择目标组织,并保留其 ID 供本任务使用。 - 使用该组织的
orgId调用engines_list,然后从返回的data中选择一个引擎 ID。 - 使用所选工具前,先阅读各工具公布的参数结构。组织级工具需要显式指定组织字段;对象级工具则可以使用资源 ID。写入操作应限定在任务约定的范围内。
在同一成员关系列表中的组织之间切换,无需另建 OAuth 连接。请在工具声明的字段中传入所选 ID,例如 orgId 或组织的 id。服务器不会根据令牌自动指定一个固定组织。如果登录的用户不正确,请通过客户端的账户管理重新连接。
members_listMemberships #
此调用不需要组织 ID。intent 为可选项,用于描述任务:
{
"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:
{
"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 上的操作步骤相同:
- 打开设置 > 自定义 > 发现。
- 搜索
Lingo.dev,然后点击 Lingo.dev 连接器上的连接。 - 在 Lingo.dev 授权页面上,登录目标账户并点击批准。
Claude 会存储并续期凭据。连接后,请核验工具清单。
ChatGPT #
远程自定义应用是否可用、是否支持 OAuth,取决于账户及客户端版本。如果支持这些功能,请使用 /mcp URL,并授权目标 Lingo.dev 用户。
给智能体一个范围明确的首个任务 #
首个请求可以这样写:
检查所选本地化引擎的法语术语表和指令。说明已附加哪些资源,以及这些资源是否涵盖我提供的产品术语。应用任何更改前,请先提出建议。本任务不授权执行翻译、生成建议、创建密钥或管理成员。
请将该指令与客户端审批机制或适当的工具允许列表配合使用。提示词规定了请求执行的工作,但不会撤销凭据的写入权限。
如果工具发现或首次读取失败,请先参阅故障排查解决问题,再继续操作。