MCP 故障排查

重试前,先排查工具发现、身份验证、组织访问、参数和结果不确定等问题。

根据症状确定下一步检查内容:找不到工具时,检查连接;调用被拒绝时,检查参数或权限错误。保留工具名称、不含机密信息的输入、响应,以及相关资源或源内容的修订版本。这些信息有助于恢复原本要完成的工作,避免重复执行结果尚不明确的写入操作。

找不到预期的工具 #

对照已配置的端点,检查客户端返回的工具清单。/mcp 和 /main 提供相同的需经身份验证才能使用的工具;/account 会在身份验证后重定向到 /main。

查找 members_listMemberships 和 engines_list,并按照首次读取示例操作。准确的名称和架构以当前的 tools/list 响应为准。API 端点存在,并不代表 MCP 也提供该端点。

如果只有部分工具未显示,请检查客户端的允许列表和批准设置,仅启用任务所需的工具。如果某个工具本应存在却未出现,请保留服务器及版本信息,以及不含机密信息的工具发现输出,以便报告问题。

GET 返回 405 #

在 /mcp 配置可流式 HTTP。通过身份验证后,对 /mcp 或 /main 发送 GET 请求会返回 405,并附带 Allow: POST;客户端通过 POST 发送 MCP 消息。令牌缺失或无效时,请求会在分发前返回 401。而向 /account 发送已通过身份验证的请求,则会返回指向 /main 的 308。这些 GET 响应无法验证有效的 MCP POST 连接能否正常工作。选择正确的传输方式后,请查看客户端的连接错误。

身份验证或组织不正确 #

对于 401,请确认连接已使用预期的 Lingo.dev 用户身份完成 OAuth 授权。托管服务器要求提供有效的用户持有者令牌;个人或服务 API 密钥既不能用于 x-api-key,也不能作为持有者令牌的值。请让客户端刷新授权,或通过客户端的账户管理功能重新连接。诊断信息中不要包含令牌。

调用 members_listMemberships,从 data 中选择目标组织,并将其 ID 传入下一个工具的组织字段。对于 engines_list,该字段为 orgId。在同一列表中切换组织,无需再次进行 OAuth 授权。如果当前登录的用户不正确,请重新连接;仅重启客户端可能仍会使用已保存的会话。

如果 ssoRequired 中列出了成员资格,请通过该组织的身份提供方登录 Lingo.dev,然后重新连接。如果 data 和 ssoRequired 均为空,请先在 https://lingo.dev/orgs/start 完成组织设置,再次读取成员资格。组织无法访问,可能是因为组织不存在、用户不是该组织的成员,或组织要求使用 SSO;不要一概将这类响应视为凭据过期。

如果工具因权限或使用资格不足而拒绝操作,请检查该操作的具体要求,而不是反复进行身份验证。能否访问组织与是否有权执行某项写入操作,是两项独立的检查。请说明缺少哪些权限,不要在未告知用户的情况下改用权限更广的角色或凭据。

工具提示组织设置尚未完成 #

该组织刚创建不久,创建者尚未在网页应用中完成集成、团队成员和首个引擎的设置。组织级工具可能要等设置完成后才能使用;重试或重新授权并不能完成这些步骤。members_listMemberships 仍然可用。请以组织创建者的身份打开消息中的链接 https://lingo.dev/orgs/<orgId>,完成消息列出的步骤,然后再次调用。参阅完成新组织的设置。

工具拒绝参数 #

将输入与连接返回的准确架构进行对照。当前工具参数采用扁平字段结构,嵌套值保留在架构指定的位置。不要自行添加 body、params 或 query 包装层。如果要求提供组织字段,请显式传入;该字段不会根据持有者令牌自动填入。可选的 intent 用于描述任务。支持的账户操作请参阅功能。

确认每个 ID 标识的对象。members_remove.id 是 members_list 返回的成员资格 ID;members_setRole.userId 标识该成员资格对应的用户。本地化引擎 ID 不能代替请求日志 ID。请原样复制不透明游标或完整精度的时间戳与 ID 对,不要根据界面显示的日期重新构造。

遵循架构对省略值与 null 值、数字与字符串、数组与单个值的区分。在尝试通过变通方法解决参数错误之前,请先检查已连接工具的架构。

账户写入操作或作业的结果不确定 #

重试前,请先读取相关资源或作业的状态。服务器接受密钥创建、邀请、审核决定、建议或作业后,仍可能发生网络错误。请先确认预期的变更是否已存在,不要自动重复提交。

对于已提交的预配作业,请先使用保存的作业 ID 读取 provisioningJobs_get,再决定是否重试。对于其他操作,请检查已保存的资源,以及已连接工具对操作完成条件的约定。翻译工作流请查阅 CLI 或 API 参考。

缺少文档或证据 #

使用 localization_search 搜索,再将某条结果的 path 传给 docs_fetch,读取完整页面。如果路径无法使用,请重新搜索该任务,并使用最新结果。知识库与基于文件的网站使用不同的存储路径,因此索引中可能缺少某些网站页面,或保留着过时版本。在判定某项功能不可用之前,请先查看网站上最新的参考文档。

报告尚未解决的 MCP 功能缺口时,请提供尝试执行的任务、准确的工具名称、服务器版本,以及不含机密信息的响应。确认收到报告,并不代表承诺修复日期。

对于质量方面的问题,请明确缺少的是哪一项:来源证据、已完成的评估、适用的标准,还是明确的答案。不同情况需要采取不同的后续措施。衡量介绍了如何报告现有证据,避免将尚无答案的情况视为通过。