routing.set_default_handler

V1.1 · post-MVP

Set the default handler for an (action class, user) pair when the user has multiple registered AI products on Cortex.

CategoryRouting
JSON-RPCtools/call
EndpointPOST /mcp

Description

When a single end-user has more than one customer-app handler registered against the same action class (e.g. they use your sales tool *and* a separate scheduling tool, both built on Cortex), the substrate has to choose which handler receives the dispatch. `routing.set_default_handler` records the user's preference. This is the cross-app routing primitive; it has no effect until the user has multiple registered apps for the same action class.

Input schema

FieldTypeRequiredDescription
user_idstringyesThe end-user the preference applies to. Scoped to the bearer's tenant.
action_classstringyesAction class the preference applies to.
handler_idstringyesHandler that should receive triggers for (user × action class).

Output shape

typescript
{ ok: boolean; applied_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": "routing.set_default_handler",
  "arguments": {
    "user_id": "usr_01HXP9USER",
    "action_class": "communicate",
    "handler_id": "hnd_01HXP9HANDLER"
  }
}

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, "applied_at": "2027-02-14T10:11:00Z" }

Errors this tool can return

CodeMeaning
invalid_argumentsTool input failed Zod validation.
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