MCP error handling

The Casdoor MCP server reports protocol errors as JSON-RPC 2.0 errors. This page lists the codes and shows example responses.

Error codes

Code	Name	Cause
`-32700`	Parse error	The request isn't valid JSON
`-32600`	Invalid Request	A required field is missing
`-32601`	Method not found	The method name is unknown
`-32602`	Invalid params	The parameters are malformed
`-32001`	Unauthorized or insufficient scope	The request has no valid credentials, or the token lacks the scope of the tool

Example responses

Missing scope. The error names the scope that the tool requires and the scopes of the token:

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": -32001,
    "message": "insufficient_scope",
    "data": {
      "tool": "add_application",
      "granted_scopes": ["read:application"],
      "required_scope": "write:application"
    }
  }
}

Invalid JSON:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32700,
    "message": "Parse error",
    "data": "unexpected character at position 12"
  }
}

Unknown method:

{
  "jsonrpc": "2.0",
  "id": 8,
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": "Method 'unknown_method' not found"
  }
}

Errors that happen while a tool runs aren't JSON-RPC errors. The tool returns a result with the isError flag. See Result format.

Other protocol features

Notifications: The server accepts requests without an id field and doesn't answer them.
Batch requests: The server accepts an array of requests.

Health check: The ping method returns an empty result:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "ping"
}

Demo mode: When Casdoor runs in demo mode, the server rejects write operations and allows read operations and authentication.

Error codes​

Example responses​

Other protocol features​

See also​

Error codes

Example responses

Other protocol features

See also