@centrali-io/centrali-mcp 6.8.0 → 6.9.0

package/dist/index.js

@@ -26,6 +26,7 @@ const describe_js_1 = require("./tools/describe.js");
 const auth_providers_js_1 = require("./tools/auth-providers.js");
 const service_accounts_js_1 = require("./tools/service-accounts.js");
 const webhook_subscriptions_js_1 = require("./tools/webhook-subscriptions.js");
+const events_js_1 = require("./tools/events.js");
 const structures_js_2 = require("./resources/structures.js");
 function getRequiredEnv(name) {
     const value = process.env[name];
@@ -84,6 +85,7 @@ function main() {
             isServiceAccount: true,
         });
         (0, webhook_subscriptions_js_1.registerWebhookSubscriptionTools)(server, sdk);
+        (0, events_js_1.registerEventTools)(server, sdk, baseUrl, workspaceId);
         (0, describe_js_1.registerDescribeTools)(server);
         // Register resources
         (0, structures_js_2.registerCollectionResources)(server, sdk);

package/dist/tools/describe.js

@@ -195,6 +195,17 @@ function registerDescribeTools(server) {
                                     "cancel_webhook_delivery",
                                 ],
                             },
+                            event_log: {
+                                summary: "Read, replay, trace, and subscribe to the Event Log — the Tier 1 projection unioning inbound HTTP-trigger arrivals, record changes, and outbound webhook deliveries into one chronological, queryable stream. Follow a single event end-to-end across the inbound → function → outbound chain via its correlation id.",
+                                describeWith: "describe_events",
+                                tools: [
+                                    "list_events",
+                                    "get_event",
+                                    "replay_event",
+                                    "trace_correlation",
+                                    "subscribe_to_events",
+                                ],
+                            },
                             service_accounts: {
                                 summary: "Machine identities for backend-to-backend API access. Create service accounts with client_credentials OAuth2 flow, manage roles and groups for fine-grained permissions, and introspect access with permission scanning.",
                                 describeWith: "describe_service_accounts",
@@ -1469,6 +1480,67 @@ function registerDescribeTools(server) {
             ],
         });
     }));
+    // ── Event Log ──────────────────────────────────────────────────────
+    (0, _register_js_1.registerTool)(server, "describe_events", "Get the schema reference for the Centrali Event Log. Explains the Tier 1 projection, queryable fields, the event row shape, correlation-id lineage, and what is replayable.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        return ({
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        domain: "Event Log",
+                        description: "The Tier 1 event projection unions three immutable change logs into one chronological, queryable stream: inbound HTTP-trigger arrivals (inbound_events), record changes (record_change_log), and outbound webhook deliveries (webhook_deliveries). A correlation id stamped at chain entry ties an inbound arrival to the function runs it spawned and the outbound deliveries they produced — follow the whole chain with trace_correlation.",
+                        source_tables: {
+                            inbound_events: "Inbound HTTP-trigger arrivals. eventType 'inbound.http_trigger'. Replayable (re-dispatch).",
+                            record_change_log: "Record create/update/delete. eventType 'record.*'. Immutable history — not replayable.",
+                            webhook_deliveries: "Outbound webhook dispatch attempts. eventType 'outbound.webhook_delivery'. Replayable (re-deliver).",
+                        },
+                        event_row_shape: {
+                            eventType: "string — e.g. 'inbound.http_trigger', 'record.created', 'outbound.webhook_delivery'",
+                            sourceTable: "'inbound_events' | 'record_change_log' | 'webhook_deliveries'",
+                            sourceId: "string — the event's id within its source table; pair with sourceTable as the natural key for get_event / replay_event",
+                            correlationId: "string | null — the chain key; pass to trace_correlation for the ordered lineage",
+                            timestamp: "ISO 8601 datetime",
+                            clockTier: "0 (host-clock inbound) | 1 (DB-clock record/delivery)",
+                            note: "list_events returns metadata only (no payload). Fetch the decrypted payload, signature result, dispatch status, request headers, and nested function runs with get_event.",
+                        },
+                        queryable_fields: ["eventType", "sourceTable", "sourceId", "correlationId", "timestamp", "triggerId"],
+                        tools: {
+                            list_events: {
+                                description: "Query the projection, newest first. All filters optional; AND-combined.",
+                                optional_params: ["correlationId", "sourceTable", "eventType", "triggerId", "since", "until", "limit"],
+                                note: "triggerId scopes to one integration and only matches inbound_events rows. limit defaults to 50, caps at 200.",
+                                example: { sourceTable: "inbound_events", since: "2026-06-01T00:00:00Z", limit: 20 },
+                            },
+                            get_event: {
+                                description: "Full detail for one event by its (sourceTable, sourceId) natural key — decrypted payload plus inbound metadata and nested function runs.",
+                                required_params: ["sourceTable", "sourceId"],
+                            },
+                            replay_event: {
+                                description: "Re-dispatch an inbound arrival or re-deliver an outbound webhook. record_change_log events are not replayable.",
+                                required_params: ["sourceTable", "sourceId"],
+                            },
+                            trace_correlation: {
+                                description: "The full lineage chain for a correlation id, oldest first — inbound arrival → record changes → outbound deliveries.",
+                                required_params: ["correlationId"],
+                            },
+                            subscribe_to_events: {
+                                description: "Create an outbound webhook subscription so an external URL receives a signed payload on each matching event. Returns the whsec_ signing secret once. Manage it afterwards with the webhook tools.",
+                                required_params: ["name", "url", "eventTypes"],
+                                optional_params: ["recordSlugs", "active"],
+                                note: "Deliverable eventTypes today are record events (record_created, record_updated, record_deleted, records_bulk_created) — the outbound webhook primitive's current capability.",
+                            },
+                        },
+                        tips: [
+                            "Start from a correlationId on any row and call trace_correlation to see the whole inbound → function → outbound story in order.",
+                            "list_events is metadata-only by design (inbound payloads are encrypted at rest); use get_event for the decrypted payload and signature result.",
+                            "Pair list_events(sourceTable='webhook_deliveries') with replay_event to re-drive failed outbound deliveries after fixing the receiver.",
+                            "Use triggerId to keep a query scoped to a single integration's inbound traffic.",
+                        ],
+                    }, null, 2),
+                },
+            ],
+        });
+    }));
     // ── Insights ───────────────────────────────────────────────────────
     (0, _register_js_1.registerTool)(server, "describe_insights", "Get the schema reference for Centrali anomaly insights. Explains anomaly detection, severity levels, and the acknowledge/dismiss workflow.", {}, () => __awaiter(this, void 0, void 0, function* () {
         return ({

package/dist/tools/events.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+export declare function registerEventTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string): void;

package/dist/tools/events.js

@@ -0,0 +1,257 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerEventTools = registerEventTools;
+const axios_1 = __importDefault(require("axios"));
+const zod_1 = require("zod");
+const _register_js_1 = require("./_register.js");
+/**
+ * Event Log MCP tools (CEN-1302) — make an agent a first-class consumer of the
+ * Tier 1 event projection (CEN-1298). The projection unions three immutable
+ * change logs into one chronological, queryable stream:
+ *
+ *   - `inbound_events`     — inbound HTTP-trigger arrivals (`inbound.http_trigger`)
+ *   - `record_change_log`  — record create/update/delete (`record.*`)
+ *   - `webhook_deliveries` — outbound webhook dispatch state (`outbound.webhook_delivery`)
+ *
+ * These tools wrap the data-service Event Log REST surface directly (no SDK
+ * manager exists for it yet), mirroring the direct-axios pattern in compute.ts.
+ */
+/** The three source tables the Tier 1 projection unions. */
+const SOURCE_TABLE_VALUES = [
+    "inbound_events",
+    "record_change_log",
+    "webhook_deliveries",
+];
+/** Record events a webhook subscription can deliver (the only events the
+ *  outbound webhook primitive supports today — inbound/outbound projection
+ *  rows are not yet deliverable; that arrives with the SSE broadening). */
+const SUBSCRIBABLE_EVENT_VALUES = [
+    "record_created",
+    "record_updated",
+    "record_deleted",
+    "records_bulk_created",
+];
+/** Ensure the SDK has a valid bearer token (see compute.ts). */
+function ensureToken(sdk) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const token = sdk.getToken();
+        if (token)
+            return token;
+        try {
+            yield sdk.functions.list({ limit: 1 });
+        }
+        catch (_a) {
+            /* token refresh side effect */
+        }
+        return sdk.getToken();
+    });
+}
+/** Build the data-service API base for a workspace, honouring the `api.`
+ *  gateway-subdomain convention used across the MCP tools (see compute.ts). */
+function dataApiBase(centraliUrl, workspaceId) {
+    const url = new URL(centraliUrl);
+    const hostname = url.hostname.startsWith("api.") ? url.hostname : `api.${url.hostname}`;
+    return `${url.protocol}//${hostname}/data/workspace/${workspaceId}/api/v1`;
+}
+function registerEventTools(server, sdk, centraliUrl, workspaceId) {
+    // ── list_events ────────────────────────────────────────────────────
+    (0, _register_js_1.registerTool)(server, "list_events", "Query the workspace Event Log — the Tier 1 projection that unions inbound HTTP-trigger arrivals, record changes, and outbound webhook deliveries into one chronological stream. Returns metadata-only rows (eventType, sourceTable, sourceId, correlationId, timestamp), newest first. Fetch a single event's full payload with get_event, or follow a chain with trace_correlation.", {
+        correlationId: zod_1.z
+            .string()
+            .optional()
+            .describe("Only events sharing this correlation id (the chain key stamped at chain entry). Use trace_correlation for the ordered lineage."),
+        sourceTable: zod_1.z
+            .enum(SOURCE_TABLE_VALUES)
+            .optional()
+            .describe("Restrict to one source: inbound_events (HTTP trigger fires), record_change_log (record changes), or webhook_deliveries (outbound deliveries)."),
+        eventType: zod_1.z
+            .string()
+            .optional()
+            .describe("Exact event type, e.g. 'inbound.http_trigger', 'record.created', 'outbound.webhook_delivery'."),
+        triggerId: zod_1.z
+            .string()
+            .optional()
+            .describe("Scope to one integration — the HTTP trigger UUID an inbound arrival came through. Only matches inbound_events rows."),
+        since: zod_1.z
+            .string()
+            .optional()
+            .describe("ISO 8601 datetime — include events at or after this time."),
+        until: zod_1.z
+            .string()
+            .optional()
+            .describe("ISO 8601 datetime — include events at or before this time."),
+        limit: zod_1.z
+            .number()
+            .optional()
+            .describe("Max rows to return (default 50, max 200)."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ correlationId, sourceTable, eventType, triggerId, since, until, limit }) {
+        try {
+            const token = yield ensureToken(sdk);
+            const conditions = [];
+            if (correlationId)
+                conditions.push({ correlationId: { eq: correlationId } });
+            if (sourceTable)
+                conditions.push({ sourceTable: { eq: sourceTable } });
+            if (eventType)
+                conditions.push({ eventType: { eq: eventType } });
+            if (triggerId)
+                conditions.push({ triggerId: { eq: triggerId } });
+            if (since)
+                conditions.push({ timestamp: { gte: since } });
+            if (until)
+                conditions.push({ timestamp: { lte: until } });
+            const definition = {
+                resource: "event-log",
+                sort: [{ field: "timestamp", direction: "desc" }],
+                page: { limit: limit !== null && limit !== void 0 ? limit : 50 },
+            };
+            if (conditions.length === 1)
+                definition.where = conditions[0];
+            else if (conditions.length > 1)
+                definition.where = { and: conditions };
+            const result = yield axios_1.default.post(`${dataApiBase(centraliUrl, workspaceId)}/event-log/query`, definition, {
+                headers: token ? { Authorization: `Bearer ${token}` } : {},
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, "querying the event log") }],
+                isError: true,
+            };
+        }
+    }));
+    // ── get_event ──────────────────────────────────────────────────────
+    (0, _register_js_1.registerTool)(server, "get_event", "Get a single Event Log event by its (sourceTable, sourceId) natural key, with the stored payload decrypted on read. Inbound arrivals also return signature result, dispatch status, request headers, and any replay source; the response nests the function runs sharing the event's correlationId.", {
+        sourceTable: zod_1.z
+            .enum(SOURCE_TABLE_VALUES)
+            .describe("The source table the event lives in (from a list_events row)."),
+        sourceId: zod_1.z.string().describe("The event's id within its source table."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ sourceTable, sourceId }) {
+        try {
+            const token = yield ensureToken(sdk);
+            const result = yield axios_1.default.get(`${dataApiBase(centraliUrl, workspaceId)}/event-log/${encodeURIComponent(sourceTable)}/${encodeURIComponent(sourceId)}`, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `getting event '${sourceTable}/${sourceId}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    // ── replay_event ───────────────────────────────────────────────────
+    (0, _register_js_1.registerTool)(server, "replay_event", "Re-run an event. For an inbound_events row, re-dispatches the buffered inbound arrival through its original trigger (a new event is recorded, linked via replayedFrom). For a webhook_deliveries row, re-delivers the outbound webhook, preserving the original payload and signature. record_change_log events are immutable history and cannot be replayed.", {
+        sourceTable: zod_1.z
+            .enum(SOURCE_TABLE_VALUES)
+            .describe("The source table of the event to replay (from a list_events / get_event row)."),
+        sourceId: zod_1.z.string().describe("The event's id within its source table."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ sourceTable, sourceId }) {
+        if (sourceTable === "record_change_log") {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "record_change_log events are immutable history and cannot be replayed. Only inbound_events (re-dispatch) and webhook_deliveries (re-deliver) are replayable.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const token = yield ensureToken(sdk);
+            const base = dataApiBase(centraliUrl, workspaceId);
+            const path = sourceTable === "inbound_events"
+                ? `${base}/inbound-events/${encodeURIComponent(sourceId)}/replay`
+                : `${base}/webhook-subscriptions/deliveries/${encodeURIComponent(sourceId)}/retry`;
+            const result = yield axios_1.default.post(path, {}, {
+                headers: token ? { Authorization: `Bearer ${token}` } : {},
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `replaying event '${sourceTable}/${sourceId}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    // ── trace_correlation ──────────────────────────────────────────────
+    (0, _register_js_1.registerTool)(server, "trace_correlation", "Return the full lineage chain for a correlation id — every Tier 1 event (inbound arrival → record changes → outbound deliveries) that shares it, oldest first. The canonical way to follow an event end-to-end across the inbound → function → outbound flow.", {
+        correlationId: zod_1.z.string().describe("The correlation id shared across the event chain (from any list_events / get_event row)."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ correlationId }) {
+        try {
+            const token = yield ensureToken(sdk);
+            const result = yield axios_1.default.get(`${dataApiBase(centraliUrl, workspaceId)}/event-lineage`, {
+                params: { correlationId },
+                headers: token ? { Authorization: `Bearer ${token}` } : {},
+            });
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `tracing correlation '${correlationId}'`) }],
+                isError: true,
+            };
+        }
+    }));
+    // ── subscribe_to_events ────────────────────────────────────────────
+    // Event-namespace convenience over the outbound webhook primitive: lets an
+    // agent set up its own production reactive path without first discovering the
+    // separate webhook-subscriptions tool family. Backed by the same primitive,
+    // so manage the subscription afterwards with the webhook tools
+    // (update/rotate/delete_webhook_subscription, list_webhook_deliveries, ...).
+    (0, _register_js_1.registerTool)(server, "subscribe_to_events", "Subscribe an external URL to a live event stream by creating an outbound webhook subscription. Centrali POSTs a signed payload (HMAC-SHA256 under a whsec_ secret) on each matching event. The response includes the signing secret — capture it immediately, it is not returned on later reads. Today's deliverable events are record events; manage or inspect the subscription afterwards with the webhook tools (get/update/delete_webhook_subscription, list_webhook_deliveries, retry_webhook_delivery).", {
+        name: zod_1.z.string().describe("Display name for the subscription."),
+        url: zod_1.z.string().describe("HTTPS URL that will receive POSTed event payloads."),
+        eventTypes: zod_1.z
+            .array(zod_1.z.enum(SUBSCRIBABLE_EVENT_VALUES))
+            .describe("Events to deliver: record_created, record_updated, record_deleted, records_bulk_created."),
+        recordSlugs: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Optional collection slugs to scope the subscription to. Omit for all collections."),
+        active: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Whether the subscription is active on creation. Defaults to true."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ name, url, eventTypes, recordSlugs, active }) {
+        try {
+            const input = { name, url, events: eventTypes };
+            if (recordSlugs !== undefined)
+                input.recordSlugs = recordSlugs;
+            if (active !== undefined)
+                input.active = active;
+            const result = yield sdk.webhookSubscriptions.create(input);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `subscribing to events as '${name}'`) }],
+                isError: true,
+            };
+        }
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "6.8.0",
+  "version": "6.9.0",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",
@@ -25,7 +25,7 @@
   "author": "Blueinit",
   "license": "ISC",
   "dependencies": {
-    "@centrali-io/centrali-sdk": "^6.8.0",
+    "@centrali-io/centrali-sdk": "^6.9.0",
     "@modelcontextprotocol/sdk": "^1.28.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -16,6 +16,7 @@ import { registerDescribeTools } from "./tools/describe.js";
 import { registerAuthProviderTools } from "./tools/auth-providers.js";
 import { registerServiceAccountTools } from "./tools/service-accounts.js";
 import { registerWebhookSubscriptionTools } from "./tools/webhook-subscriptions.js";
+import { registerEventTools } from "./tools/events.js";
 import { registerStructureResources, registerCollectionResources } from "./resources/structures.js";
 
 function getRequiredEnv(name: string): string {
@@ -81,6 +82,7 @@ async function main() {
     isServiceAccount: true,
   });
   registerWebhookSubscriptionTools(server, sdk);
+  registerEventTools(server, sdk, baseUrl, workspaceId);
   registerDescribeTools(server);
 
   // Register resources

package/src/tools/describe.ts

@@ -202,6 +202,18 @@ export function registerDescribeTools(server: McpServer) {
                     "cancel_webhook_delivery",
                   ],
                 },
+                event_log: {
+                  summary:
+                    "Read, replay, trace, and subscribe to the Event Log — the Tier 1 projection unioning inbound HTTP-trigger arrivals, record changes, and outbound webhook deliveries into one chronological, queryable stream. Follow a single event end-to-end across the inbound → function → outbound chain via its correlation id.",
+                  describeWith: "describe_events",
+                  tools: [
+                    "list_events",
+                    "get_event",
+                    "replay_event",
+                    "trace_correlation",
+                    "subscribe_to_events",
+                  ],
+                },
                 service_accounts: {
                   summary:
                     "Machine identities for backend-to-backend API access. Create service accounts with client_credentials OAuth2 flow, manage roles and groups for fine-grained permissions, and introspect access with permission scanning.",
@@ -1606,9 +1618,80 @@ export function registerDescribeTools(server: McpServer) {
     })
   );
 
+  // ── Event Log ──────────────────────────────────────────────────────
+
+  registerTool<any>(server,
+    "describe_events",
+    "Get the schema reference for the Centrali Event Log. Explains the Tier 1 projection, queryable fields, the event row shape, correlation-id lineage, and what is replayable.",
+    {},
+    async () => ({
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              domain: "Event Log",
+              description:
+                "The Tier 1 event projection unions three immutable change logs into one chronological, queryable stream: inbound HTTP-trigger arrivals (inbound_events), record changes (record_change_log), and outbound webhook deliveries (webhook_deliveries). A correlation id stamped at chain entry ties an inbound arrival to the function runs it spawned and the outbound deliveries they produced — follow the whole chain with trace_correlation.",
+              source_tables: {
+                inbound_events: "Inbound HTTP-trigger arrivals. eventType 'inbound.http_trigger'. Replayable (re-dispatch).",
+                record_change_log: "Record create/update/delete. eventType 'record.*'. Immutable history — not replayable.",
+                webhook_deliveries: "Outbound webhook dispatch attempts. eventType 'outbound.webhook_delivery'. Replayable (re-deliver).",
+              },
+              event_row_shape: {
+                eventType: "string — e.g. 'inbound.http_trigger', 'record.created', 'outbound.webhook_delivery'",
+                sourceTable: "'inbound_events' | 'record_change_log' | 'webhook_deliveries'",
+                sourceId: "string — the event's id within its source table; pair with sourceTable as the natural key for get_event / replay_event",
+                correlationId: "string | null — the chain key; pass to trace_correlation for the ordered lineage",
+                timestamp: "ISO 8601 datetime",
+                clockTier: "0 (host-clock inbound) | 1 (DB-clock record/delivery)",
+                note: "list_events returns metadata only (no payload). Fetch the decrypted payload, signature result, dispatch status, request headers, and nested function runs with get_event.",
+              },
+              queryable_fields: ["eventType", "sourceTable", "sourceId", "correlationId", "timestamp", "triggerId"],
+              tools: {
+                list_events: {
+                  description: "Query the projection, newest first. All filters optional; AND-combined.",
+                  optional_params: ["correlationId", "sourceTable", "eventType", "triggerId", "since", "until", "limit"],
+                  note: "triggerId scopes to one integration and only matches inbound_events rows. limit defaults to 50, caps at 200.",
+                  example: { sourceTable: "inbound_events", since: "2026-06-01T00:00:00Z", limit: 20 },
+                },
+                get_event: {
+                  description: "Full detail for one event by its (sourceTable, sourceId) natural key — decrypted payload plus inbound metadata and nested function runs.",
+                  required_params: ["sourceTable", "sourceId"],
+                },
+                replay_event: {
+                  description: "Re-dispatch an inbound arrival or re-deliver an outbound webhook. record_change_log events are not replayable.",
+                  required_params: ["sourceTable", "sourceId"],
+                },
+                trace_correlation: {
+                  description: "The full lineage chain for a correlation id, oldest first — inbound arrival → record changes → outbound deliveries.",
+                  required_params: ["correlationId"],
+                },
+                subscribe_to_events: {
+                  description: "Create an outbound webhook subscription so an external URL receives a signed payload on each matching event. Returns the whsec_ signing secret once. Manage it afterwards with the webhook tools.",
+                  required_params: ["name", "url", "eventTypes"],
+                  optional_params: ["recordSlugs", "active"],
+                  note: "Deliverable eventTypes today are record events (record_created, record_updated, record_deleted, records_bulk_created) — the outbound webhook primitive's current capability.",
+                },
+              },
+              tips: [
+                "Start from a correlationId on any row and call trace_correlation to see the whole inbound → function → outbound story in order.",
+                "list_events is metadata-only by design (inbound payloads are encrypted at rest); use get_event for the decrypted payload and signature result.",
+                "Pair list_events(sourceTable='webhook_deliveries') with replay_event to re-drive failed outbound deliveries after fixing the receiver.",
+                "Use triggerId to keep a query scoped to a single integration's inbound traffic.",
+              ],
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    })
+  );
+
   // ── Insights ───────────────────────────────────────────────────────
 
-  registerTool<any>(server, 
+  registerTool<any>(server,
     "describe_insights",
     "Get the schema reference for Centrali anomaly insights. Explains anomaly detection, severity levels, and the acknowledge/dismiss workflow.",
     {},

package/src/tools/events.ts

@@ -0,0 +1,293 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import axios from "axios";
+import { z } from "zod";
+import { registerTool, formatError } from "./_register.js";
+
+/**
+ * Event Log MCP tools (CEN-1302) — make an agent a first-class consumer of the
+ * Tier 1 event projection (CEN-1298). The projection unions three immutable
+ * change logs into one chronological, queryable stream:
+ *
+ *   - `inbound_events`     — inbound HTTP-trigger arrivals (`inbound.http_trigger`)
+ *   - `record_change_log`  — record create/update/delete (`record.*`)
+ *   - `webhook_deliveries` — outbound webhook dispatch state (`outbound.webhook_delivery`)
+ *
+ * These tools wrap the data-service Event Log REST surface directly (no SDK
+ * manager exists for it yet), mirroring the direct-axios pattern in compute.ts.
+ */
+
+/** The three source tables the Tier 1 projection unions. */
+const SOURCE_TABLE_VALUES = [
+  "inbound_events",
+  "record_change_log",
+  "webhook_deliveries",
+] as const;
+type SourceTableValue = (typeof SOURCE_TABLE_VALUES)[number];
+
+/** Record events a webhook subscription can deliver (the only events the
+ *  outbound webhook primitive supports today — inbound/outbound projection
+ *  rows are not yet deliverable; that arrives with the SSE broadening). */
+const SUBSCRIBABLE_EVENT_VALUES = [
+  "record_created",
+  "record_updated",
+  "record_deleted",
+  "records_bulk_created",
+] as const;
+type SubscribableEventValue = (typeof SUBSCRIBABLE_EVENT_VALUES)[number];
+
+/** Ensure the SDK has a valid bearer token (see compute.ts). */
+async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
+  const token = sdk.getToken();
+  if (token) return token;
+  try {
+    await sdk.functions.list({ limit: 1 });
+  } catch {
+    /* token refresh side effect */
+  }
+  return sdk.getToken();
+}
+
+/** Build the data-service API base for a workspace, honouring the `api.`
+ *  gateway-subdomain convention used across the MCP tools (see compute.ts). */
+function dataApiBase(centraliUrl: string, workspaceId: string): string {
+  const url = new URL(centraliUrl);
+  const hostname = url.hostname.startsWith("api.") ? url.hostname : `api.${url.hostname}`;
+  return `${url.protocol}//${hostname}/data/workspace/${workspaceId}/api/v1`;
+}
+
+export function registerEventTools(
+  server: McpServer,
+  sdk: CentraliSDK,
+  centraliUrl: string,
+  workspaceId: string
+) {
+  // ── list_events ────────────────────────────────────────────────────
+  registerTool<{
+    correlationId?: string;
+    sourceTable?: SourceTableValue;
+    eventType?: string;
+    triggerId?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+  }>(
+    server,
+    "list_events",
+    "Query the workspace Event Log — the Tier 1 projection that unions inbound HTTP-trigger arrivals, record changes, and outbound webhook deliveries into one chronological stream. Returns metadata-only rows (eventType, sourceTable, sourceId, correlationId, timestamp), newest first. Fetch a single event's full payload with get_event, or follow a chain with trace_correlation.",
+    {
+      correlationId: z
+        .string()
+        .optional()
+        .describe("Only events sharing this correlation id (the chain key stamped at chain entry). Use trace_correlation for the ordered lineage."),
+      sourceTable: z
+        .enum(SOURCE_TABLE_VALUES)
+        .optional()
+        .describe("Restrict to one source: inbound_events (HTTP trigger fires), record_change_log (record changes), or webhook_deliveries (outbound deliveries)."),
+      eventType: z
+        .string()
+        .optional()
+        .describe("Exact event type, e.g. 'inbound.http_trigger', 'record.created', 'outbound.webhook_delivery'."),
+      triggerId: z
+        .string()
+        .optional()
+        .describe("Scope to one integration — the HTTP trigger UUID an inbound arrival came through. Only matches inbound_events rows."),
+      since: z
+        .string()
+        .optional()
+        .describe("ISO 8601 datetime — include events at or after this time."),
+      until: z
+        .string()
+        .optional()
+        .describe("ISO 8601 datetime — include events at or before this time."),
+      limit: z
+        .number()
+        .optional()
+        .describe("Max rows to return (default 50, max 200)."),
+    },
+    async ({ correlationId, sourceTable, eventType, triggerId, since, until, limit }) => {
+      try {
+        const token = await ensureToken(sdk);
+        const conditions: Record<string, unknown>[] = [];
+        if (correlationId) conditions.push({ correlationId: { eq: correlationId } });
+        if (sourceTable) conditions.push({ sourceTable: { eq: sourceTable } });
+        if (eventType) conditions.push({ eventType: { eq: eventType } });
+        if (triggerId) conditions.push({ triggerId: { eq: triggerId } });
+        if (since) conditions.push({ timestamp: { gte: since } });
+        if (until) conditions.push({ timestamp: { lte: until } });
+
+        const definition: Record<string, unknown> = {
+          resource: "event-log",
+          sort: [{ field: "timestamp", direction: "desc" }],
+          page: { limit: limit ?? 50 },
+        };
+        if (conditions.length === 1) definition.where = conditions[0];
+        else if (conditions.length > 1) definition.where = { and: conditions };
+
+        const result = await axios.post(`${dataApiBase(centraliUrl, workspaceId)}/event-log/query`, definition, {
+          headers: token ? { Authorization: `Bearer ${token}` } : {},
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, "querying the event log") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── get_event ──────────────────────────────────────────────────────
+  registerTool<{ sourceTable: SourceTableValue; sourceId: string }>(
+    server,
+    "get_event",
+    "Get a single Event Log event by its (sourceTable, sourceId) natural key, with the stored payload decrypted on read. Inbound arrivals also return signature result, dispatch status, request headers, and any replay source; the response nests the function runs sharing the event's correlationId.",
+    {
+      sourceTable: z
+        .enum(SOURCE_TABLE_VALUES)
+        .describe("The source table the event lives in (from a list_events row)."),
+      sourceId: z.string().describe("The event's id within its source table."),
+    },
+    async ({ sourceTable, sourceId }) => {
+      try {
+        const token = await ensureToken(sdk);
+        const result = await axios.get(
+          `${dataApiBase(centraliUrl, workspaceId)}/event-log/${encodeURIComponent(sourceTable)}/${encodeURIComponent(sourceId)}`,
+          { headers: token ? { Authorization: `Bearer ${token}` } : {} }
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting event '${sourceTable}/${sourceId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── replay_event ───────────────────────────────────────────────────
+  registerTool<{ sourceTable: SourceTableValue; sourceId: string }>(
+    server,
+    "replay_event",
+    "Re-run an event. For an inbound_events row, re-dispatches the buffered inbound arrival through its original trigger (a new event is recorded, linked via replayedFrom). For a webhook_deliveries row, re-delivers the outbound webhook, preserving the original payload and signature. record_change_log events are immutable history and cannot be replayed.",
+    {
+      sourceTable: z
+        .enum(SOURCE_TABLE_VALUES)
+        .describe("The source table of the event to replay (from a list_events / get_event row)."),
+      sourceId: z.string().describe("The event's id within its source table."),
+    },
+    async ({ sourceTable, sourceId }) => {
+      if (sourceTable === "record_change_log") {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "record_change_log events are immutable history and cannot be replayed. Only inbound_events (re-dispatch) and webhook_deliveries (re-deliver) are replayable.",
+            },
+          ],
+          isError: true,
+        };
+      }
+      try {
+        const token = await ensureToken(sdk);
+        const base = dataApiBase(centraliUrl, workspaceId);
+        const path =
+          sourceTable === "inbound_events"
+            ? `${base}/inbound-events/${encodeURIComponent(sourceId)}/replay`
+            : `${base}/webhook-subscriptions/deliveries/${encodeURIComponent(sourceId)}/retry`;
+        const result = await axios.post(path, {}, {
+          headers: token ? { Authorization: `Bearer ${token}` } : {},
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `replaying event '${sourceTable}/${sourceId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── trace_correlation ──────────────────────────────────────────────
+  registerTool<{ correlationId: string }>(
+    server,
+    "trace_correlation",
+    "Return the full lineage chain for a correlation id — every Tier 1 event (inbound arrival → record changes → outbound deliveries) that shares it, oldest first. The canonical way to follow an event end-to-end across the inbound → function → outbound flow.",
+    {
+      correlationId: z.string().describe("The correlation id shared across the event chain (from any list_events / get_event row)."),
+    },
+    async ({ correlationId }) => {
+      try {
+        const token = await ensureToken(sdk);
+        const result = await axios.get(`${dataApiBase(centraliUrl, workspaceId)}/event-lineage`, {
+          params: { correlationId },
+          headers: token ? { Authorization: `Bearer ${token}` } : {},
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `tracing correlation '${correlationId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── subscribe_to_events ────────────────────────────────────────────
+  // Event-namespace convenience over the outbound webhook primitive: lets an
+  // agent set up its own production reactive path without first discovering the
+  // separate webhook-subscriptions tool family. Backed by the same primitive,
+  // so manage the subscription afterwards with the webhook tools
+  // (update/rotate/delete_webhook_subscription, list_webhook_deliveries, ...).
+  registerTool<{
+    name: string;
+    url: string;
+    eventTypes: SubscribableEventValue[];
+    recordSlugs?: string[];
+    active?: boolean;
+  }>(
+    server,
+    "subscribe_to_events",
+    "Subscribe an external URL to a live event stream by creating an outbound webhook subscription. Centrali POSTs a signed payload (HMAC-SHA256 under a whsec_ secret) on each matching event. The response includes the signing secret — capture it immediately, it is not returned on later reads. Today's deliverable events are record events; manage or inspect the subscription afterwards with the webhook tools (get/update/delete_webhook_subscription, list_webhook_deliveries, retry_webhook_delivery).",
+    {
+      name: z.string().describe("Display name for the subscription."),
+      url: z.string().describe("HTTPS URL that will receive POSTed event payloads."),
+      eventTypes: z
+        .array(z.enum(SUBSCRIBABLE_EVENT_VALUES))
+        .describe("Events to deliver: record_created, record_updated, record_deleted, records_bulk_created."),
+      recordSlugs: z
+        .array(z.string())
+        .optional()
+        .describe("Optional collection slugs to scope the subscription to. Omit for all collections."),
+      active: z
+        .boolean()
+        .optional()
+        .describe("Whether the subscription is active on creation. Defaults to true."),
+    },
+    async ({ name, url, eventTypes, recordSlugs, active }) => {
+      try {
+        const input: Record<string, unknown> = { name, url, events: eventTypes };
+        if (recordSlugs !== undefined) input.recordSlugs = recordSlugs;
+        if (active !== undefined) input.active = active;
+
+        const result = await sdk.webhookSubscriptions.create(input as any);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `subscribing to events as '${name}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+}