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 不可用	客戶技術負責人或實施負責人。
工具輸出在技術上不一致	對應模組的產品或工程負責人。
來源資料缺失或過期	資料管線負責人或來源系統負責人。
動作審批不清晰	工作流程的營運負責人。