@centrali-io/centrali-mcp 5.2.0 → 5.4.0

package/src/tools/compute.ts

@@ -2,28 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
 import axios from "axios";
 import { z } from "zod";
-
-function formatError(error: unknown, context: string): string {
-  if (error && typeof error === 'object') {
-    const e = error as Record<string, any>;
-    if ('message' in e) {
-      let msg = `Error ${context}`;
-      if ('code' in e || 'status' in e) {
-        msg += `: [${e.code ?? e.status ?? 'ERROR'}] ${e.message}`;
-      } else {
-        msg += `: ${e.message}`;
-      }
-      if (Array.isArray(e.fieldErrors) && e.fieldErrors.length > 0) {
-        msg += '\nField errors:\n' + (e.fieldErrors as Array<{field: string; message: string}>)
-          .map(f => `  ${f.field}: ${f.message}`)
-          .join('\n');
-      }
-      return msg;
-    }
-  }
-  return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
-}
-
+import { registerTool, formatError } from "./_register.js";
 /**
  * Ensures the SDK has a valid token.
  */
@@ -37,7 +16,7 @@ async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
 }
 
 export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
-  server.tool(
+  registerTool<any>(server, 
     "list_functions",
     "List all compute functions in the workspace. Compute functions are JavaScript code blocks that run server-side.",
     {
@@ -72,7 +51,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "list_triggers",
     "List function triggers in the workspace. Triggers define how and when compute functions are executed (on-demand, event-driven, scheduled, http-trigger, endpoint).",
     {
@@ -112,7 +91,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "invoke_trigger",
     "Invoke an on-demand function trigger by ID. Optionally pass a custom payload. Returns the queued job ID.",
     {
@@ -156,7 +135,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_compute_job_status",
     "Check the status of an async compute job by job ID. Returns the current state (queued, running, completed, failed), the return value on success, or the failure reason on error. Use this after invoke_trigger to poll for results.",
     {
@@ -195,7 +174,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
 
   // ── Function CRUD tools ──────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "get_function",
     "Get a compute function by ID. Returns the full function definition including code.",
     {
@@ -223,7 +202,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_function",
     "Create a new compute function. Compute functions are JavaScript code blocks that run server-side.",
     {
@@ -270,7 +249,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_function",
     "Update an existing compute function by ID. Only include the fields you want to change.",
     {
@@ -320,7 +299,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_function",
     "Delete a compute function by ID.",
     {
@@ -351,7 +330,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "test_function",
     "Test execute code without saving it as a function. Useful for validating function code before creating or updating.",
     {
@@ -402,7 +381,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
 
   // ── Trigger CRUD tools ───────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "get_trigger",
     "Get a function trigger by ID. Returns full trigger details including execution type and metadata.",
     {
@@ -430,7 +409,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_trigger",
     "Create a new function trigger. Triggers define how and when a compute function is executed.",
     {
@@ -443,7 +422,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
       triggerMetadata: z
         .record(z.string(), z.any())
         .optional()
-        .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' }."),
+        .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' }. All trigger types accept params: a dictionary of static values passed to the function as triggerParams. Mark any secret with { value: 'plaintext', encrypt: true } to store it AES-256-GCM-encrypted at rest; it arrives as plaintext in triggerParams at execution time."),
       enabled: z.boolean().optional().describe("Whether the trigger is enabled (default: true)"),
     },
     async ({ name, functionId, executionType, description, triggerMetadata, enabled }) => {
@@ -473,7 +452,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_trigger",
     "Update an existing function trigger by ID. Only include the fields you want to change.",
     {
@@ -484,7 +463,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
       triggerMetadata: z
         .record(z.string(), z.any())
         .optional()
-        .describe("Updated type-specific configuration"),
+        .describe("Updated type-specific configuration. To rotate an encrypted params value, send params: { KEY: { value: 'new-plaintext', encrypt: true } }. To preserve an existing encrypted value without rotating, echo back the stored shape: params: { KEY: { value: '********', encrypted: true, keyVersion: N } } (use get_trigger to read the current shape). Omit a key from params entirely to remove it."),
     },
     async ({ triggerId, name, description, enabled, triggerMetadata }) => {
       try {
@@ -514,7 +493,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_trigger",
     "Delete a function trigger by ID.",
     {
@@ -545,7 +524,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "pause_trigger",
     "Pause a function trigger. Paused triggers will not fire until resumed.",
     {
@@ -573,7 +552,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "resume_trigger",
     "Resume a paused function trigger. The trigger will start firing again on matching events or schedules.",
     {
@@ -603,7 +582,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
 
   // ── Function Runs tools ────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "get_function_run",
     "Get a function run by ID. Returns status, output, error, timing, and execution metadata. Use this to check the result of an async trigger invocation or test execution.",
     {
@@ -631,7 +610,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "list_function_runs",
     "List function runs filtered by trigger ID or function ID. Returns execution history with status, timing, and errors. Useful for checking whether a trigger invocation completed and what it returned.",
     {
@@ -689,7 +668,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
 
   // ── Endpoint Trigger (Sync Execution) ─────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "invoke_endpoint",
     "Invoke a compute endpoint trigger by path. The function executes synchronously — Centrali waits for the function to complete and returns its output directly in the response. No polling needed. Max execution time: 30 seconds (configurable via triggerMetadata.timeoutMs, range 1–30s). If the function exceeds the timeout, returns 504. Endpoint triggers must be created first with executionType='endpoint'. Use this for real-time API responses; use invoke_trigger for long-running background work that doesn't need an immediate response.",
     {
@@ -744,7 +723,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
 
   // ── Allowed Domains tools ──────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_allowed_domains",
     "List all allowed domains for compute function HTTP requests. Functions can only call external APIs on domains in this allowlist.",
     {},
@@ -770,7 +749,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "add_allowed_domain",
     "Add a domain to the allowlist so compute functions can make HTTP requests to it. Supports wildcards (e.g., '*.example.com').",
     {
@@ -798,7 +777,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "remove_allowed_domain",
     "Remove a domain from the allowlist. Compute functions will no longer be able to call this domain.",
     {
@@ -831,7 +810,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
 
   // ── Scaffold (function + trigger in one step) ─────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "scaffold_function",
     "Create a compute function with boilerplate code and optionally wire a trigger — all in one step. The function uses the required `async function run()` pattern with `api.*` globals, `triggerParams`, and `executionParams` available.",
     {

package/src/tools/describe.ts

@@ -1,4 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTool } from "./_register.js";
 
 /**
  * Introspection tools that teach AI assistants the valid shapes, schemas,
@@ -11,7 +12,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export function registerDescribeTools(server: McpServer) {
   // ── Master describe tool ────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_centrali",
     "Get an overview of all Centrali platform capabilities and API domains. Call this first to understand what Centrali can do and which describe_* tool to call for deeper schema details.",
     {},
@@ -184,6 +185,23 @@ export function registerDescribeTools(server: McpServer) {
                     "refresh_auth_provider_jwks",
                   ],
                 },
+                webhooks: {
+                  summary:
+                    "Outbound webhook subscriptions for record events. Centrali POSTs a signed JSON payload to your URL on record_created, record_updated, record_deleted, and records_bulk_created. Each dispatch is signed with HMAC-SHA256 under the subscription's whsec_ secret and every attempt is recorded in the delivery log for inspection and replay.",
+                  describeWith: "describe_webhooks",
+                  tools: [
+                    "list_webhook_subscriptions",
+                    "get_webhook_subscription",
+                    "create_webhook_subscription",
+                    "update_webhook_subscription",
+                    "delete_webhook_subscription",
+                    "rotate_webhook_subscription_secret",
+                    "list_webhook_deliveries",
+                    "get_webhook_delivery",
+                    "retry_webhook_delivery",
+                    "cancel_webhook_delivery",
+                  ],
+                },
                 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.",
@@ -278,6 +296,7 @@ export function registerDescribeTools(server: McpServer) {
                   "Anomaly insights": { sdk: true, mcp: true, console: true },
                   "Search": { sdk: true, mcp: true, console: true },
                   "Function runs (execution history)": { sdk: true, mcp: true, console: true },
+                  "Outbound webhooks": { sdk: true, mcp: true, console: true, note: "SDK namespace (client.webhookSubscriptions) and MCP tools wrap the REST surface including delivery replay" },
                   "Service accounts & IAM": { sdk: false, mcp: true, console: true, note: "MCP tools for full SA lifecycle, roles, groups, and permission introspection" },
                   "File uploads": { sdk: true, mcp: false, console: true, note: "SDK-only — use client.uploadFile() in app code" },
                 },
@@ -502,7 +521,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Collections ────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_collections",
     "Get the schema reference for Centrali collections. Explains field types, property shapes, constraints, and how to define data models.",
     {},
@@ -602,7 +621,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Records ────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_records",
     "Get the schema reference for Centrali record operations. Explains filter syntax, sort syntax, pagination, expand, and the data. prefix convention.",
     {},
@@ -720,7 +739,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Search ─────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_search",
     "Get the schema reference for Centrali full-text search. Explains search behavior, filtering, and result format.",
     {},
@@ -762,7 +781,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Compute ────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_compute",
     "Get the schema reference for Centrali compute functions and triggers. Explains function types, trigger execution modes, and invocation patterns.",
     {},
@@ -979,10 +998,12 @@ export function registerDescribeTools(server: McpServer) {
                 utilities: "api.uuid, api.formatDate, api.chunk, api.merge, api.math, api.evaluate, api.renderTemplate, api.log, api.logError, api.toCSV, api.toJSON",
               },
               secrets: {
-                description: "Compute functions have NO built-in environment variables or secrets field.",
-                recommended: "Wrap the function in an orchestration and use encrypted params on the compute step. Encrypted params are stored with AES-256-GCM at rest, decrypted at execution time, and arrive in triggerParams.",
-                alternative: "Pass secrets in the trigger invocation payload via executionParams. This works but means the calling app is the courier for the secret.",
-                encrypted_params_flow: "Create orchestration → add compute step with encryptedParams: { API_KEY: { value: 'secret', encrypt: true } } → at execution, API_KEY arrives decrypted in triggerParams.API_KEY",
+                description: "Set encrypted params directly on any trigger's triggerMetadata.params. Shape at create/update: { paramName: { value: 'plaintext', encrypt: true } }. Stored AES-256-GCM at rest, decrypted at execution time, arrive in triggerParams[paramName] as plaintext.",
+                works_on: "event-driven, scheduled, http-trigger, endpoint, and on-demand triggers — plus orchestration compute steps (same mechanism, scoped to a step via encryptedParams).",
+                example_event_driven: "create_trigger({ executionType: 'event-driven', triggerMetadata: { eventType: 'record_created', recordSlug: 'stripe-events', params: { SLACK_WEBHOOK_URL: { value: 'https://hooks.slack.com/...', encrypt: true } } } }) — function accesses triggerParams.SLACK_WEBHOOK_URL as plaintext.",
+                update_semantics: "To rotate a value: send { KEY: { value: 'new-plaintext', encrypt: true } }. To preserve an existing encrypted value without rotating: send { KEY: { value: '********', encrypted: true, keyVersion: N } } (use get_trigger to see the stored shape).",
+                alternative: "Pass secrets in the invocation payload via executionParams — only when the caller is already holding the secret and you don't want to store it on the trigger.",
+                orchestration_note: "Orchestration compute steps use encryptedParams with the same { value, encrypt: true } shape — equivalent mechanism, just scoped to a single step.",
               },
               async_execution: {
                 description: "Trigger invocation is ASYNCHRONOUS. invoke_trigger returns a job ID, not the execution result. There are two ways to get the result.",
@@ -1020,7 +1041,7 @@ export function registerDescribeTools(server: McpServer) {
                 "Use get_function_run or list_function_runs to check execution results after invoking a trigger",
                 "Use api.crypto.signJwt() for GitHub App, Google Cloud, or Azure AD authentication flows",
                 "Before creating functions that call external APIs, add the target domains with add_allowed_domain",
-                "For secrets (API keys, credentials), use orchestration encrypted params — see the 'secrets' section above",
+                "For secrets (API keys, credentials), set encrypted params on the trigger (triggerMetadata.params with { value, encrypt: true }) — see the 'secrets' section above",
               ],
             },
             null,
@@ -1033,7 +1054,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Smart Queries ──────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_smart_queries",
     "Get the schema reference for Centrali smart queries. Explains parameterized queries, variable substitution, and execution.",
     {},
@@ -1120,7 +1141,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Orchestrations ─────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_orchestrations",
     "Get the schema reference for Centrali orchestrations. Explains multi-step workflows, runs, steps, and execution model.",
     {},
@@ -1298,9 +1319,167 @@ export function registerDescribeTools(server: McpServer) {
     })
   );
 
+  // ── Webhooks ───────────────────────────────────────────────────────
+
+  registerTool<any>(server, 
+    "describe_webhooks",
+    "Get the schema reference for Centrali outbound webhooks. Explains subscription shape, supported event types, signature verification, retry behavior, and delivery-status lifecycle.",
+    {},
+    async () => ({
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(
+            {
+              domain: "Webhook Subscriptions",
+              description:
+                "Centrali emits record lifecycle events to external URLs. A subscription binds an HTTPS URL to one or more event types (optionally scoped to a subset of collections). Every dispatch is signed with HMAC-SHA256 and recorded in the delivery log — successes, retries, and terminal failures are all preserved.",
+              subscription_shape: {
+                id: "UUID",
+                name: "string",
+                url: "string — HTTPS URL that receives the POSTed payload",
+                events: "RecordEventType[] — subscribed events",
+                recordSlugs: "string[] — restrict to these collections. An empty array (or null on a read from an older row) means the subscription receives events for all collections. On update_webhook_subscription, pass [] to clear the restriction; omit the field to leave scope unchanged.",
+                active: "boolean — when false, dispatches are skipped",
+                secret: "string | undefined — `whsec_<base64url>` signing secret. Returned ONLY on create_webhook_subscription and rotate_webhook_subscription_secret; omitted on list/get.",
+                createdAt: "ISO 8601 datetime",
+                updatedAt: "ISO 8601 datetime",
+              },
+              event_types: {
+                record_created: "A new record was inserted",
+                record_updated: "An existing record was modified",
+                record_deleted: "A record was deleted (soft or hard)",
+                records_bulk_created: "Multiple records were inserted in a batch",
+              },
+              outbound_payload_shape: {
+                description:
+                  "Body shape Centrali POSTs to the subscribed URL. JSON-serialized; the raw bytes of this body are what gets HMAC-signed into X-Signature.",
+                event: "string — one of 'record_created' | 'record_updated' | 'record_deleted' | 'records_bulk_created'",
+                workspaceSlug: "string — the workspace that produced the event",
+                recordSlug: "string | undefined — the collection slug (absent on some bulk events)",
+                recordId: "string — the affected record's UUID (or the batch marker for bulk events)",
+                data: "object | undefined — the record snapshot for created/updated events (absent on deletes)",
+                timestamp: "string | undefined — ISO 8601 time the event was emitted",
+                createdBy: "string | undefined — actor user ID; populated on 'record_created'",
+                updatedBy: "string | undefined — actor user ID; populated on 'record_updated'",
+                deletedBy: "string | undefined — actor user ID; populated on 'record_deleted'",
+                note:
+                  "Actor fields are per-event: a create delivery carries createdBy, an update carries updatedBy, a delete carries deletedBy. They are the source of truth for 'who did this' — don't infer it from `data`.",
+              },
+              signature: {
+                header: "X-Signature",
+                algorithm: "HMAC-SHA256",
+                secret_format:
+                  "`whsec_<base64url>` — strip the `whsec_` prefix and base64url-decode the remainder to get the raw HMAC key bytes.",
+                signed_value:
+                  "The raw JSON request body (the outbound_payload_shape above, as bytes). Verify before parsing.",
+                output_encoding: "base64 (standard, not base64url)",
+                verify_example: [
+                  "// Node.js verification",
+                  "const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64url');",
+                  "const expected = crypto.createHmac('sha256', key).update(rawBody).digest('base64');",
+                  "// then timing-safe compare expected to req.headers['x-signature']",
+                ].join("\n"),
+              },
+              delivery_shape: {
+                id: "UUID",
+                webhookSubscriptionId: "UUID — parent subscription",
+                event: "string — the event name that triggered the dispatch",
+                status: "'success' | 'failed' | 'retrying'",
+                attemptCount: "number — number of HTTP attempts made against the target",
+                httpStatus: "number | null — the response status on the last attempt",
+                lastError: "string | null — last error message; 'Cancelled by user' for cancelled retries",
+                lastAttemptAt: "ISO 8601 datetime",
+                nextAttemptAt: "ISO 8601 datetime | null — scheduled time of the next retry (null when terminal)",
+                requestPayload:
+                  "object — only present on get_webhook_delivery (list_webhook_deliveries trims it for efficiency)",
+                responseBody:
+                  "string | null — first 1000 chars of the target response; only present on get_webhook_delivery",
+                replayedFrom: "UUID | null — delivery ID this row was replayed from; null for originals",
+                createdAt: "ISO 8601 datetime",
+                updatedAt: "ISO 8601 datetime",
+              },
+              retry_behavior: {
+                description:
+                  "Failed deliveries retry with fixed backoffs. After exhausting all attempts the row terminates as 'failed'. Circuit-open rejections count as spent attempts.",
+                max_attempts: 5,
+                terminal_statuses: ["success", "failed"],
+                replay:
+                  "retry_webhook_delivery inserts a new delivery row and preserves the original payload and signature. The retry counter restarts for the replay.",
+                cancel:
+                  "cancel_webhook_delivery only works on 'retrying' rows. It flips the row to 'failed' with lastError='Cancelled by user' and clears nextAttemptAt.",
+              },
+              crud_tools: {
+                create_webhook_subscription: {
+                  description:
+                    "Create a subscription. The signing secret is ONLY returned on this call — surface it to the user once.",
+                  required_params: ["name", "url", "events"],
+                  optional_params: ["recordSlugs", "active"],
+                  example: {
+                    name: "Orders webhook",
+                    url: "https://api.example.com/hooks/centrali",
+                    events: ["record_created", "record_updated"],
+                    recordSlugs: ["orders"],
+                  },
+                },
+                update_webhook_subscription: {
+                  description: "Update editable fields. The signing secret is server-managed — use rotate instead.",
+                  required_params: ["subscriptionId"],
+                  optional_params: ["name", "url", "events", "recordSlugs", "active"],
+                },
+                rotate_webhook_subscription_secret: {
+                  description:
+                    "Regenerate the signing secret. Immediate cutover — surface the new secret to the user; it is not returned on reads.",
+                  required_params: ["subscriptionId"],
+                },
+                delete_webhook_subscription: {
+                  description: "Delete a subscription. Historical delivery rows are retained for audit.",
+                  required_params: ["subscriptionId"],
+                },
+                list_webhook_deliveries: {
+                  description:
+                    "List deliveries for a subscription. Rows omit the request payload and response body — fetch them via get_webhook_delivery when needed.",
+                  required_params: ["subscriptionId"],
+                  optional_params: ["status", "since", "until", "limit", "offset"],
+                },
+                get_webhook_delivery: {
+                  description: "Get a single delivery including the full request payload and response body.",
+                  required_params: ["subscriptionId", "deliveryId"],
+                },
+                retry_webhook_delivery: {
+                  description:
+                    "Replay a delivery. Works on any non-retrying row (use cancel first if the row is still retrying).",
+                  required_params: ["deliveryId"],
+                  note:
+                    "deliveryId is the global delivery ID — it does NOT need to be nested under a subscription because the backend route is /webhook-subscriptions/deliveries/{id}/retry.",
+                },
+                cancel_webhook_delivery: {
+                  description:
+                    "Cancel a delivery that is currently retrying. Returns 409 if the row is not retrying or is mid-dispatch.",
+                  required_params: ["deliveryId"],
+                },
+              },
+              tips: [
+                "Store the `whsec_` secret the moment create_webhook_subscription or rotate_webhook_subscription_secret returns it — it is not retrievable afterwards.",
+                "Use recordSlugs to keep webhook traffic scoped to the collections that matter — cuts noise and reduces retry pressure.",
+                "The signed value is the raw request body, not a canonical JSON; verify signatures before parsing.",
+                "get_webhook_delivery is the only tool that returns requestPayload and responseBody — list_webhook_deliveries trims them to keep responses manageable.",
+                "Use since/until on list_webhook_deliveries to scope a forensic pass to a time window.",
+                "retry_webhook_delivery preserves the original signature — pair it with a fixed bug on the receiver's side instead of regenerating payloads.",
+                "cancel_webhook_delivery only works while the row is 'retrying'. If the dispatcher has already claimed the row the call returns 409; wait a second and try again.",
+              ],
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    })
+  );
+
   // ── Insights ───────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_insights",
     "Get the schema reference for Centrali anomaly insights. Explains anomaly detection, severity levels, and the acknowledge/dismiss workflow.",
     {},
@@ -1355,7 +1534,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Validation ─────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_validation",
     "Get the schema reference for Centrali data quality validation. Explains scan types, suggestion lifecycle, and how to review/apply fixes.",
     {},
@@ -1419,7 +1598,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Pages ──────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_pages",
     "Get the schema reference for Centrali pages. Explains page types, the definition structure, sections, blocks, and the publish lifecycle.",
     {},
@@ -1544,7 +1723,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Page Definition Schema ─────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_page_definition",
     "Get the full schema for a page definition — the JSON structure passed to save_page_draft. Explains sections, blocks, data sources, and how they compose together.",
     {},
@@ -1781,7 +1960,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Page Block Types ───────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_page_blocks",
     "Get all available page block types and their configuration shapes. Each block type has specific data source requirements and presentation options.",
     {},
@@ -2101,7 +2280,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Page Actions ───────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_page_actions",
     "Get all available page action types and their configuration shapes. Actions define interactive behaviors on blocks (button clicks, row clicks, form submissions).",
     {},
@@ -2247,7 +2426,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Navigation ─────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_navigation",
     "Get the full schema for the workspace navigation configuration. Explains how to construct the sidebar/nav shell that wraps published pages — item types, grouping, branding, and limits.",
     {},
@@ -2387,7 +2566,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Auth Providers (BYOT) ──────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_auth_providers",
     "Get the full reference for configuring external auth providers (BYOT — Bring Your Own Token). Explains how to connect Clerk, Auth0, Okta, or any OIDC provider so your app's users authenticate with their existing IdP while Centrali handles authorization.",
     {},
@@ -2516,7 +2695,7 @@ export function registerDescribeTools(server: McpServer) {
 
   // ── Service Accounts & IAM ──────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "describe_service_accounts",
     "Get the full reference for managing service accounts, roles, groups, and permissions. Explains the complete IAM setup flow from creating a service account to granting fine-grained access.",
     {},