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 が利用できない	顧客技術責任者または実装責任者。
ツール出力が技術的に一貫しない	対象モジュールの製品またはエンジニアリング責任者。
参照元データが不足または古い	データパイプライン責任者または参照元システム責任者。
操作承認が不明確	ワークフローの運用責任者。