MCP Errors and Audit

Use this guide when an MCP client cannot connect, cannot see a tool, receives weak output, or needs a review record for compute and write actions.

Error handling model

Symptom	Likely cause	Response
Gateway returns 403	The request did not include an API key.	Confirm the client sends X-API-Key on every request.
Gateway returns 401	The key is invalid, revoked, expired, or for a different environment.	Request a new key from the administrator and update the client configuration.
Tool list is empty	Endpoint is reachable, but the key has no matching scope or the module is unavailable.	Check endpoint, scope set, and module enablement with the key owner.
Tool call returns missing scope	The key can connect, but does not hold the required scope for that tool.	Use the Scope Matrix and request only the missing approved scope.
Tool name fails	The client hard-coded a tool that is not visible at runtime.	Run tool discovery and call only visible tools.
Output lacks evidence	Source data is missing, stale, or not mapped to the asset.	Run a data-readiness check before relying on the answer.
Compute result is blocked	Compute scope or review policy is missing.	Keep the request as a review task until assumptions and owner are defined.
Write action is blocked	Write scope, draft policy, or approval state is missing.	Return the draft content for human review and do not create the record.

Diagnostic sequence

1. Confirm host, endpoint path, and trailing slash.
2. Confirm the X-API-Key header is present.
3. Initialize the MCP session.
4. List tools at runtime.
5. Check whether the expected tool is visible.
6. Check the required scope in the generated Tool Reference.
7. Call a read-only tool before compute or write actions.
8. Record missing data, blocked scope, or approval requirements in the run record.

Audit record

Each accepted workflow run should retain enough information for an operator, engineer, or customer reviewer to understand how the output was produced.

Record field	Purpose
Request ID or task ID	Connects the run to the user request or operating task.
Client identity	Shows which MCP client or enterprise agent made the call.
Endpoint and scopes	Shows the governed access path used by the workflow.
Runtime-visible tools	Shows what the key could see at the time of the run.
Source evidence	Lists records, documents, timestamps, asset IDs, scene versions, and returned references.
Generated output	Separates confirmed facts, assumptions, missing data, and recommendations.
Review decision	Captures reviewer, decision, reason, and timestamp.
Final action	Links work order, inspection, scenario, validation, or feedback record.

Compute review

For simulation, optimization, forecasting, spatial analysis, and Physical AI preparation, record:

• task goal and boundary;
• input data and source timestamps;
• model, scenario, or scene version where applicable;
• assumptions and known limitations;
• result summary and alternative options;
• reviewer and acceptance state;
• follow-up validation or field comparison.

Write-action review

For work orders, inspection tasks, scenario records, and other controlled actions:

1. Generate a draft first.
2. Show evidence and missing-data notes beside the draft.
3. Require a reviewer decision.
4. Store the final action ID only after approval.
5. Capture rejected drafts and reviewer corrections for future workflow improvement.

Escalation notes

Situation	Escalate to
Key appears invalid or revoked	Key owner or FactVerse administrator.
Expected module endpoint is unavailable	Customer technical owner or implementation owner.
Tool output is technically inconsistent	Product or engineering owner for that module.
Source data is missing or stale	Data pipeline owner or source-system owner.
Action approval is unclear	Operating owner for the workflow.