Check the call before it reaches a handler
An MCP request and a direct service call can reach the same operation through different entry points. The SDK registers strict Zod schemas, and the shared service parses raw input again, so direct callers don't skip the checks. Size and depth limits also stop nested JSON from carrying unbounded content.
A parse failure returns before dispatch. The security tests send unexpected synthetic input through the SDK and oversized text through the service, then check that the response doesn't echo the supplied value and that the rejected write creates no project. The data assertion checks the effect of the refusal, not just its error label.
Keep the explanation inside the response contract
Known failures such as a missing record or revision conflict retain controlled messages and retry guidance. An unexpected exception becomes a fixed internal error without its original text. That distinction lets the client act on familiar failures without receiving arbitrary implementation details.
Known messages still need care: the fallback doesn't sanitize strings deliberately produced by the application. Diagnostics also stay separate from protocol output. MCP messages use STDOUT; lifecycle logs use STDERR and describe configuration without printing the data directory. An error report mustn't corrupt the stream carrying the response.
Record the failed attempt once
After valid input reaches a write handler, an operational failure can create an audit event with the canonical request digest and controlled failure code. An idempotency conflict takes a different route and skips the extra event. If the failure audit itself can't be saved, the client still receives the fixed internal error.
The integration test follows a failed write with identical and changed retries under its key. Both conflict, and the expected audit count stays at one. A separate successful-retry test expects the original result without a duplicate project. These definitions were inspected, not rerun for this note.
Request rejection and operational failure are separate paths
Input validation precedes dispatch; valid write failures can produce a failure receipt without exposing arbitrary internal exceptions.
Service entry
Operation and storage
Caller response
Scroll or drag the background to move. Use the zoom buttons to resize.Arrow keys move between components. Enter selects.
Choose a component to explore
Select a numbered component on the map or use the component menu. Its details and connections will appear here.
No component selected.
All connections (8)
- 01 · Tool name and input → 02 · Strict input contractParse selected input contract · Direct call
- 02 · Strict input contract → 06 · Input-schema errorInvalid input · Blocked / denied
- 02 · Strict input contract → 03 · Operation handlerValidated input · Direct call
- 03 · Operation handler → 07 · Validated success responseOutput-schema check succeeds · Response / return
- 03 · Operation handler → 04 · Failure-audit eligibilityOperation failed · Direct call
- 04 · Failure-audit eligibility → 05 · Failure receipt and auditEligible failed write · Direct call
- 04 · Failure-audit eligibility → 08 · Mapped operational errorRead failure or conflicting retry · Response / return
- 05 · Failure receipt and audit → 08 · Mapped operational errorReturn controlled failure response · Response / return