Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Errors

Two layers

MCP distinguishes protocol errors from tool execution errors.

Protocol errors

Use JSON-RPC error responses for:

  • malformed JSON;
  • unknown methods;
  • unsupported protocol versions;
  • invalid request metadata;
  • unknown tools;
  • invalid tool arguments that fail schema validation.

These are transport-level failures. The client should not retry without changing the request.

Tool errors

Use a successful JSON-RPC response with isError: true and a structured error object in structuredContent:

{
  "isError": true,
  "structuredContent": {
    "code": "CE_PROCESS_NOT_FOUND",
    "message": "No process matches 'game.exe'.",
    "remediation": "Call process_list and retry with a PID.",
    "retryable": false,
    "details": {
      "query": "game.exe"
    }
  }
}

A tool error means the tool ran and the operation failed. The transport is healthy.

Error object

FieldTypeRequiredMeaning
codestringYesStable machine-readable code
messagestringYesHuman-readable summary
remediationstringYesWhat the caller can do next
retryablebooleanYesWhether an identical retry may succeed
detailsobjectNoStructured context, never secrets
causestringNoUnderlying Cheat Engine or OS message

Rules:

  • code is stable across versions; do not parse message.
  • remediation is actionable, not generic.
  • retryable is about an identical retry. A retry with different arguments is a new request.
  • details must not contain the bridge token, absolute user paths or raw target memory beyond what the caller requested.
  • cause is sanitized and truncated.

Codes

CodeMeaningRetryableTypical remediation
CE_INVALID_ARGUMENTArguments are semantically invalidNoFix the argument; see details.field
CE_UNSUPPORTED_PLATFORMTool is not available on this OS/archNoUse a supported platform or a different tool
CE_TOOL_NOT_IN_PROFILETool exists but is outside the active profileNoRestart with the profile named in details.profile
CE_BACKEND_UNAVAILABLEBridge or Cheat Engine is not reachableYesStart Cheat Engine and load the bridge
CE_BACKEND_BUSYBridge is processing another operationYesWait and retry; use tasks for long work
CE_ACCESS_DENIEDToken, permissions or OS access deniedNoCheck the token file and macOS permissions
CE_HANDLE_EXPIREDHandle is unknown, closed or expiredNoRe-open the process or start a new scan
CE_PROCESS_NOT_FOUNDNo process matches the queryNoCall process_list
CE_PROCESS_CLOSEDThe target exited or was detachedNoRe-open the process
CE_NOT_ATTACHEDNo process is open for this handleNoCall process_open
CE_INVALID_ADDRESSAddress is unmapped or malformedNoValidate with region_list or address_parse
CE_SCAN_NOT_FOUNDScan handle does not existNoStart a new scan
CE_SCAN_BUSYA scan is already running for this handleYesWait, poll scan_status, or cancel
CE_SCAN_CANCELLEDScan was cancelledNoStart a new scan
CE_DEBUG_NOT_ATTACHEDNo debugger session for this handleNoCall debug_attach
CE_BREAKPOINT_NOT_FOUNDBreakpoint ID does not existNoCall breakpoint_list
CE_LUA_ERRORLua raised an errorNoFix the script; see cause
CE_TIMEOUTOperation exceeded its deadlineMaybeCheck status before retrying; it may still be running
CE_INVALID_CURSORPagination cursor is invalid or expiredNoRe-run the original list call
CE_LIMIT_EXCEEDEDResult or size limit exceededNoNarrow the range or use pagination
CE_INTERNALUnexpected server errorMaybeReport with the request ID

Retry guidance

  • retryable: true means an identical request may succeed later. Use exponential backoff with jitter (for example 100 ms, 250 ms, 500 ms).
  • CE_TIMEOUT is ambiguous. A scan may still be running. Poll scan_status or the task before retrying.
  • CE_BACKEND_BUSY resolves when the current operation finishes; do not open a second bridge connection to bypass it.
  • Never retry CE_ACCESS_DENIED, CE_INVALID_ARGUMENT or CE_TOOL_NOT_IN_PROFILE without changing something.
  • Tasks are the preferred mechanism for operations that can exceed a client timeout.

Mapping from the bridge

Bridge conditionCode
Connection refusedCE_BACKEND_UNAVAILABLE
Missing or bad tokenCE_ACCESS_DENIED
Lua pcall failureCE_LUA_ERROR
openProcess returned no processCE_PROCESS_NOT_FOUND
Read at unmapped addressCE_INVALID_ADDRESS
Scan thread still activeCE_SCAN_BUSY
Socket read timeoutCE_TIMEOUT
JSON encode failureCE_INTERNAL

Progress and cancellation

  • Long operations report progress through tasks or scan_status, not by emitting unstructured log lines.
  • Cancellation is cooperative. scan_cancel and tasks/cancel set a flag; the scan checks it between regions.
  • A cancelled operation returns CE_SCAN_CANCELLED and, if requested, the partial results.

Logging

  • stdio: logs go to stderr only.
  • HTTP: logs go to stderr or a configured file.
  • Audit logs are opt-in and separate from error logs.
  • Tokens, raw memory and user paths are redacted by default.

References