fix(mcp-server): include agent error detail and status in tool errors

[hercemer42]

What

MCP tool error results now surface the agent's real error — the JSON:API errors[0].detail plus the HTTP status (e.g. The value "reason" is required (HTTP 422)) — instead of the generic Agent responded with HTTP {status}.

Why

registerToolWithLogging's catch built the { isError: true } text from error.message. For a raw AgentHttpError (e.g. getActionForm) that was the generic string, leaving the real cause buried in error.body.

Changes

• error-parser.ts — parseAgentError appends (HTTP <status>) to the extracted JSON:API detail; falls back to the raw message (no doubled status) when no detail can be extracted.
• tool-with-logging.ts — the catch builds the message via parseAgentError(error), preserving the existing non-Error fallback (JSON.stringify ?? String).
• Tests updated/extended: error-parser, tool-with-logging, with-activity-log.

Scope / notes

• Both error paths funnel through parseAgentError, so the suffix reaches all withActivityLog data tools (list/create/update/delete/associate/dissociate/listRelated) and getActionForm.
• executeAction is unchanged: agent-client converts its AgentHttpError to semantic ActionFormValidationError/ActionRequiresApprovalError upstream, dropping the status — out of scope.
• Response envelope unchanged (already MCP-spec-compliant).

Tests: test/utils (110) and test/tools (244) green; eslint / prettier / tsc clean.

fixes PRD-729

🤖 Generated with Claude Code

Note

Include HTTP status and JSON:API detail in MCP server tool errors

• Updates parseAgentError in error-parser.ts to append the HTTP status code to JSON:API error details, returning '<detail> (HTTP <status>)' instead of just '<detail>'.
• Updates registerToolWithLogging in tool-with-logging.ts to use parseAgentError in its catch block, surfacing structured error details for AgentHttpError instead of a raw stringified error.
• Behavioral Change: tool error messages now include HTTP status codes when a JSON:API detail is present; consumers parsing error strings may need to account for the new format.

📊 Macroscope summarized 9caee51. 2 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[linear-code]

PRD-729

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (2)

Rating	File	% Diff	Uncovered Line #s
	packages/mcp-server/src/utils/error-parser.ts	100.0%
	packages/mcp-server/src/utils/tool-with-logging.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

[hercemer42]

Claude Opus 4.8 (1M) — code review of #1739

No must-fix. The core fix is correct: the (HTTP <status>) suffix is appended only when a JSON:API detail is extracted (no double status on non-JSON:API bodies), the two-layer withActivityLog → tool-with-logging path does not double-append (the re-thrown Error hits the object-with-message branch, not the AgentHttpError branch), and undefined/null/circular throws are handled. Both changed source lines are covered by exact toEqual/toBe assertions.

Two preferential edge-case notes inline (both newly reachable via the parseAgentError switch). No convention violations. The executeAction path surfacing the detail without an HTTP suffix is the documented, intended asymmetry (agent-client converts its AgentHttpError to semantic errors upstream before mcp-server sees it).