Read MCP results without mistaking transport success for tool success

Keep three response layers separate

An MCP request crosses HTTP transport, JSON-RPC routing and a business operation. A successful HTTP response can contain a JSON-RPC error, and a valid JSON-RPC result can contain isError true for an operation that failed. Flattening those layers into response.ok produces false success messages. Preserve HTTP status, request ID, protocol error and tool result separately. This gives your client a precise place to record a malformed call, a denied inbox read, a disabled provider or an uncertain external action without claiming they are equivalent failures.

Recognize protocol and argument errors

Lupin returns -32600 for an invalid JSON-RPC request, -32601 for an unknown method or tool, and -32602 for invalid tool arguments. These usually mean the caller must repair the request or refresh the relevant contract rather than retry an unchanged network operation. Keep the original proposed action while correcting representation errors. If the corrected arguments change recipients, selected account or material content, return the action to review. A schema correction should not quietly become a different authorized external effect.

Parse content according to its type

Most Lupin MCP tools return the corresponding REST JSON body as a text content item. Parse that string deliberately after checking the result’s error flag. Browser screenshots can return a native image content item plus text metadata, so do not assume every content block is JSON text. Treat binary or base64 media as media, not an instruction-bearing model paragraph. Preserve useful source metadata and avoid dumping private response bodies into general logs. A client should support an unexpected content type as an explicit unsupported-result state rather than crashing into an optimistic fallback.

Interpret operational failures by code

A tool result can report missing_permission, workspace_key_required, not_found or provider configuration errors. Choose the next action from the structured code and known stage. A 404 may preserve a scope boundary and should not trigger a search through other tenants’ credentials. A provider not configured is not simulated success. An operation_failed result warns that the external outcome may be unknown; do not blindly replay a write with a new operation key. Store the uncertain state and reconcile using the original identity and available operation evidence.

Return evidence to the user plainly

Say whether the call was rejected before execution, failed with a definitive result, completed with a returned resource, or remains uncertain. For email, provider acceptance is distinct from delivery. For a browser action, a returned page or screenshot supports only what was actually observed. Do not ask the model to infer success from the absence of an exception. A tool error should also not be transformed into instructions that tell a later model to reveal more data or bypass a permission boundary.

Test the envelope combinations

Build fixtures for HTTP failure, JSON-RPC error, result.isError with JSON text, successful text JSON and successful image-plus-metadata. Add a timeout on a sensitive action and assert the client preserves its key and unresolved state. Your next step is one result decoder that every tool integration uses, with explicit branches rather than separate optimistic parsing in each feature.

Sources & verification

Reviewed against checked-in Lupin API handlers and documentation. Example requests were not executed against live providers.

• Lupin MCP result contract ↗Checked 2026-11-05
• MCP tool results and errors ↗Checked 2026-11-05
• Lupin structured error conventions ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.