handler.list

Coming July 20, 2026

List the registered handlers for the authenticated principal.

CategoryHandler
JSON-RPCtools/call
EndpointPOST /mcp

Description

Returns all handlers registered for the current bearer, optionally filtered by `action_class`. The `webhook_secret` is never returned here — only on creation and on rotation.

Input schema

FieldTypeRequiredDescription
action_classstringnoOptional action class filter.
enabled_onlybooleannoIf true, omit handlers in the disabled state. Defaults to `false`.

Output shape

typescript
{
  handlers: Array<{
    handler_id: string;
    url: string;
    action_classes: string[];
    enabled: boolean;
    challenge_status: "pending" | "verified";
    created_at: string;
    last_delivery_at?: string;
    last_delivery_status?: "success" | "failed" | "dlq";
  }>;
}

Example call

JSON-RPC tools/call request body (omit the JSON-RPC envelope when using an SDK; the SDK adds it for you):

jsontools/call params
{
  "name": "handler.list",
  "arguments": { "action_class": "communicate" }
}

Example response

Tool results are always wrapped as content[0].text with a stringified JSON body. The shape below is what you get back from JSON.parse(result.content[0].text):

jsonparsed result body
{
  "handlers": [
    {
      "handler_id": "hnd_01HXP9HANDLER",
      "url": "https://handlers.your-app.com/cortex",
      "action_classes": ["communicate", "schedule"],
      "enabled": true,
      "challenge_status": "verified",
      "created_at": "2026-05-27T14:31:00Z",
      "last_delivery_at": "2026-05-27T15:02:11Z",
      "last_delivery_status": "success"
    }
  ]
}

Errors this tool can return

CodeMeaning
unauthorizedMissing or invalid bearer token.

See the full error catalog for resolution steps on each code, plus the standard transport-layer responses (401, 429).

Notes