MCP Response Validation: JSON-RPC Errors and Tool Failures

A successful HTTP request, a valid JSON-RPC envelope and a successful tool operation are different observations. Keep all three in the diagnostic record.

Reviewed 19 October 2026. Examples are synthetic; no customer data or production outcomes.

Open the free MCP Response Inspector

Start with evidence

  1. Keep the response's HTTP status and content type as separate evidence. Do not paste authorization headers, session identifiers or customer data into a public issue.
  2. Inspect one JSON response object. For an SSE response, identify the relevant JSON message with an appropriate transport client first; the inspector does not decode a stream.
  3. Compare the response identifier with the request privately. Then read the expected method result schema and the actual operation outcome.

Worked examples

These examples exercise the current tool logic. Load the matching case on the tool page to reproduce its result. Downloads contain only the fixed synthetic example, never your pasted input.

Result envelope

Envelope structure passes. An empty tool list is not evidence that a useful tool ran.

Example JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": []
  }
}

Download result envelope JSON

Tool-level failure

Envelope structure passes, with a tool-level error flag. Structural success is not task success.

Example JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "Synthetic example failure."
      }
    ]
  }
}

Download tool-level failure JSON

Result and error together

Needs attention: a response must contain exactly one of result or error.

Example JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {},
  "error": {
    "code": -32603,
    "message": "Synthetic example error."
  }
}

Download result and error together JSON

Diagnostic decisions

Both result and error are present
A JSON-RPC response must select one of these members. The third example deliberately violates this rule and should fail the envelope check.
The envelope passes, but isError is true
The inspector reports a tool-level error flag. A valid outer envelope does not establish that a tool completed its task. Follow the tool's documented error contract.
The input begins with data: or HTTP headers
That is framing rather than one JSON object. Keep the raw evidence locally and extract the appropriate message without treating a transport frame as a standalone response.

What this does not establish

This is an envelope check, not full MCP conformance. It does not validate method-specific schemas, match request identifiers, detect duplicate JSON keys, verify transport/authentication, or establish a real tool outcome. A parseable result can still contain application-level problems. The copied checklist deliberately omits input, identifiers, payloads and server messages.

Optional analytics records sanitized page paths and fixed action labels after consent. The tools keep your input local. An action count is not a person, installation, resolved incident or sale.

Primary references

Continue with KnownFix