handler.update

Coming July 20, 2026

Update a registered handler.

CategoryHandler
JSON-RPCtools/call
EndpointPOST /mcp

Description

Mutates `url`, `action_classes`, or `enabled` for a registered handler. Changing `url` triggers a new challenge POST against the new endpoint; the old URL stops receiving dispatches once the new one verifies.

Input schema

FieldTypeRequiredDescription
handler_idstringyesHandler to update.
urlstring (HTTPS URL)noNew endpoint. Triggers a new challenge POST.
action_classesstring[]noReplace the supported action classes.
enabledbooleannoEnable / disable. Disabled handlers do not receive new dispatches but retain their delivery history.

Output shape

typescript
{
  ok: boolean;
  handler: {
    handler_id: string;
    url: string;
    action_classes: string[];
    enabled: boolean;
    challenge_status: "pending" | "verified";
  };
}

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.update",
  "arguments": {
    "handler_id": "hnd_01HXP9HANDLER",
    "enabled": false
  }
}

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
{
  "ok": true,
  "handler": {
    "handler_id": "hnd_01HXP9HANDLER",
    "url": "https://handlers.your-app.com/cortex",
    "action_classes": ["communicate", "schedule"],
    "enabled": false,
    "challenge_status": "verified"
  }
}

Errors this tool can return

CodeMeaning
invalid_argumentsTool input failed Zod validation.
unauthorizedMissing or invalid bearer token.
handler_disabledThe registered handler is disabled (manual disable, repeated failed deliveries, or exceeded DLQ threshold).

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

Notes