JSON-RPC 2.0: Requests, Responses, Errors, and Notifications

Why it exists

MCP messages use the JSON-RPC 2.0 envelope, making it predictable to match requests with responses and send one-way events.

Message types

• Request: Contains id, method, and optional params; a response is expected.
• Successful response: Contains the same id plus result.
• Error response: Contains the same id plus a structured error.
• Notification: Contains method and optional params, but no id; no response is returned.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": { "tools": [] }
}

Protocol error versus tool error

• A malformed request or unknown method may result in a JSON-RPC or protocol error.
• A valid tool call whose business action fails may return a tool result with isError: true.
• Actionable tool errors can help the model correct its behavior safely.

Debugging checklist

• Do the request and response IDs match?
• Has an id accidentally been included in a notification?
• Does the method name exactly match the specification?
• Are logs corrupting the transport's stdout output?