JSON-RPC error codes are used correctly

JSON-RPC error codes carry semantic meaning that MCP clients use to determine how to display and recover from errors. Using HTTP-style codes (404, 500) instead of JSON-RPC codes (-32601, -32603) causes client error handlers to misclassify failures — a method-not-found error processed as an internal error may suppress retry logic or show the wrong message. CWE-703 (improper check or handling of exceptional conditions) applies: error codes must accurately describe the failure type for clients to respond correctly, especially in automated AI workflows where error classification drives next-step decisions.

Use the standard JSON-RPC error codes. The MCP SDK exports ErrorCode and McpError — use them instead of constructing error objects manually.

// src/errors.ts — structured MCP errors
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js'

// In tool handlers:
throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: query')

// In custom message routers:
const METHOD_NOT_FOUND = -32601
const INVALID_PARAMS   = -32602
const INTERNAL_ERROR   = -32603

return {
  jsonrpc: '2.0',
  id: request.id,
  error: { code: METHOD_NOT_FOUND, message: `Unknown method: ${request.method}` }
}

Custom server error codes must be in the range -32000 to -32099 — never use HTTP status codes.