@adrata/adrata-mcp 1.0.1 → 1.0.3

package/api-bridge.js

@@ -91,11 +91,19 @@ const ALLOWED_PREFIXES = [
   '/api/v1/email',
   '/api/v1/email-analytics',
   '/api/v1/email-deliverability',
+  // `matchesPathPrefix` is segment-boundary matched, so `/api/v1/email` does
+  // NOT annex `/api/v1/email-drafts` — the draft surface the Email app reads
+  // and writes on every compose was outside the allowlist entirely.
+  '/api/v1/email-drafts',
   '/api/v1/email-intelligence',
   '/api/v1/email-provisioning',
   '/api/v1/emails',
   '/api/v1/engagement',
-  '/api/v1/entities',
+  // What the workspace is entitled to. The nine-space chooser at /spaces reads
+  // exactly this and nothing else, so without it an agent cannot answer "which
+  // spaces does this workspace even have" — the first question about the app's
+  // new top-level shape.
+  '/api/v1/entitlements',
   '/api/v1/env-audit',
   '/api/v1/events',
   '/api/v1/evidence',
@@ -121,8 +129,13 @@ const ALLOWED_PREFIXES = [
   '/api/v1/jobs',
   '/api/v1/knowledge',
   '/api/v1/lead-lifecycle',
+  // Same segment-boundary point as email-drafts: `/api/v1/leads` does not
+  // annex `/api/v1/lead-lists`. The Deals list joins lead lists and their
+  // members, so the list surface was half-reachable without this.
+  '/api/v1/lead-lists',
   '/api/v1/lead-routing',
   '/api/v1/leads',
+  '/api/v1/lists',
   '/api/v1/leaderboard',
   '/api/v1/linkedin',
   '/api/v1/media',
@@ -158,8 +171,14 @@ const ALLOWED_PREFIXES = [
   '/api/v1/retention',
   '/api/v1/revenue',
   '/api/v1/revenue-cloud',
-  '/api/v1/sales',
-  '/api/v1/scim',
+  // Source control connections and their repository bindings. The board
+  // cannot learn that a pull request merged unless something can create the
+  // connection and register the callback, and until this row existed the
+  // bridge refused every /scm path — so the receiver at /webhooks/scm sat
+  // mounted and reachable with no connection ever pointing at it.
+  // The unauthenticated receiver itself is NOT here: it is mounted below the
+  // auth layer and is not an agent-callable path.
+  '/api/v1/scm',
   '/api/v1/scoring',
   '/api/v1/security',
   '/api/v1/self-service',
@@ -169,7 +188,6 @@ const ALLOWED_PREFIXES = [
   '/api/v1/signal-triggers',
   '/api/v1/simple-features',
   '/api/v1/sms',
-  '/api/v1/sso',
   '/api/v1/speedrun',
   '/api/v1/supersets',
   '/api/v1/survival',
@@ -179,6 +197,7 @@ const ALLOWED_PREFIXES = [
   '/api/v1/targets',
   '/api/v1/team',
   '/api/v1/trash',
+  '/api/v1/triggers',
   '/api/v1/usage',
   '/api/v1/user-voice-profile',
   '/api/v1/users',
@@ -192,12 +211,36 @@ const ALLOWED_PREFIXES = [
   '/api/v1/work-board-rollups',
   '/api/v1/work-boards',
   '/api/v1/work-items',
+  // The containers above the cards (initiative / epic / feature) and the
+  // "add this to the roadmap" verb. Creating an epic proposal is a governed
+  // write like any other; the strategic commitment itself still moves through
+  // spoq/ PRs (company/decisions/2026-08-06-spoq-roadmap-sync.md).
+  '/api/v1/work-scopes',
   '/api/v1/workflow-runtime',
   '/api/v1/workflows',
   '/api/v1/workspace',
   '/api/v1/workspace-features',
   '/api/v1/workspace-settings',
   '/api/v1/zoho',
+  // ---------------------------------------------------------------------
+  // /api/v2 — the desktop read models and the aimed send path.
+  //
+  // Until this block existed the bridge allowlisted `/api/v1` exclusively, so
+  // EVERY v2 path failed `path is outside the agent bridge allowlist`. That
+  // was not a niche gap: the app's Email and Calendar surfaces read from v2,
+  // not v1. `GET /api/v2/emails/threads` backs the inbox list,
+  // `GET /api/v2/emails/counts` backs the folder badges, and
+  // `GET /api/v2/events/calendar` backs the entire agenda. A person could open
+  // their inbox and their calendar; an agent could reach neither, while the
+  // v1 write paths for the same records (PUT /api/v1/events/{id}, the draft
+  // routes) were allowlisted the whole time. The bridge could modify a
+  // calendar it could not read.
+  //
+  // The v2 namespace is deliberately small — `code/api/src/routes/v2/mod.rs`
+  // nests exactly `/emails` and `/events` — so these two prefixes are the
+  // whole surface, not a wildcard.
+  '/api/v2/emails',
+  '/api/v2/events',
 ];
 
 function matchesPathPrefix(path, prefix) {
@@ -232,10 +275,46 @@ const PATH_WRITE_SCOPES = [
   ['/api/v1/agent-tasks', 'write:tasks'],
   ['/api/v1/tasks', 'write:tasks'],
   ['/api/v1/actions', 'write:actions'],
+  // Starfield boards. A card IS a task, so the API's scope_guard maps all three
+  // board families onto the SAME read:tasks/write:tasks pair rather than a new
+  // scope family — see `required_scopes_for` in
+  // code/api/crates/middleware/src/scope_guard/mod.rs and the test
+  // `work_board_routes_are_reachable_by_the_credential_the_mcp_actually_issues`.
+  // Without these three rows a board write previewed as
+  // `requiredScope: "unknown (no mapping for this path)"` with `wouldSend: true`,
+  // so the preview could not warn that the connection lacked write:tasks — the
+  // exact "safe preview that predicts nothing" this map exists to prevent.
+  // All three are listed separately because `matchesPathPrefix` is
+  // segment-boundary matched: `/work-boards` does not annex
+  // `/work-board-rollups`.
+  // Authorising a source-control account is the same act as connecting a CRM —
+  // an external system permitted to write into the workspace — so scope_guard
+  // maps it onto the integrations family rather than a new one. Deliberately
+  // not an `admin:` scope: those refuse first-party bypass and a human session
+  // JWT carries an empty permission list, which would 403 every person opening
+  // the Connections screen. Mirrors `family_matches(path, "/scm")` in
+  // code/api/crates/middleware/src/scope_guard/mod.rs.
+  ['/api/v1/scm', 'write:integrations'],
+  ['/api/v1/work-boards', 'write:tasks'],
+  ['/api/v1/work-items', 'write:tasks'],
+  ['/api/v1/work-board-rollups', 'write:tasks'],
 ];
 
+/**
+ * The API classifies a path AFTER stripping its version prefix, so
+ * `/api/v2/emails/direct` is scoped by exactly the same rules as
+ * `/api/v1/emails/direct` (`VERSIONED_API_PREFIXES` in
+ * code/api/crates/middleware/src/scope_guard/mod.rs). Mirror that here instead
+ * of duplicating every row under a second version — a duplicated map is a map
+ * that drifts, and a v2 path silently falling through to "no mapping" is the
+ * "preview that predicts nothing" failure this module exists to prevent.
+ */
+function toScopeClassificationPath(path) {
+  return path.startsWith('/api/v2/') ? `/api/v1/${path.slice('/api/v2/'.length)}` : path;
+}
+
 export function requiredWriteScopeForPath(path) {
-  const normalized = normalizeApiPath(path);
+  const normalized = toScopeClassificationPath(normalizeApiPath(path));
   let best = null;
   for (const [prefix, scope] of PATH_WRITE_SCOPES) {
     if (matchesPathPrefix(normalized, prefix)) {

package/governance/governed-args.js

@@ -0,0 +1,261 @@
+/**
+ * Shared governed-write plumbing for the toolset packs.
+ *
+ * # Why this file exists
+ *
+ * `governedWrite` (api-bridge.js) is the enforcement point: a write previews by
+ * default and only executes with `dryRun:false` + `approved:true` + a non-empty
+ * `reason` + a non-empty `idempotencyKey`. server.js wired 18 tools to it, but
+ * it did so with two private helpers — `governedWriteArgs` (the zod fields) and
+ * `governedWriteNote` (the description sentence) — that live inside server.js
+ * and cannot be imported. Every other pack (`toolsets/*.js`, `tools/*.js`) was
+ * therefore left calling `api()` raw, which is exactly the asymmetry
+ * `governedWrite` was written to end: the purpose-built tool was strictly less
+ * safe than the generic `adrata_api_request` fallback it exists to replace.
+ *
+ * Copying the schema into five files is how a governance contract drifts — one
+ * file gains a field, another keeps the old wording, and the gate silently
+ * differs by tool. So the schema, the description sentence, the refusal text
+ * and the preview renderer live here once, and the packs import them.
+ *
+ * This governs the *client*. It does not replace the server-side scope check:
+ * the API still rejects a token without the matching `write:*` scope with 403
+ * insufficient_scope.
+ *
+ * It lives in `governance/` rather than at the package root next to
+ * `governed-args`-style helpers because `package.json`'s `files:` array names
+ * root modules one by one and whole directories wholesale — `governance/` is
+ * already shipped, a new root file would not be, and packaging.test.js's "ships
+ * every source file" check would fail on a module that exists in the checkout
+ * and is missing from the tarball. `governance/money.js` is the same idea for
+ * money writes, so this is where a governance envelope belongs anyway.
+ */
+
+import { z as defaultZod } from 'zod';
+
+import { governedWrite } from '../api-bridge.js';
+import { md, mdError } from '../output-formatter.js';
+
+/**
+ * Coresignal charges 20 credits for a `collect/{employee_id}` — one person.
+ * See CLAUDE.md ("Coresignal credits are the other real bill") and
+ * `code/api/crates/integrations/src/coresignal/company_multi_source.rs`, whose
+ * `COMPANY_MULTI_SOURCE_CREDITS_PER_CALL` is likewise 20.
+ *
+ * This number is stated in the tool description AND repeated in the preview on
+ * purpose: a caller who only ever reads the preview must still see the bill
+ * before approving it.
+ */
+export const CORESIGNAL_CREDITS_PER_PERSON = 20;
+export const CORESIGNAL_CREDITS_PER_COMPANY = 20;
+
+export const PERSON_ENRICH_COST_SENTENCE =
+  ` SPENDS VENDOR CREDITS: a Coresignal collect is ${CORESIGNAL_CREDITS_PER_PERSON} credits per person, charged to the workspace's shared credit pool.`;
+
+export const COMPANY_ENRICH_COST_SENTENCE =
+  ` SPENDS VENDOR CREDITS: a Coresignal company multi-source call is ${CORESIGNAL_CREDITS_PER_COMPANY} credits per company, charged to the workspace's shared credit pool.`;
+
+/** The cost line rendered inside an enrich preview. */
+export function enrichCostLine(kind) {
+  return kind === 'company'
+    ? `${CORESIGNAL_CREDITS_PER_COMPANY} Coresignal credits per company (vendor spend, not refundable)`
+    : `${CORESIGNAL_CREDITS_PER_PERSON} Coresignal credits per person (vendor spend, not refundable)`;
+}
+
+/**
+ * Governance fields every governed write tool accepts.
+ *
+ * Takes the caller's `zod` so a pack that receives `z` through its dependency
+ * object (tools/email-tools.js) builds its schema with the same instance the
+ * rest of that tool's schema uses.
+ */
+export function governedWriteArgs(zod = defaultZod) {
+  return {
+    dryRun: zod
+      .boolean()
+      .optional()
+      .describe('Defaults to true. Returns a preview of the exact call instead of performing it. Set false to execute.'),
+    approved: zod
+      .boolean()
+      .optional()
+      .describe('Required (true) for a live write. Records that the caller confirmed the mutation; it does not by itself grant scope.'),
+    reason: zod
+      .string()
+      .optional()
+      .describe('Required for a live write. Recorded as the audit reason (X-Adrata-Reason).'),
+    idempotencyKey: zod
+      .string()
+      .optional()
+      .describe('Required for a live write. Sent as Idempotency-Key so a retry cannot double-apply.'),
+  };
+}
+
+/**
+ * The sentence appended to a governed tool's description.
+ *
+ * It names the scope because that is the one thing the caller cannot guess and
+ * the API will reject them for: a 403 `insufficient_scope` on `write:people`
+ * reads like a bug unless the tool already said which scope it needed. Pass
+ * `null` when the route genuinely requires no OAuth write scope.
+ */
+export function governedWriteNote(scope) {
+  const base =
+    ' Governed write: previews by default. A live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey';
+  return scope
+    ? `${base}, and the connection must hold ${scope} (connect_workspace with writeAccess:true).`
+    : `${base}. This route currently requires no OAuth write scope, so approval and audit are the only gate.`;
+}
+
+/** True when the caller has explicitly asked for a live write. */
+export function isLiveWrite(args = {}) {
+  return args?.dryRun === false;
+}
+
+/**
+ * Which authorization fields a live write is still missing.
+ *
+ * `validateApiBridgeRequest` throws on the first one it finds, which tells a
+ * caller to add a reason and then, one round trip later, to add an idempotency
+ * key. Listing them together is the same gate, said once.
+ */
+export function missingLiveWriteFields(args = {}) {
+  const missing = [];
+  if (args.approved !== true) missing.push('approved:true');
+  if (!args.reason || !String(args.reason).trim()) missing.push('reason');
+  if (!args.idempotencyKey || !String(args.idempotencyKey).trim()) missing.push('idempotencyKey');
+  return missing;
+}
+
+/** The refusal payload for a live write that is missing authorization fields. */
+export function liveWriteRefusal(args = {}, request = {}) {
+  const missing = missingLiveWriteFields(args);
+  return {
+    error: true,
+    refused: true,
+    missing,
+    message:
+      `live write refused: missing ${missing.join(', ')}. ` +
+      `Nothing was sent to ${request.method || 'the API'} ${request.path || ''}`.trimEnd() + '.',
+    wouldHaveCalled: { method: request.method, path: request.path },
+  };
+}
+
+const PREVIEW_LABELS = {
+  method: 'Method',
+  path: 'Path',
+  wouldSend: 'Would send',
+  requiredScope: 'Required scope',
+  scopeHeld: 'Scope held',
+  entity: 'Entity',
+  entityId: 'Entity ID',
+  operation: 'Operation',
+  cost: 'Cost if executed',
+  affects: 'Would affect',
+  cascade: 'Cascades to',
+};
+
+/**
+ * Render a governed-write preview as Markdown.
+ *
+ * The preview is not a courtesy — it IS the refusal, rendered as the exact call
+ * that was withheld plus what is missing to authorize it. So it always prints
+ * the method and path, never a bare "ok".
+ */
+export function previewMarkdown(heading, preview = {}) {
+  const {
+    method,
+    path,
+    wouldSend,
+    requiredScope,
+    scopeHeld,
+    requiredForLiveWrite,
+    note,
+    body,
+    blocked,
+    fix,
+    reason,
+    ...extra
+  } = preview;
+
+  let text = `## ${heading} — Preview Only (nothing was written)\n\n`;
+  text += `- **Method:** ${method}\n`;
+  text += `- **Path:** ${path}\n`;
+  text += `- **Required scope:** ${requiredScope}\n`;
+  text += `- **Scope held:** ${scopeHeld}\n`;
+
+  for (const [key, value] of Object.entries(extra)) {
+    if (value === undefined || value === null) continue;
+    const label = PREVIEW_LABELS[key] || key;
+    const rendered =
+      typeof value === 'object' ? JSON.stringify(value) : String(value);
+    text += `- **${label}:** ${rendered}\n`;
+  }
+
+  if (blocked) {
+    text += `\n> **Blocked:** ${reason}\n>\n> Fix: ${fix}\n`;
+  }
+
+  if (body && Object.keys(body).length > 0) {
+    text += `\n### Body that would be sent\n\n\`\`\`json\n${JSON.stringify(body, null, 2)}\n\`\`\`\n`;
+  }
+
+  text += `\n### To execute\n\nRe-call with \`dryRun:false\`, \`approved:true\`, a \`reason\`, and an \`idempotencyKey\`.\n`;
+  if (note) text += `\n${note}\n`;
+  return text;
+}
+
+/**
+ * Run a Markdown-returning tool's write through the governed contract.
+ *
+ * @param api       the pack's `api(method, path, opts)` callable
+ * @param args      tool arguments carrying dryRun/approved/reason/idempotencyKey
+ * @param request   {method, path, body, preview, heading}
+ * @param onSuccess (result) => Markdown string, rendered only on a live write
+ */
+export async function runGovernedMarkdownWrite(api, args, request, onSuccess) {
+  const { heading = 'Governed write', ...call } = request;
+
+  if (isLiveWrite(args)) {
+    const missing = missingLiveWriteFields(args);
+    if (missing.length > 0) {
+      return mdError(
+        `Live write refused — missing ${missing.join(', ')}`,
+        `Nothing was sent to ${call.method} ${call.path}. Re-call with dryRun:false plus ${missing.join(', ')}.`,
+      );
+    }
+  }
+
+  try {
+    const outcome = await governedWrite(api, args, call);
+    if (outcome.dryRun) return md(previewMarkdown(heading, outcome.preview));
+    return md(onSuccess(outcome.result));
+  } catch (err) {
+    return mdError(`${heading} failed`, err.message);
+  }
+}
+
+/**
+ * Run a JSON-returning tool's write through the governed contract.
+ *
+ * @param api       the pack's `api(method, path, opts)` callable
+ * @param args      tool arguments carrying dryRun/approved/reason/idempotencyKey
+ * @param request   {method, path, body, preview}
+ * @param ok        the pack's `ok(data)` envelope helper
+ * @param onSuccess (result) => object, merged into the live-write envelope
+ */
+export async function runGovernedJsonWrite(api, args, request, ok, onSuccess = (r) => ({ result: r })) {
+  if (isLiveWrite(args)) {
+    const missing = missingLiveWriteFields(args);
+    if (missing.length > 0) return ok(liveWriteRefusal(args, request));
+  }
+
+  try {
+    const outcome = await governedWrite(api, args, request);
+    if (outcome.dryRun) {
+      return ok({ dryRun: true, executed: false, preview: outcome.preview });
+    }
+    return ok({ dryRun: false, executed: true, ...onSuccess(outcome.result) });
+  } catch (err) {
+    return ok({ error: true, executed: false, message: err.message });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adrata/adrata-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Adrata MCP Server \u2014 connect Claude Code, Codex, Gemini, Cursor, and other AI tools to your CRM. 80+ tools for companies, people, deals, actions, buyer groups, warm intros, webhooks, intelligence, and more.",
   "type": "module",
   "main": "server.js",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "start": "node server.js",
-    "test": "node --test server.test.js api-bridge.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js security.test.js toolsets.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js governance/money.test.js"
+    "test": "node --test server.test.js api-bridge.test.js audit-flush.test.js buyer-group-writes.test.js note-writes.test.js mcp-spec.test.js packaging.test.js product-profile.test.js security.test.js tool-annotations.test.js toolsets.test.js access/auth.test.js access/oauth-callback.test.js access/oauth-session.test.js access/oauth-capabilities.test.js scripts/local-dev-server.test.js tools/email-tools.test.js tools/scheduling.test.js tools/work-board-tools.test.js tools/work-hub/audit.test.js tools/roadmap-tools.test.js governance/money.test.js"
   },
   "keywords": [
     "mcp",
@@ -47,6 +47,7 @@
     "transport-http.js",
     "resources.js",
     "tool-annotations.js",
+    "product-profile.js",
     "output-formatter.js",
     "access/",
     "tools/",
@@ -63,8 +64,8 @@
   },
   "overrides": {
     "@hono/node-server": "2.0.12",
-    "fast-uri": "3.1.4",
-    "hono": "4.12.27"
+    "fast-uri": "3.1.5",
+    "hono": "4.12.34"
   },
   "bugs": {
     "url": "https://github.com/adrata/adrata/issues"

package/product-profile.js

@@ -0,0 +1,43 @@
+/** Branded MCP launch profiles over one shared server implementation. */
+export const PRODUCT_PROFILES = Object.freeze({
+  adrata: Object.freeze({ displayName: 'Adrata', domains: null }),
+  bounce: Object.freeze({
+    displayName: 'Bounce',
+    domains: Object.freeze([
+      'actions', 'agent', 'bridge', 'calendar', 'email', 'infra',
+      'meetings', 'sequences', 'webhooks',
+    ]),
+  }),
+  starfield: Object.freeze({
+    displayName: 'Starfield',
+    domains: Object.freeze([
+      'agent', 'board', 'bridge', 'forms', 'surveys', 'webhooks', 'workflows',
+    ]),
+  }),
+});
+
+export function applyProductProfile(env = process.env) {
+  const product = env.ADRATA_MCP_PRODUCT?.trim().toLowerCase();
+  if (!product) return null;
+  const profile = PRODUCT_PROFILES[product];
+  if (!profile) {
+    throw new Error(
+      `Unknown ADRATA_MCP_PRODUCT "${product}". Expected ${Object.keys(PRODUCT_PROFILES).join(', ')}.`,
+    );
+  }
+  if (!env.ADRATA_MCP_SERVER_NAME?.trim()) env.ADRATA_MCP_SERVER_NAME = profile.displayName;
+  // Explicit operator policy wins. A profile only supplies a least-privilege default.
+  if (!env.ADRATA_MCP_ENABLED_DOMAINS?.trim() && profile.domains) {
+    env.ADRATA_MCP_ENABLED_DOMAINS = profile.domains.join(',');
+  }
+  return profile;
+}
+
+export function assertProductCapabilityRef(ref, product) {
+  const normalizedProduct = String(product ?? '').trim().toLowerCase();
+  if (!normalizedProduct) return ref;
+  if (typeof ref !== 'string' || !ref.startsWith(`/${normalizedProduct}/`)) {
+    throw new Error(`Capability ${String(ref)} is outside the /${normalizedProduct}/ product scope.`);
+  }
+  return ref;
+}

package/resources.js

@@ -225,18 +225,30 @@ Use connect_workspace to get started.`;
  * @param {Function} apiFn  - The api() helper for server calls
  * @param {object}   auth   - AUTH context { tier, token, apiKey, authenticated }
  */
+export function resourceNamesForProduct(product = process.env.ADRATA_MCP_PRODUCT) {
+  const normalized = String(product ?? '').trim().toLowerCase();
+  return !normalized || normalized === 'adrata'
+    ? ['recent-research', 'sales-playbook', 'workspace-summary']
+    : ['workspace-summary'];
+}
+
 export function registerResources(server, apiFn, auth) {
-  server.resource(
-    'recent-research',
-    'adrata://recent-research',
-    buildRecentResearchHandler(apiFn, auth)
-  );
+  const enabled = new Set(resourceNamesForProduct());
+  if (enabled.has('recent-research')) {
+    server.resource(
+      'recent-research',
+      'adrata://recent-research',
+      buildRecentResearchHandler(apiFn, auth)
+    );
+  }
 
-  server.resource(
-    'sales-playbook',
-    'adrata://guide/sales-playbook',
-    buildSalesPlaybookHandler()
-  );
+  if (enabled.has('sales-playbook')) {
+    server.resource(
+      'sales-playbook',
+      'adrata://guide/sales-playbook',
+      buildSalesPlaybookHandler()
+    );
+  }
 
   server.resource(
     'workspace-summary',

package/security.js

@@ -300,6 +300,16 @@ class AuditLogger {
     this.maxBufferedEntries = 1000;
     this.flushIntervalMs = 30_000;
     this.flushing = false;
+    // Consecutive failed flushes. Telemetry is best-effort, so a server that is
+    // permanently unable to accept it must not produce an unbounded stream of
+    // stderr on somebody's terminal: the MCP's own audit endpoint answered 500
+    // to every batch for the whole life of the 1.0.x line, and the visible
+    // result was "[audit] Failed to flush N audit entries" every 30 seconds,
+    // forever, in a client the user is trying to work in. After
+    // `maxConsecutiveFailures` the logger says so ONCE and stands down.
+    this.consecutiveFailures = 0;
+    this.maxConsecutiveFailures = 3;
+    this.disabled = false;
     this.flushTimer = setInterval(() => this.flush(), this.flushIntervalMs);
     if (this.flushTimer.unref) this.flushTimer.unref();
   }
@@ -309,7 +319,7 @@ class AuditLogger {
    * @param {{ tool: string, tier: string, action: string, args: object, userId: string|null, sessionKey: string, timestamp: string }} entry
    */
   log(entry) {
-    if (!TELEMETRY_ENABLED) return;
+    if (!TELEMETRY_ENABLED || this.disabled) return;
 
     this.buffer.push({
       tool: entry.tool,
@@ -332,18 +342,36 @@ class AuditLogger {
    * Silently drops entries if the API is unavailable (non-blocking).
    */
   async flush() {
-    if (this.buffer.length === 0 || this.flushing) return;
+    if (this.buffer.length === 0 || this.flushing || this.disabled) return;
     this.flushing = true;
     const entries = this.buffer.splice(0, this.buffer.length);
 
     if (this.apiFn) {
       try {
         await this.apiFn('POST', '/api/v1/mcp/audit', { body: { entries } });
+        // A success clears the streak; an intermittent outage must not count
+        // toward standing down.
+        this.consecutiveFailures = 0;
       } catch {
-        // Retain a bounded retry buffer. Never retain arbitrary arguments: log()
-        // already redacts and truncates them before they enter this buffer.
-        this.buffer = [...entries, ...this.buffer].slice(-this.maxBufferedEntries);
-        console.error(`[audit] Failed to flush ${entries.length} audit entries; retained for retry`);
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+          // Give up for the life of the process, and drop what we were holding
+          // rather than carrying a doomed batch forever. Telemetry is not worth
+          // a permanent retry loop or a growing buffer in someone's editor.
+          this.disabled = true;
+          this.buffer = [];
+          clearInterval(this.flushTimer);
+          console.error(
+            `[audit] Audit telemetry disabled after ${this.consecutiveFailures} consecutive flush failures. `
+            + 'Tool calls still work; only local usage analytics stop. '
+            + 'Set ADRATA_TELEMETRY=off to disable this at startup.',
+          );
+        } else {
+          // Retain a bounded retry buffer. Never retain arbitrary arguments: log()
+          // already redacts and truncates them before they enter this buffer.
+          this.buffer = [...entries, ...this.buffer].slice(-this.maxBufferedEntries);
+          console.error(`[audit] Failed to flush ${entries.length} audit entries; retained for retry`);
+        }
       } finally {
         this.flushing = false;
       }