MCP 错误与审计

当 MCP 客户端无法连接、看不到工具、输出质量不足，或计算和写入动作需要复核记录时，使用本指南处理。

错误处理模型

现象	可能原因	处理方式
Gateway 返回 403	请求未包含 API key。	确认客户端每次请求都发送 X-API-Key。
Gateway 返回 401	Key 无效、已吊销、过期，或属于其他环境。	向管理员申请新 key，并更新客户端配置。
工具列表为空	Endpoint 可达，但 key 没有匹配 scope，或模块不可用。	与 key 负责人确认 endpoint、scope 集合和模块启用状态。
工具调用返回缺少 scope	Key 可以连接，但没有该工具所需 scope。	使用 Scope 矩阵 只申请已批准的缺失 scope。
工具名调用失败	客户端硬编码了运行时不可见的工具。	执行工具发现，只调用可见工具。
输出缺少证据	来源数据缺失、过期或未映射到资产。	在依赖答案前运行数据就绪度检查。
计算结果被阻止	计算 scope 或复核策略缺失。	在假设和负责人明确前，将请求保留为复核任务。
写入动作被阻止	写入 scope、草稿策略或审批状态缺失。	返回草稿内容给人工复核，不创建记录。

诊断顺序

1. 确认 host、endpoint 路径和结尾斜杠。
2. 确认存在 X-API-Key header。
3. 初始化 MCP session。
4. 在运行时列出工具。
5. 检查预期工具是否可见。
6. 在生成的 工具参考 中确认所需 scope。
7. 在计算或写入动作前先调用只读工具。
8. 在运行记录中写明缺失数据、被阻止的 scope 或审批要求。

审计记录

每次已接受工作流运行都应保留足够信息，让运营人员、工程师或客户复核人理解输出如何产生。

记录字段	目的
请求 ID 或任务 ID	将运行结果连接到用户请求或运营任务。
客户端身份	说明哪个 MCP 客户端或企业 Agent 发起调用。
Endpoint 和 scope	说明工作流使用的受控访问路径。
运行时可见工具	说明该 key 在运行时能看到哪些工具。
来源证据	列出记录、文档、时间戳、资产 ID、场景版本和返回引用。
生成输出	区分已确认事实、假设、缺失数据和建议。
复核决策	捕获复核人、决策、原因和时间戳。
最终动作	链接工单、巡检、场景、验证或反馈记录。

计算复核

对于仿真、优化、预测、空间分析和 Physical AI 准备，应记录：

• 任务目标和边界；
• 输入数据和来源时间戳；
• 适用时的模型、场景或 scene 版本；
• 假设和已知限制；
• 结果摘要和备选方案；
• 复核人和接受状态；
• 后续验证或现场对比。

写入动作复核

对于工单、巡检任务、场景记录和其他受控动作：

1. 先生成草稿。
2. 在草稿旁显示证据和缺失数据说明。
3. 要求复核人决策。
4. 只有审批后才保存最终动作 ID。
5. 捕获被拒草稿和复核人修正，用于后续工作流改进。

升级说明

情况	升级给
Key 看起来无效或已吊销	Key 负责人或 FactVerse 管理员。
预期模块 endpoint 不可用	客户技术负责人或实施负责人。
工具输出在技术上不一致	对应模块的产品或工程负责人。
来源数据缺失或过期	数据管道负责人或来源系统负责人。
动作审批不清晰	工作流的运营负责人。