The investigation path
- 1. API symptom
- 2. SSH / runtime evidence
- 3. Database state
- 4. Root cause
- 5. Verify fix
Step 1 — Reproduce the API error
Reproduction turns a vague report into a check that can be repeated. For POST /orders, send the request from the intended environment and preserve enough detail to distinguish the failing request from nearby traffic.
- Method: confirm the request is POST rather than a similar GET, PUT, or retry endpoint.
- URL: record the resolved host, path, and relevant query parameters.
- Environment: verify dev, test, or production and the active variable values before sending.
- Request data: preserve the shape and identifiers while keeping secrets out of shared examples.
- Status and response: record the HTTP status, response body, and relevant headers.
- Timing: note when the request ran and how long it took so server evidence can be matched to it.
Step 2 — Check server evidence
Use SSH to inspect evidence from the service that handled the request. Unfour provides terminal, history, files, diagnostics, and saved tasks; it does not assume a particular log format or provide a fictional universal log parser.
Application logs
Search the relevant time window for the request identifier, route, error message, or stack trace. Avoid dumping unrelated logs into the investigation.
Process and runtime state
Check whether the expected process is running, restarting, resource constrained, or connected to the intended dependency.
Configuration evidence
Compare the deployed environment, service configuration, and relevant remote files with what the request was expected to use.
Step 3 — Inspect database state
Translate the current hypothesis into the smallest useful query. For an order failure, that may mean checking the referenced customer, inventory record, idempotency key, constraint, or partially created order—not browsing every table.
- Start read-only, especially for production and any environment whose state is hard to restore.
- Use request identifiers and timestamps from the earlier steps to keep the query focused.
- Confirm the connection points to the same environment as the API and server checks.
- If a mutation is genuinely required, review the generated or proposed SQL, target rows, transaction behavior, and rollback plan before execution.
Step 4 — Correlate the evidence
A root-cause claim should explain all three layers without ignoring contradictory evidence. For POST /orders, the useful chain might be: the API failed at 14:03, the service logged a foreign-key error for order ID 812, and the referenced customer record was missing in the same test database.
Time
Does the API request timestamp match the server error and the database event or record state?
Identity
Do request IDs, entity IDs, user IDs, and trace values refer to the same operation?
Environment
Were the API host, SSH connection, and database connection all pointed at the same target?
Causality
Does the proposed cause explain why this request failed, or is it merely something unusual found nearby?
Step 5 — Verify the fix
-
Apply the reviewed change
Change only the code, configuration, or data justified by the evidence, using the normal review and deployment path for that environment.
-
Repeat the original request
Send the same POST /orders request with the same relevant data and environment, not an easier substitute request.
-
Check the expected result
Confirm the response status and body, then inspect any server or database side effects that define success.
-
Check for regression clues
Review nearby error logs or unintended record changes when the fix could affect more than the original request.
Common mistakes
- Reading only the API response and guessing the server-side cause.
- Changing database data before understanding how the incorrect state was produced.
- Checking API, SSH, or database evidence from different environments.
- Treating a code change or successful deployment as proof that the original failure is fixed.
- Copying partial context among unrelated tools until timestamps, identifiers, and environment details drift apart.
Where MCP helps
MCP can assist this workflow without becoming the subject of the entire investigation. A compatible agent can query approved Unfour tools, correlate selected evidence from one workspace, and repeat checks after a proposed fix.
- Query approved saved requests, redacted history, SSH diagnostics, database structure, or read-only results.
- Compare timestamps, identifiers, environments, and results without manually re-pasting each fragment.
- Re-run the same bounded checks after a change so verification follows the original evidence path.
- Keep guarded and high-risk actions subject to workspace policy and content-bound confirmation.