register_events

Purpose

Confirm and atomically register pinned event definitions and a default funnel.

Access and effects

Owner workspace credential only. Member, partner and app-bound affiliate credentials cannot use this tool. Use the owned app UUID from list_apps. Only register_events writes; the other instrumentation tools read or generate code.

Example request

Identifiers are fictional. Use the actual owned app and returned plan; do not fabricate production receipts.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "register_events",
    "arguments": {
      "appId": "11111111-1111-4111-8111-111111111111",
      "events": [
        {
          "category": "setup",
          "definition": {
            "name": "setup_started",
            "label": "Setup started",
            "allowedProperties": [
              "result_code"
            ],
            "expectedOrigin": "app_reported"
          },
          "analyticsHandle": "crust.analytics.setup_started"
        },
        {
          "category": "setup",
          "definition": {
            "name": "setup_completed",
            "label": "Setup completed",
            "allowedProperties": [
              "result_code"
            ],
            "expectedOrigin": "app_reported"
          },
          "analyticsHandle": "crust.analytics.setup_completed"
        },
        {
          "category": "value",
          "definition": {
            "name": "first_value",
            "label": "First value",
            "allowedProperties": [
              "result_code"
            ],
            "expectedOrigin": "app_reported"
          },
          "analyticsHandle": "crust.analytics.first_value"
        },
        {
          "category": "feature",
          "definition": {
            "name": "feature_used",
            "label": "Feature used",
            "allowedProperties": [
              "result_code"
            ],
            "expectedOrigin": "app_reported"
          },
          "analyticsHandle": "crust.analytics.feature_used"
        },
        {
          "category": "error",
          "definition": {
            "name": "feature_failed",
            "label": "Feature failed",
            "allowedProperties": [
              "result_code"
            ],
            "expectedOrigin": "app_reported"
          },
          "analyticsHandle": "crust.analytics.feature_failed"
        }
      ],
      "confirm": true
    }
  }
}

POST to https://heycrust.com/api/mcp with Content-Type: application/json and Authorization: Bearer <YOUR_CREDENTIAL>. Check JSON-RPC errors and result.isError, then parse JSON text in result.content.

Result and interpretation

Requires explicit confirm=true. Review get_instrumentation_plan and edit its 5–10 events first. The example uses fictional identifiers and must not be submitted as a synthetic setup test. Registration is an owner-only write: one transaction creates or reuses exactly matching owned current event revisions, pins those versions and creates one default setup/value funnel. Repeating identical input returns the same registered plan; a different plan or conflicting existing definition rejects without partial catalog/funnel writes. No deployment coverage is declared, no events are fabricated and no automation is activated. After registration, use the versioned catalog/funnel editors for changes.

Delivery boundaries

Download the Node ESM package. The SQLite spool requires Node 22.13+ or 24+ and a persistent local disk. Ephemeral Render/serverless disk does not retain queued work across replacements or deployments. Existing durable PostgreSQL/Prisma outboxes should use the package's guarded delivery seam and preserve their shared lifecycle fences, redaction cancellation and retained reinstall epochs.

Clear an optional analyticsHandle to null (or omit it) for Crust-only tracking. Generated Shopify maps exclude those events; existing registered handles and pinned definitions are preserved.

Shopify mirroring is opt-in per explicit crust.analytics.* monitoring handle. Keep handles absent from pricing meters; no value, billing, contact or identity attributes are permitted. Shopify uses client credentials and the 2026-10 App Events endpoint. Exact 202 plus success=true confirms transport acceptance, not Analytics processing. Shopify custom-event deduplication lasts 24 hours; never claim permanent exactly-once delivery. Analytics developer preview access and accepted declarations are separate. No generic App Events read/backfill API is assumed. The SDK defaults to32 bounded attempts with5-second polling and exponential backoff capped at1hour; a repeated1hour outage remains queued and recovery is retried automatically. The next retry may take up to the backoff cap; custom lower attempt limits can exhaust earlier. Shopify reference.

Recognized PostgreSQL timeouts return status: unavailable with reasons: [query_timeout]; do not interpret missing totals as zero.