Module: MCPClient::Errors::Codes

Defined in:
lib/mcp_client/errors.rb

Overview

JSON-RPC error codes used by MCP (basic/index.mdx "Error Codes").

MCP partitions the JSON-RPC server-error range: -32000..-32019 is implementation-defined (legacy, no meaning may be assumed beyond -32002), and -32020..-32099 is reserved for codes defined by the MCP specification itself.

Constant Summary collapse

PARSE_ERROR =

Standard JSON-RPC 2.0 codes

-32_700
INVALID_REQUEST = 
-32_600
METHOD_NOT_FOUND = 
-32_601
INVALID_PARAMS = 
-32_602
INTERNAL_ERROR = 
-32_603
HEADER_MISMATCH =

MCP 2026-07-28 spec-defined codes (reserved sub-range)

-32_020
MISSING_REQUIRED_CLIENT_CAPABILITY = 
-32_021
UNSUPPORTED_PROTOCOL_VERSION = 
-32_022
LEGACY_RESOURCE_NOT_FOUND =

Resource not found in protocol versions 2025-11-25 and earlier; replaced by INVALID_PARAMS but still accepted from older servers.

-32_002
MODERN_ERROR_CODES =

Codes that identify a modern (2026-07-28+) server. Receiving one of these means the peer speaks a per-request-metadata revision, so a dual-era client must retry or correct the request rather than fall back to the initialize handshake (basic/versioning.mdx).

[HEADER_MISMATCH, MISSING_REQUIRED_CLIENT_CAPABILITY,
UNSUPPORTED_PROTOCOL_VERSION].freeze
RESOURCE_NOT_FOUND_CODES =

Codes a resources/read error may carry to mean "resource not found" on a modern (2026-07-28+) server. Legacy servers only ever used -32002; for them -32602 is plain Invalid params.

[INVALID_PARAMS, LEGACY_RESOURCE_NOT_FOUND].freeze

Class Method Summary collapse

Class Method Details

.modern_error_code?(code) ⇒ Boolean

Returns whether it is a recognized 2026-07-28 protocol error.

Parameters:

  • code (Integer, nil) —

    a JSON-RPC error code

Returns:

  • (Boolean) —

    whether it is a recognized 2026-07-28 protocol error



120
121
122
 
# File 'lib/mcp_client/errors.rb', line 120

def self.modern_error_code?(code)
  MODERN_ERROR_CODES.include?(code)
end

.resource_not_found_code?(code, modern: true) ⇒ Boolean

Whether a resources/read error code means the resource does not exist. 2026-07-28 servers say -32602 (and clients SHOULD still accept the earlier -32002); a legacy session only ever meant not-found by -32002, so its -32602 stays a generic Invalid params.

Parameters:

  • code (Integer, nil) —

    a JSON-RPC error code from resources/read

  • modern (Boolean) (defaults to: true) —

    whether the session is a modern protocol revision

Returns:

  • (Boolean) —

    whether it means the resource does not exist



131
132
133
134
135
 
# File 'lib/mcp_client/errors.rb', line 131

def self.resource_not_found_code?(code, modern: true)
  return true if code == LEGACY_RESOURCE_NOT_FOUND

  modern && code == INVALID_PARAMS
end