handler.test

Coming July 20, 2026

Fire a synthetic test trigger at a registered handler.

CategoryHandler
JSON-RPCtools/call
EndpointPOST /mcp

Description

Dispatches a synthetic trigger envelope with `mode: 'test'` and the same HMAC signing scheme as production. Useful during integration to verify your handler verifies the signature, returns 2xx within 30s, and calls back `trigger.complete`. Test triggers are recorded in the ledger but flagged synthetic.

Input schema

FieldTypeRequiredDescription
handler_idstringyesHandler to test.
action_classstringyesWhich action class to simulate (must be in the handler's registered set).

Output shape

typescript
{
  ok: boolean;
  trigger_id: string;
  dispatched_at: string;
}

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.test",
  "arguments": {
    "handler_id": "hnd_01HXP9HANDLER",
    "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
{
  "ok": true,
  "trigger_id": "trg_01HXP9TEST",
  "dispatched_at": "2026-05-27T15:32:00Z"
}

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