action_classes.register · Cortex MCP Docs

Description

Namespace is locked to client_id. Enforces per-tenant quota, schema subset validation, and bumps world_version via customActionClassesHash. Per ADR-0022.

Input schema

Field	Type	Required	Description
`namespace`	`string`	yes	Client namespace (must match client_id).
`name`	`string`	yes	Action class name within namespace.
`payload_schema`	`object`	yes	JSON Schema 2020-12 subset (≤32KB, ≤8 levels).
`allowed_modes`	`Array<'ask'\|'notify'\|'silent'>`	yes	Supported dispatch modes.
`display_name`	`string`	no	Human-readable label.
`description`	`string`	no	Class description.
`legal_effect_classification`	`'none'\|'possible'\|'always'`	no	Default 'possible'.

Output shape

typescript

{ ok: true; class_id: string; namespaced_name: string; world_version: string } | { ok: false; error: 'namespace_collision' | 'namespace_owned' | 'quota_exceeded' | 'schema_invalid'; message: 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": "action_classes.register", "arguments": { "namespace": "acme_builder", "name": "transact", "payload_schema": { "type": "object", "properties": { "amount": { "type": "number" } } }, "allowed_modes": ["ask"] } }

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, "class_id": "550e8400-e29b-41d4-a716-446655440000", "namespaced_name": "acme_builder.transact", "world_version": "wv_01HXCUSTOMCL" }

Errors this tool can return

Code	Meaning
`namespace_owned`	action_classes.register rejected because the namespace is owned by a different client_id within the same tenant.
`quota_exceeded`	Per-minute, daily call, or daily inference budget exceeded.
`invalid_arguments`	Tool input failed Zod validation.
`unauthorized`	Missing or invalid bearer token.

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