@adrata/adrata-mcp 1.0.0

package/server.js

@@ -0,0 +1,2139 @@
+#!/usr/bin/env node
+
+/**
+ * @adrata/adrata-mcp
+ *
+ * Connect Claude Code, Cursor, Windsurf, VS Code, and Claude Desktop
+ * to your Adrata CRM workspace.
+ *
+ * Usage:
+ *   npx -y @adrata/adrata-mcp
+ *
+ * Environment:
+ *   ADRATA_API_KEY          — Your Adrata API key (enables pro tier)
+ *   ADRATA_OAUTH_TOKEN      — OAuth bearer token (enables enterprise tier)
+ *   ADRATA_API_URL          — API base URL (default: https://api.adrata.com)
+ *   ADRATA_MCP_TRANSPORT    — 'stdio' (default) or 'http' for Streamable HTTP
+ *   ADRATA_MCP_PORT         — HTTP transport port (default: 3100)
+ *   ADRATA_MCP_CORS_ORIGINS — Comma-separated CORS origins (default: '*')
+ *   ADRATA_MCP_SERVER_NAME  — Display name reported in serverInfo
+ *                             (default: '@adrata/adrata-mcp'). The
+ *                             `@adrata/starfield-mcp` wrapper sets this to
+ *                             'Starfield'.
+ *
+ * Tier model:
+ *   - No credentials:    free tier  (search, email sync, demo scheduling)
+ *   - ADRATA_API_KEY:    pro tier   (+ intelligence, analytics, enrichment)
+ *   - ADRATA_OAUTH_TOKEN: enterprise (+ CRM CRUD, sequences, admin)
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { authenticate, reauthenticate, checkToolAccess, assertOAuthIssuerMatchesTarget } from './access/auth.js';
+import { TIERS } from './access/tiers.js';
+import { findCompany, findPerson } from './tools/free-search.js';
+import { applySecurityLayer } from './security.js';
+import { registerMemoryTools, wrapWithEventLogging, registerProfileResource } from './tools/memory.js';
+import { registerBillingTools } from './tools/billing.js';
+import { registerMorningBrief } from './tools/morning-brief.js';
+import { registerSloanTools } from './toolsets/revenue/sloan-tools.js';
+import { registerResources } from './resources.js';
+import { connectWorkspace, disconnectWorkspace, getConnectionStatus, getValidToken, fetchWorkspaceCapabilities, loadTokens } from './access/oauth.js';
+import { registerEnterpriseTools } from './tools/enterprise-tools.js';
+import { registerEmailTools } from './tools/email-tools.js';
+import { registerWorkBoardTools } from './tools/work-board-tools.js';
+import { registerPaperTools } from './tools/paper-tools.js';
+import { register as registerAlwaysLoadedTools } from './toolsets/revenue/always-loaded.js';
+import { register as registerExtensibilityTools } from './toolsets/extensibility.js';
+import { getDemoAvailability, scheduleDemo, scheduleMeeting } from './tools/scheduling.js';
+import { registerAnalytics } from './analytics.js';
+import {
+  apiBridgeCatalog,
+  buildMutationHeaders,
+  buildRealtimePayload,
+  governedWrite,
+  validateApiBridgeRequest,
+} from './api-bridge.js';
+import { buildToolAnnotations, checkDomainScope } from './tool-annotations.js';
+import { executeMoneyWrite, capClientSide, CLIENT_PAGE_CAP } from './governance/money.js';
+
+let AUTH = authenticate();
+const API_BASE = AUTH.apiUrl || process.env.ADRATA_API_URL || 'https://api.adrata.com';
+const authContextStore = new AsyncLocalStorage();
+
+function currentAuth() {
+  return authContextStore.getStore() || AUTH;
+}
+
+function runWithAuthContext(auth, fn) {
+  return authContextStore.run(auth || AUTH, fn);
+}
+
+if (AUTH.tier === 'free') {
+  console.error('Adrata MCP Server starting in FREE tier mode.');
+  console.error('Set ADRATA_API_KEY for pro features, or use connect_workspace for enterprise.');
+} else if (AUTH.tier === 'pro') {
+  console.error(`Adrata MCP Server starting in PRO tier mode.`);
+} else {
+  console.error(`Adrata MCP Server starting in ENTERPRISE tier mode (source: ${AUTH.source}).`);
+  // Pre-load workspace capabilities for enterprise connections
+  if (AUTH.token) {
+    fetchWorkspaceCapabilities(API_BASE, AUTH.token).catch(() => {
+      console.error('Warning: Could not fetch workspace capabilities at startup.');
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helper
+// ---------------------------------------------------------------------------
+
+// Translate a typed refresh failure from getValidToken into a clear,
+// actionable tool error. A dead refresh token ("reconnect required") must not
+// read like a transient blip, and a transient network blip must not tell the
+// user to reconnect.
+function refreshFailureError(err) {
+  if (err?.reconnectRequired) {
+    return new Error(
+      'Workspace OAuth session expired or was revoked. Run connect_workspace to reconnect before using governed tools.',
+    );
+  }
+  if (err?.transient) {
+    return new Error(
+      'Could not refresh the workspace session due to a temporary network issue. Please retry in a moment.',
+    );
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+
+async function api(method, path, { params, body, headers: extraHeaders } = {}) {
+  const url = new URL(path, API_BASE);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v != null && v !== '') url.searchParams.set(k, String(v));
+    }
+  }
+
+  // For stored OAuth tokens, auto-refresh if expired before the request
+  const auth = currentAuth();
+  assertOAuthIssuerMatchesTarget(auth, API_BASE);
+  let currentToken = auth.token;
+  if (auth.source === 'stored') {
+    let freshToken;
+    try {
+      freshToken = await getValidToken(API_BASE);
+    } catch (err) {
+      throw refreshFailureError(err);
+    }
+    if (!freshToken) {
+      throw new Error('No workspace OAuth session found. Run connect_workspace before using governed tools.');
+    }
+    currentToken = freshToken;
+    auth.token = freshToken;
+  }
+
+  const headers = { 'Content-Type': 'application/json' };
+  if (currentToken) {
+    headers['Authorization'] = `Bearer ${currentToken}`;
+  }
+  if (auth.apiKey) {
+    headers['X-API-Key'] = auth.apiKey;
+  }
+  Object.assign(headers, extraHeaders || {});
+
+  const request = (token) => {
+    const requestHeaders = { ...headers };
+    if (token) requestHeaders.Authorization = `Bearer ${token}`;
+    return fetch(url.toString(), {
+      method,
+      headers: requestHeaders,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  };
+
+  let res = await request(currentToken);
+  if (res.status === 401 && auth.source === 'stored') {
+    let refreshedToken;
+    try {
+      refreshedToken = await getValidToken(API_BASE, { forceRefresh: true });
+    } catch (err) {
+      throw refreshFailureError(err);
+    }
+    if (!refreshedToken) {
+      throw new Error('No workspace OAuth session found. Run connect_workspace before using governed tools.');
+    }
+    currentToken = refreshedToken;
+    auth.token = refreshedToken;
+    res = await request(currentToken);
+  }
+  // The shared agent session (agent.json) has no refresh path inside the MCP —
+  // the @adrata agent owns rotation. An expired session needs a re-login, and
+  // that must not read like a generic API failure.
+  if (res.status === 401 && auth.source === 'agent_config') {
+    throw new Error(
+      'The shared `adrata login` session was rejected (401) — it may have expired. Run `adrata login` (or `@adrata login`) to sign in again.',
+    );
+  }
+
+  const text = await res.text();
+  let data;
+  try { data = JSON.parse(text); } catch { data = { raw: text }; }
+
+  if (!res.ok) {
+    throw new Error(`API ${method} ${path} → ${res.status}: ${JSON.stringify(data).slice(0, 200)}`);
+  }
+  return data;
+}
+
+function body(fields) {
+  const b = {};
+  for (const [k, v] of Object.entries(fields)) if (v !== undefined) b[k] = v;
+  return b;
+}
+
+function ok(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+
+async function executeAiCrmTool(toolName, args = {}, controls = {}) {
+  let headers;
+  if (controls.confirmSpend === true) {
+    if (!controls.reason || !String(controls.reason).trim()) {
+      throw new Error('confirmSpend requires a non-empty reason for the durable audit log');
+    }
+    if (!controls.idempotencyKey || !String(controls.idempotencyKey).trim()) {
+      throw new Error(
+        'confirmSpend requires an idempotencyKey. Reuse the SAME key on retry so the paid provider call cannot run twice.',
+      );
+    }
+    headers = buildMutationHeaders({
+      reason: controls.reason,
+      idempotencyKey: controls.idempotencyKey,
+      approved: true,
+    });
+  }
+  const payload = {
+    toolName,
+    arguments: args,
+    ...controls,
+  };
+  return api('POST', '/api/v1/ai-crm-tools/execute', { body: payload, headers });
+}
+
+// ---------------------------------------------------------------------------
+// Shared schemas
+// ---------------------------------------------------------------------------
+
+const page = { limit: z.number().optional().describe('Results per page (default 25)'), page: z.number().optional().describe('Page number') };
+
+// Governance envelope shared by MONEY writes (partner attribution/consumption).
+// Contract implemented in governance/money.js: dry-run by default; live
+// execution requires approved:true + auditReason + idempotencyKey.
+const moneyWrite = {
+  dryRun: z.boolean().optional().describe('Defaults to TRUE: returns a preview of the exact write (payload + endpoint) without executing. Set false to execute live.'),
+  approved: z.boolean().optional().describe('Required true for live execution — explicit approval of this specific money write.'),
+  auditReason: z.string().optional().describe('Required (non-empty) for live execution: why this write is happening. Stored for audit.'),
+  idempotencyKey: z.string().optional().describe('Required for live execution: unique key (e.g. a ULID) sent as the Idempotency-Key header. Reuse the SAME key on retry so the write cannot double-book.'),
+};
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+/**
+ * What a client shows in its connection list.
+ *
+ * This is the ONE string a person actually reads — `claude mcp list` and Codex's
+ * `mcpServerStatus` both print it — and it was the npm package name, which tells
+ * a reader nothing about what they are connected to.
+ *
+ * It is overridable because one server serves several products. Somebody wiring
+ * a coding agent to their Starfield board should see Starfield in their client,
+ * not the name of the company that publishes it; `@adrata/starfield-mcp` sets
+ * this and imports this same file. There is exactly one implementation — the
+ * surfaces a seat may actually reach are decided server-side by `app_scope`, not
+ * by which name launched the process, so this cannot be used to widen access.
+ *
+ * Only the DISPLAY name moves. The tool prefix a client derives from its own
+ * config key (`mcp__adrata__*`) is the client's business and is untouched.
+ *
+ * Trimmed, because a config file is where whitespace comes from. A TOML or JSON
+ * value of `" "` is truthy, and a server whose name is a space renders as a
+ * blank row in the client's list — indistinguishable from a server that failed
+ * to start, which is the exact failure this whole surface keeps producing.
+ */
+const SERVER_NAME = process.env.ADRATA_MCP_SERVER_NAME?.trim() || '@adrata/adrata-mcp';
+
+const server = new McpServer({ name: SERVER_NAME, version: '1.0.0' });
+
+// ---------------------------------------------------------------------------
+// Tier-gating wrapper
+// ---------------------------------------------------------------------------
+// Wrap server.tool so every handler is checked against the user's tier.
+// If the user lacks access, the handler returns a teaser/prompt instead of
+// calling the real implementation. This keeps all 67 tool registrations intact.
+
+const _originalTool = server.tool.bind(server);
+server.tool = function gatedTool(name, ...rest) {
+  // server.tool(name, [description], [schema], handler) — handler is always last.
+  const handler = rest[rest.length - 1];
+  const gatedHandler = async function gatedHandler(...handlerArgs) {
+    // Least-privilege scoped tool packs: when ADRATA_MCP_ENABLED_DOMAINS is
+    // set, tools outside the granted domains are refused at dispatch.
+    const scope = checkDomainScope(name);
+    if (!scope.allowed) {
+      return ok({
+        error: 'tool_out_of_scope',
+        tool: name,
+        domain: scope.domain,
+        enabledDomains: scope.enabled,
+        message: `The "${name}" tool belongs to the "${scope.domain}" pack, which is not in the granted ADRATA_MCP_ENABLED_DOMAINS scope.`,
+      });
+    }
+    const access = checkToolAccess(name, currentAuth());
+    if (!access.allowed) {
+      return access.response;
+    }
+    return handler(...handlerArgs);
+  };
+
+  // Inject honest MCP tool annotations (readOnly/destructive/idempotent/
+  // openWorld + domain). Annotation-carrying overloads require a params
+  // schema, so normalize the args into (name, description, schema,
+  // annotations, handler). Derived from real behaviour, never a description.
+  const annotations = buildToolAnnotations(name);
+  const head = rest.slice(0, -1);
+  let description = '';
+  let schema = {};
+  if (head.length === 1) {
+    if (typeof head[0] === 'string') description = head[0];
+    else schema = head[0];
+  } else if (head.length >= 2) {
+    description = head[0];
+    schema = head[1];
+  }
+  return _originalTool(name, description, schema, annotations, gatedHandler);
+};
+
+// ---------------------------------------------------------------------------
+// Automatic event logging wrapper
+// ---------------------------------------------------------------------------
+// Wraps every tool invocation to silently POST to /api/v1/mcp/events.
+// Must be applied AFTER the tier-gating wrapper above.
+wrapWithEventLogging(server, api, AUTH);
+
+// ---------------------------------------------------------------------------
+// Security layer: rate limiting, input validation, audit logging
+// ---------------------------------------------------------------------------
+// Must be applied AFTER tier-gating and event logging wrappers above.
+applySecurityLayer(server, currentAuth, api);
+
+// ===== WORKSPACE CONNECTION: OAuth 2.0 (available at all tiers) =====
+
+server.tool('connect_workspace',
+  'Connect your Adrata workspace via OAuth 2.0. Opens a browser window for authorization. By default the connection is READ-ONLY (least privilege): search/read companies, people, opportunities, pipeline, buyer groups, signals and analytics, plus the governed AI dispatcher for reads. Pass writeAccess:true to additionally request the CRM write scopes (companies, people, buyer groups, opportunities, actions, tasks) so create/update/delete work from this client; you will see them on the consent screen and can decline. Workspace administration and enrichment spend are never requested and always require a signed-in human session. The capability summary returned is derived from the scope the server actually granted, not from what was requested.',
+  {
+    writeAccess: z.boolean().optional().describe('Request CRM write scopes in addition to read. Defaults to false (read-only).'),
+  },
+  async (args = {}) => {
+    try {
+      const result = await connectWorkspace(API_BASE, { writeAccess: args.writeAccess === true });
+      // Re-authenticate to pick up the new stored tokens
+      AUTH = reauthenticate();
+      return ok(result);
+    } catch (err) {
+      return ok({ error: true, message: err.message, hint: 'Make sure your browser is accessible and try again.' });
+    }
+  });
+
+server.tool('disconnect_workspace',
+  'Disconnect your Adrata workspace. Revokes OAuth tokens and clears local credentials. Enterprise tools will no longer be available after disconnecting.',
+  {},
+  async () => {
+    try {
+      const result = await disconnectWorkspace(API_BASE);
+      // Re-authenticate to drop enterprise tier
+      AUTH = reauthenticate();
+      return ok(result);
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('workspace_status',
+  'Check which credential this MCP server is actually running on, what tier it grants, which workspace it is acting in, and whether that credential still works. Run this first when a tool returns 401 or 403 — it names the credential in play and what to do about it.',
+  {},
+  async () => {
+    // `getConnectionStatus` reports on the STORED session (~/.adrata/tokens.json)
+    // and nothing else. That is the right question only when the stored session
+    // is the credential in play — and it is one of five (auth.js). With
+    // ADRATA_OAUTH_TOKEN, a shared agent session, or an API key, this tool used
+    // to report "No workspace connected" and `tier: free` while the server was
+    // running enterprise and every tool worked. That is the worst possible
+    // answer from a diagnostic: it sends someone to reconnect a connection that
+    // was never the problem, and it is the tool a connect flow tells you to run
+    // to confirm the setup worked.
+    const usingStoredSession = AUTH.source === 'stored';
+    const stored = await getConnectionStatus(API_BASE);
+
+    // AUTH.workspaceId is only populated when the workspace was pinned via env
+    // or CLI config. An OAuth connection leaves it null, which used to make
+    // this tool report `workspaceId: null` while every data tool was happily
+    // reading from a real workspace. Resolve it from the authenticated user so
+    // the system of record can always name the workspace it is acting on.
+    //
+    // Which credential decides "live" differs: for the stored session it is the
+    // session's own status, for any other credential it is simply that one is
+    // configured — `getConnectionStatus` only ever reports on the stored session.
+    const credentialLive = usingStoredSession ? stored.connected : AUTH.authenticated;
+    let workspaceId = AUTH.workspaceId || null;
+    let workspaceName = null;
+    if (!workspaceId && credentialLive) {
+      try {
+        const me = await api('GET', '/api/v1/users/me');
+        const u = me?.data || me;
+        workspaceId = u?.activeWorkspaceId || u?.workspaceId || null;
+      } catch {
+        // Leave null rather than inventing an ID; the caller can still see
+        // `connected` and act on it.
+      }
+    }
+    if (credentialLive) {
+      try {
+        // GET /api/v1/workspace resolves the caller's current workspace.
+        const ws = await api('GET', '/api/v1/workspace');
+        const w = ws?.data || ws;
+        workspaceName = w?.name || null;
+        workspaceId = workspaceId || w?.id || null;
+      } catch { /* name is a nicety, not a contract */ }
+    }
+    const workspaceIdSource = AUTH.workspaceId ? 'pinned' : (workspaceId ? 'resolved-from-user' : 'unknown');
+
+    if (usingStoredSession) {
+      return ok({
+        ...stored,
+        tier: stored.connected ? AUTH.tier : TIERS.FREE,
+        credential: 'stored OAuth session (~/.adrata/tokens.json)',
+        authSource: AUTH.source,
+        apiBase: API_BASE,
+        workspaceId,
+        workspaceName,
+        workspaceIdSource,
+      });
+    }
+
+    // Some other credential is in play. Say which, and report the stored
+    // session — if there even is one — as the side note it actually is.
+    const CREDENTIALS = {
+      env: 'ADRATA_OAUTH_TOKEN (environment)',
+      agent_config: 'shared agent session (~/.config/adrata/agent.json, from `adrata login`)',
+      api_key: 'ADRATA_API_KEY (environment)',
+      cli_config: 'legacy CLI token (~/.config/adrata/cli.json)',
+      none: 'none',
+    };
+    return ok({
+      connected: AUTH.authenticated,
+      tier: AUTH.tier,
+      credential: CREDENTIALS[AUTH.source] ?? AUTH.source,
+      authSource: AUTH.source,
+      apiBase: API_BASE,
+      workspaceId,
+      workspaceName,
+      workspaceIdSource,
+      // A bearer token this server did not mint cannot be introspected from
+      // here, so "connected" means "a credential is configured", not "the API
+      // accepted it". Say so rather than implying a liveness check happened.
+      note: AUTH.authenticated
+        ? 'A credential is configured and every tool will be sent with it. This is not a liveness check — if calls still fail, the token is expired or lacks the scope the route requires (403 insufficient_scope names which).'
+        : 'No credential configured. Run connect_workspace, or set ADRATA_OAUTH_TOKEN / ADRATA_API_KEY.',
+      storedSession: stored.connected
+        ? { present: true, note: 'A stored OAuth session also exists but is NOT the credential in use.' }
+        : { present: Boolean(stored.storedCredentials), note: stored.message },
+    });
+  });
+
+server.tool('list_workspaces',
+  'List the workspaces the authenticated user is actually a member of, with their role in each. Use before switch_workspace when a user belongs to more than one workspace.',
+  {},
+  // `/api/v1/workspace/mine` — the signed-in user's own memberships. Deliberately
+  // NOT `/api/v1/workspace/list`: that is the administrative endpoint, and it
+  // expands a super_admin into EVERY customer tenant (see
+  // routes/v1/entities/org/workspace/handlers.rs). Listing those here would
+  // offer an agent a set of workspace IDs it could hand straight to
+  // switch_workspace, turning a convenience tool into a cross-tenant hop.
+  async () => ok(await api('GET', '/api/v1/workspace/mine')));
+
+server.tool('switch_workspace',
+  'Switch the active workspace for the authenticated user. Subsequent tool calls read and write in the new workspace. Use list_workspaces first to get valid IDs.',
+  { workspaceId: z.string().describe('Target workspace ID from list_workspaces') },
+  async (a) => ok(await api('POST', '/api/v1/workspace/switch', { body: { workspaceId: a.workspaceId } })));
+
+// ===== ADRATA AGENT API BRIDGE =====
+
+server.tool('adrata_api_catalog',
+  'Describe the governed Adrata API bridge for Claude Code/Codex. Use this to discover how to call any allowlisted platform API safely from the agent layer.',
+  {},
+  async () => ok(apiBridgeCatalog()));
+
+server.tool('adrata_api_request',
+  'Governed low-level Adrata API request. Read calls run directly except sensitive denied surfaces. Writes default to dry-run; a live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey, and additionally requires the connection to hold the matching write:* scope (connect_workspace with writeAccess:true). Without that scope the API rejects the call with 403 insufficient_scope. Use only after a higher-level tool is not available.',
+  {
+    method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).default('GET'),
+    path: z.string().describe('Relative Adrata API path, e.g. /api/v1/opportunities/opp_123'),
+    params: z.record(z.unknown()).optional(),
+    body: z.record(z.unknown()).optional(),
+    dryRun: z.boolean().optional().describe('Defaults to true for write methods. Set false to execute a live write; the connection must also hold the matching write:* scope.'),
+    approved: z.boolean().optional().describe('Required (true) for a live write. Records that the caller confirmed the mutation; it does not by itself grant scope.'),
+    reason: z.string().optional().describe('Required for a live write. Recorded as the audit reason (X-Adrata-Reason).'),
+    idempotencyKey: z.string().optional().describe('Required for a live write. Sent as Idempotency-Key so a retry cannot double-apply.'),
+    realtimePublish: z.object({
+      workspaceId: z.string(),
+      userId: z.string().optional(),
+      entityType: z.enum(['person', 'company', 'opportunity']).optional(),
+      entityId: z.string().optional(),
+      entityName: z.string().optional(),
+      changes: z.record(z.unknown()).optional(),
+      type: z.enum(['record_updated', 'pipeline_stage_changed']).optional(),
+    }).optional().describe('Optional realtime event to publish after a successful live write.'),
+  },
+  async (args) => {
+    try {
+      // Pass the scope the stored connection actually holds so a dry-run can
+      // say whether the live write would be rejected, instead of always
+      // answering wouldSend:true.
+      let grantedScope;
+      try {
+        grantedScope = loadTokens()?.scope;
+      } catch { /* no stored connection; dry-run reports "not checked" */ }
+      const validation = validateApiBridgeRequest({ ...args, grantedScope });
+      if (validation.dryRun) {
+        return ok({
+          ...validation,
+          params: args.params || {},
+          body: args.body || {},
+        });
+      }
+
+      const result = await api(validation.method, validation.path, {
+        params: args.params,
+        body: args.body,
+        headers: buildMutationHeaders(args),
+      });
+
+      let realtime = null;
+      if (args.realtimePublish && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(validation.method)) {
+        const payload = buildRealtimePayload({
+          ...args.realtimePublish,
+          source: 'agent',
+        });
+        realtime = await api('POST', '/api/v1/realtime/publish', { body: payload });
+      }
+
+      return ok({
+        ok: true,
+        method: validation.method,
+        path: validation.path,
+        result,
+        realtime,
+      });
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('adrata_ai_tool_catalog',
+  'List the AI CRM tools Adrata chat can use, including Channels, external source catalogs, ICP ranking, batch import progress, and automation tools. Use this to audit parity before falling back to adrata_api_request.',
+  {},
+  async () => ok(await api('GET', '/api/v1/ai-crm-tools/catalog')));
+
+server.tool('adrata_ai_tool_execute',
+  'Execute the same governed AI CRM ToolDispatcher path used by Adrata chat. Free reads run directly. Reads that can spend external data credits return a spend hold; execute one only with confirmSpend:true, a reason, and an idempotencyKey (reuse the same key on retry). The response includes the approved ceiling and an exact provider-reported receipt where available. Writes use a two-step, server-bound confirmationToken flow; a client approved boolean can never authorize a write. A non-interactive machine/OAuth principal (every MCP client) can preview writes but cannot complete one.',
+  {
+    toolName: z.string().describe('AI CRM tool name from adrata_ai_tool_catalog, e.g. list_channels or rank_companies_by_icp'),
+    arguments: z.record(z.unknown()).optional(),
+    dryRun: z.boolean().optional().describe('Defaults to true for write tools. Set false only after explicit approval.'),
+    approved: z.boolean().optional().describe('Deprecated compatibility field; never authorizes a live write.'),
+    reason: z.string().optional().describe('Required audit reason for a spend acknowledgment or when requesting a live-write confirmation token.'),
+    confirmationToken: z.string().optional().describe('Single-use server token returned by the first live-write request; bound to the user, workspace, tool, and stored arguments.'),
+    confirmSpend: z.boolean().optional().describe('Required true to execute a read held for external vendor spend. Never authorizes a workspace write.'),
+    idempotencyKey: z.string().optional().describe('Required with confirmSpend:true. Reuse the same key on retry; the API replays the first response instead of calling the paid provider twice.'),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool(args.toolName, args.arguments || {}, {
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+        confirmationToken: args.confirmationToken,
+        confirmSpend: args.confirmSpend,
+        idempotencyKey: args.idempotencyKey,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+// ===== PAPER DESKTOP APP TOOLS =====
+
+registerPaperTools(server, {
+  api,
+  ok,
+  buildMutationHeaders,
+});
+
+server.tool('get_account_read',
+  'Get Adrata chat’s grounded no-loss account/deal read through the governed ToolDispatcher. Returns Known/Read/Ask, evidence, confidence, why-now, best move, alternatives, falsification criteria, and observable-evidence triangulation guardrails. Never infer IQ, age, college-as-IQ, or protected classes.',
+  {
+    opportunityId: z.string().describe('Opportunity/deal ID. Required until company-level account reads are integrated.'),
+    companyId: z.string().optional().describe('Optional company/account ID for future account-read backend alignment.'),
+    includeEvidence: z.boolean().optional().describe('Whether to include evidence objects, default true.'),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('get_account_read', args));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('build_pursuit_command_center',
+  'Build or refresh Adrata’s persistent, evidence-linked Pursuit command center for one enterprise account. Composes the active opportunity, structured MEDDPICC, buyer room and path to power, deal health and forecast risk, triggers, one recommended Give/Get move, and reviewable email/cadence proposals. Preview is non-mutating by default. Persisting the artifact or cadence requires the server-issued confirmation flow, an audit reason, and idempotent governed execution.',
+  {
+    companyId: z.string().optional().describe('Company/account ID. Supply this or companyName.'),
+    companyName: z.string().optional().describe('Company/account name when the ID is not known.'),
+    opportunityId: z.string().optional().describe('Optional opportunity/deal ID; otherwise Adrata selects the newest active account opportunity.'),
+    buyerGroupId: z.string().optional().describe('Optional buyer-room/group ID.'),
+    persistArtifact: z.boolean().optional().describe('Persist the versioned Pursuit artifact after explicit approval. Defaults to false.'),
+    persistSequence: z.boolean().optional().describe('Persist the proposed cadence after explicit approval; never enrolls recipients. Defaults to false.'),
+    reason: z.string().optional().describe('Required audit reason when requesting an approved persistence operation.'),
+    confirmationToken: z.string().optional().describe('Single-use server token returned by the first persistence request.'),
+  },
+  async (args) => {
+    try {
+      const persistArtifact = args.persistArtifact ?? false;
+      const persistSequence = args.persistSequence ?? false;
+      return ok(await executeAiCrmTool('build_pursuit_command_center', {
+        companyId: args.companyId,
+        companyName: args.companyName,
+        opportunityId: args.opportunityId,
+        buyerGroupId: args.buyerGroupId,
+        dryRun: !persistArtifact && !persistSequence,
+        persistArtifact,
+        persistSequence,
+      }, {
+        dryRun: !persistArtifact && !persistSequence,
+        reason: args.reason,
+        confirmationToken: args.confirmationToken,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('rank_paths_to_power',
+  'Rank existing warm introduction and network paths to a target account or decision maker through the governed ToolDispatcher. Does not create synthetic paths. Never infer IQ, age, college-as-IQ, or protected classes.',
+  {
+    targetPersonId: z.string().optional().describe('Known decision-maker/person ID.'),
+    targetPersonName: z.string().optional().describe('Decision-maker name if ID is unknown.'),
+    companyId: z.string().optional().describe('Target company/account ID.'),
+    companyName: z.string().optional().describe('Target company/account name if ID is unknown.'),
+    opportunityId: z.string().optional().describe('Optional opportunity/deal ID for deal context.'),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('rank_paths_to_power', args));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('recommend_deal_move',
+  'Recommend Adrata chat’s next no-loss deal move through the governed ToolDispatcher. Read-only: use write tools separately after the seller chooses an action. Supports competitor wedge inputs and uses observable-evidence triangulation guardrails; never infers IQ, age, college-as-IQ, proxy personality, or protected classes.',
+  {
+    opportunityId: z.string().describe('Opportunity/deal ID for recommendation context.'),
+    personId: z.string().optional().describe('Optional person/contact ID for contact-level context.'),
+    companyId: z.string().optional().describe('Optional company/account ID for account context.'),
+    competitorPresent: z.boolean().optional().describe('Whether a competitor is known to be active in the deal.'),
+    competitorFavored: z.boolean().optional().describe('Whether evidence suggests the competitor is currently favored.'),
+    competitorStrengths: z.array(z.string()).optional().describe('Evidence-backed competitor strengths in this account.'),
+    competitorWeaknesses: z.array(z.string()).optional().describe('Evidence-backed competitor vulnerabilities or gaps in this account.'),
+    decisionCriteria: z.array(z.string()).optional().describe('Known buyer decision criteria from CRM, meetings, docs, or research.'),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('recommend_deal_move', args));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('list_external_pipelines',
+  'List Adrata Channels: refreshable external/internal pipelines such as YC, a16z Speedrun, Techstars, CSV imports, LinkedIn searches, sequences, and other source adapters.',
+  {
+    kind: z.enum(['company', 'person', 'opportunity']).optional(),
+    adapter: z.string().optional(),
+    tag: z.string().optional(),
+    globalOnly: z.boolean().optional(),
+    limit: z.number().optional(),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('list_channels', {
+        kind: args.kind,
+        adapter: args.adapter,
+        tag: args.tag,
+        global_only: args.globalOnly,
+        limit: args.limit,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('list_external_pipeline_members',
+  'List members of an external pipeline/channel before import. Supports batch/country/status filters and can flag records for ICP ranking.',
+  {
+    channelId: z.string(),
+    limit: z.number().optional(),
+    filter: z.record(z.unknown()).optional(),
+    rankByIcp: z.boolean().optional(),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('list_channel_members', {
+        channel_id: args.channelId,
+        limit: args.limit,
+        filter: args.filter,
+        rank_by_icp: args.rankByIcp,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('import_external_pipeline_members',
+  'Import members from an external pipeline/channel into the workspace through Adrata bulk import. Defaults to dry-run; live import requires explicit approval and reason.',
+  {
+    channelId: z.string(),
+    memberIds: z.array(z.string()).optional(),
+    topNByIcp: z.number().optional(),
+    dryRun: z.boolean().optional(),
+    approved: z.boolean().optional(),
+    reason: z.string().optional(),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('import_channel_members', {
+        channel_id: args.channelId,
+        member_ids: args.memberIds,
+        top_n_by_icp: args.topNByIcp,
+      }, {
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('list_external_companies',
+  'Query Adrata nightly-refreshed external company catalogs directly, such as portfolio, cohort, or source-specific company lists. Prefer list_external_pipelines for group-shaped searches.',
+  {
+    source: z.string().optional(),
+    batch: z.string().optional(),
+    cohort: z.string().optional(),
+    hqCountry: z.string().optional(),
+    status: z.string().optional(),
+    limit: z.number().optional(),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('list_external_companies', {
+        source: args.source,
+        batch: args.batch,
+        cohort: args.cohort,
+        hq_country: args.hqCountry,
+        status: args.status,
+        limit: args.limit,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('import_external_companies',
+  'Import selected external catalog companies into the workspace through Adrata bulk import, then use check_batch_import_status and rank_companies_by_icp for best-fit ordering.',
+  {
+    ids: z.array(z.string()).describe('Adrata internal external_source_companies ids from list_external_companies'),
+    dryRun: z.boolean().optional(),
+    approved: z.boolean().optional(),
+    reason: z.string().optional(),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('import_external_to_workspace', {
+        external_ids: args.ids,
+      }, {
+        dryRun: args.dryRun,
+        approved: args.approved,
+        reason: args.reason,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('rank_companies_by_icp',
+  'Rank imported companies by similarity to the workspace ICP/closed-won profile. Use immediately after external or bulk imports to surface the best-fit accounts first.',
+  {
+    companyIds: z.array(z.string()),
+    topN: z.number().optional(),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('rank_companies_by_icp', {
+        company_ids: args.companyIds,
+        top_n: args.topN,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('rank_people_by_icp',
+  'Rank a set of people by fit to the workspace ICP profile (title/persona match blended with company firmographics). Use after importing a list of people (e.g. LinkedIn post engagers) to surface the best-fit contacts first.',
+  {
+    personIds: z.array(z.string()),
+    topN: z.number().optional(),
+    minScore: z.number().optional(),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('rank_people_by_icp', {
+        person_ids: args.personIds,
+        top_n: args.topN,
+        min_score: args.minScore,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('check_batch_import_status',
+  'Check progress for Adrata bulk imports created by external catalog, Channel, CSV, or bulk create flows.',
+  {
+    batchId: z.string(),
+  },
+  async (args) => {
+    try {
+      return ok(await executeAiCrmTool('check_batch_import_status', {
+        batch_id: args.batchId,
+      }));
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+server.tool('move_pipeline_card',
+  'Move a person/company/opportunity card on a pipeline board and publish a realtime event so the web app can update. Requires explicit approval, reason, and idempotencyKey.',
+  {
+    entityType: z.enum(['person', 'company', 'opportunity']),
+    entityId: z.string(),
+    targetStage: z.string(),
+    targetRank: z.number().optional(),
+    previousStage: z.string().optional(),
+    entityName: z.string().optional(),
+    workspaceId: z.string().optional().describe('Defaults to ADRATA_WORKSPACE_ID or CLI config workspace. Required for realtime fan-out.'),
+    userId: z.string().optional().describe('User id for realtime attribution. Defaults to agent.'),
+    approved: z.boolean().optional(),
+    reason: z.string().optional(),
+    idempotencyKey: z.string().optional(),
+  },
+  async (args) => {
+    try {
+      const workspaceId = args.workspaceId || currentAuth().workspaceId;
+      if (!workspaceId) {
+        throw new Error('workspaceId is required for realtime board updates');
+      }
+
+      const endpointByType = {
+        person: 'people',
+        company: 'companies',
+        opportunity: 'opportunities',
+      };
+      const endpoint = endpointByType[args.entityType];
+      const customFields =
+        args.entityType === 'opportunity'
+          ? {
+              opportunityRankByStage: {
+                [args.targetStage]: args.targetRank,
+              },
+            }
+          : {
+              pipelineStage: args.targetStage,
+              ...(args.targetRank !== undefined ? { pipelineRank: args.targetRank } : {}),
+            };
+      const updateBody =
+        args.entityType === 'opportunity'
+          ? {
+              stage: args.targetStage,
+              customFields,
+            }
+          : {
+              stage: args.targetStage,
+              pipelineStage: args.targetStage,
+              customFields,
+            };
+
+      validateApiBridgeRequest({
+        method: 'PATCH',
+        path: `/api/v1/${endpoint}/${args.entityId}`,
+        dryRun: false,
+        approved: args.approved,
+        reason: args.reason,
+        idempotencyKey: args.idempotencyKey,
+      });
+
+      const result = await api('PATCH', `/api/v1/${endpoint}/${args.entityId}`, {
+        body: updateBody,
+        headers: buildMutationHeaders(args),
+      });
+      const realtimePayload = buildRealtimePayload({
+        workspaceId,
+        userId: args.userId,
+        entityType: args.entityType,
+        entityId: args.entityId,
+        entityName: args.entityName,
+        type: 'pipeline_stage_changed',
+        source: 'agent',
+        changes: {
+          previousStage: args.previousStage,
+          newStage: args.targetStage,
+          targetRank: args.targetRank,
+        },
+      });
+      const realtime = await api('POST', '/api/v1/realtime/publish', { body: realtimePayload });
+
+      return ok({
+        moved: true,
+        entityType: args.entityType,
+        entityId: args.entityId,
+        targetStage: args.targetStage,
+        targetRank: args.targetRank,
+        result,
+        realtime,
+      });
+    } catch (err) {
+      return ok({ error: true, message: err.message });
+    }
+  });
+
+// ===== FREE TIER: Claude-powered search (zero cost to Adrata) =====
+
+server.tool('find_company',
+  'Search for a company using Claude\'s training data. Returns a structured profile with industry, key people, estimated size, competitors, and sales angles. Free tier — no API key needed. For verified real-time data, upgrade to Pro.',
+  { name: z.string().describe('Company name to research (e.g. "Stripe", "Snowflake", "Datadog")') },
+  async (a) => findCompany(a.name));
+
+server.tool('find_person',
+  'Search for a professional using Claude\'s training data. Returns a structured profile with title, company, background, expertise, and sales context. Free tier — no API key needed. For verified contact info and buyer signals, upgrade to Pro.',
+  { name: z.string().describe('Full name of the person to research (e.g. "Patrick Collison", "Jensen Huang")') },
+  async (a) => findPerson(a.name));
+
+// ===== COMPANIES =====
+
+server.tool('search_companies', 'Search companies by name, domain, industry, or status. Returns customFields.',
+  { query: z.string().optional(), industry: z.string().optional(), status: z.string().optional().describe('ACTIVE, PROSPECT, CUSTOMER, CHURNED'), ...page },
+  async (a) => ok(await api('GET', '/api/v1/companies', { params: { search: a.query, industry: a.industry, status: a.status, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_company', 'Get full company details including customFields, lastAction, intelligence data.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/companies/${a.id}`)));
+
+server.tool('create_company', 'Create a new company.',
+  { name: z.string(), domain: z.string().optional(), industry: z.string().optional(), website: z.string().optional(), status: z.string().optional(), customFields: z.record(z.unknown()).optional() },
+  async (a) => ok(await api('POST', '/api/v1/companies', { body: a })));
+
+server.tool('update_company', 'Update company fields. customFields are JSONB-merged.',
+  { id: z.string(), name: z.string().optional(), industry: z.string().optional(), website: z.string().optional(), status: z.string().optional(), customFields: z.record(z.unknown()).optional() },
+  async ({ id, ...f }) => ok(await api('PATCH', `/api/v1/companies/${id}`, { body: body(f) })));
+
+server.tool('delete_company', 'Soft-delete a company.',
+  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/companies/${a.id}`); return ok({ deleted: a.id }); });
+
+server.tool('get_company_people', 'List all people at a company.',
+  { companyId: z.string(), ...page },
+  async (a) => ok(await api('GET', `/api/v1/companies/${a.companyId}/people`, { params: { limit: a.limit || 50, page: a.page || 1 } })));
+
+server.tool('get_company_opportunities', 'List all opportunities for a company.',
+  { companyId: z.string(), ...page },
+  async (a) => ok(await api('GET', `/api/v1/companies/${a.companyId}/opportunities`, { params: { limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_company_actions', 'List all actions on a company.',
+  { companyId: z.string(), ...page },
+  async (a) => ok(await api('GET', `/api/v1/companies/${a.companyId}/actions`, { params: { limit: a.limit || 25, page: a.page || 1 } })));
+
+// ===== PEOPLE / CONTACTS =====
+
+server.tool('search_people', 'Search people by name, email, company, title. Returns all statuses. Filter by contactCategory to separate real targets (Lead/Prospect) from known-but-not-a-target relationships (Introducer). Use viewMode:"leader" to read the whole team\'s records instead of only your own.',
+  {
+    query: z.string().optional(),
+    companyId: z.string().optional(),
+    status: z.string().optional().describe('LEAD, PROSPECT, CUSTOMER, ACTIVE'),
+    contactCategory: z.enum(['Lead', 'Prospect', 'Introducer']).optional()
+      .describe('Lead/Prospect appear in pipeline; Introducer is a known relationship that is deliberately excluded from pipeline.'),
+    viewMode: z.enum(['seller', 'leader']).optional()
+      .describe('seller = your own records (default). leader = the whole team\'s records; requires workspace admin.'),
+    ...page,
+  },
+  async (a) => ok(await api('GET', '/api/v1/people', { params: { search: a.query, companyId: a.companyId, status: a.status, contactCategory: a.contactCategory, viewMode: a.viewMode, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_person', 'Get full person details including customFields, lastAction, companyName.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/people/${a.id}`)));
+
+server.tool('create_person', 'Create a new person/contact. Set contactCategory:"Introducer" for someone you know who is NOT a sales target — they stay out of pipeline. Set customFields.researchOnly:true to suppress buyer-room and pursuit side effects on import.',
+  {
+    name: z.string().optional(), firstName: z.string().optional(), lastName: z.string().optional(),
+    email: z.string().optional(), phone: z.string().optional(), title: z.string().optional(),
+    companyId: z.string().optional(),
+    status: z.string().optional().describe('LEAD, PROSPECT, CUSTOMER'),
+    contactCategory: z.enum(['Lead', 'Prospect', 'Introducer']).optional()
+      .describe('Lead/Prospect enter pipeline; Introducer is a known relationship kept out of pipeline. Default to Introducer for bulk relationship imports.'),
+    linkedinUrl: z.string().optional(),
+    customFields: z.record(z.unknown()).optional()
+      .describe('Set researchOnly:true to suppress automatic Room creation and pursuit side effects.'),
+  },
+  async (a) => ok(await api('POST', '/api/v1/people', { body: a })));
+
+server.tool('update_person', 'Update person fields. customFields are JSONB-merged. Works for leads too. Change contactCategory to move someone between pipeline (Lead/Prospect) and known-relationship-only (Introducer).',
+  { id: z.string(), name: z.string().optional(), firstName: z.string().optional(), lastName: z.string().optional(), email: z.string().optional(), title: z.string().optional(), phone: z.string().optional(), status: z.string().optional(), contactCategory: z.enum(['Lead', 'Prospect', 'Introducer']).optional().describe('Lead/Prospect enter pipeline; Introducer is kept out of pipeline.'), linkedinUrl: z.string().optional(), customFields: z.record(z.unknown()).optional() },
+  async ({ id, ...f }) => ok(await api('PATCH', `/api/v1/people/${id}`, { body: body(f) })));
+
+server.tool('delete_person', 'Soft-delete a person.',
+  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/people/${a.id}`); return ok({ deleted: a.id }); });
+
+// ===== OPPORTUNITIES =====
+
+server.tool('search_opportunities', 'Search deals by name, stage, company, or owner.',
+  { query: z.string().optional(), companyId: z.string().optional(), stage: z.string().optional().describe('Discovery, Qualification, Proposal, Negotiation, Closed Won, Closed Lost'), ownerId: z.string().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/opportunities', { params: { search: a.query, companyId: a.companyId, stage: a.stage, ownerId: a.ownerId, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_opportunity', 'Get full opportunity details including stage, amount, customFields.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/opportunities/${a.id}`)));
+
+server.tool('create_opportunity', 'Create a new deal.',
+  { name: z.string(), companyId: z.string().optional(), amount: z.number().optional(), stage: z.string().optional(), probability: z.number().optional(), closeDate: z.string().optional(), ownerId: z.string().optional(), customFields: z.record(z.unknown()).optional() },
+  async (a) => ok(await api('POST', '/api/v1/opportunities', { body: a })));
+
+server.tool('update_opportunity', 'Update deal fields. customFields are JSONB-merged.',
+  { id: z.string(), name: z.string().optional(), amount: z.number().optional(), stage: z.string().optional(), probability: z.number().optional(), closeDate: z.string().optional(), customFields: z.record(z.unknown()).optional() },
+  async ({ id, ...f }) => ok(await api('PATCH', `/api/v1/opportunities/${id}`, { body: body(f) })));
+
+server.tool('delete_opportunity', 'Delete an opportunity.',
+  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/opportunities/${a.id}`); return ok({ deleted: a.id }); });
+
+// ===== ACTIONS =====
+
+server.tool('create_action', 'Log an action (outreach, call, meeting, note) against a person or company. Metadata is JSONB for type-specific data.',
+  { title: z.string(), type: z.string().optional().describe('email, call, meeting, note, linkedin_connection_request, linkedin_message, task'), personId: z.string().optional(), companyId: z.string().optional(), status: z.string().optional().describe('PLANNED, IN_PROGRESS, COMPLETED'), priority: z.string().optional().describe('LOW, NORMAL, HIGH, URGENT'), dueDate: z.string().optional(), outcome: z.string().optional(), metadata: z.record(z.unknown()).optional(), assignedTo: z.string().optional() },
+  async (a) => ok(await api('POST', '/api/v1/actions', { body: a })));
+
+server.tool('list_actions', 'List actions with filters. Use to answer "what did X do this week?" Use viewMode:"leader" to see the whole team\'s activity rather than only your own.',
+  { status: z.string().optional(), type: z.string().optional(), personId: z.string().optional(), companyId: z.string().optional(), assignedTo: z.string().optional(), priority: z.string().optional(), sortBy: z.string().optional(), sortOrder: z.string().optional(), viewMode: z.enum(['seller', 'leader']).optional().describe('seller = your own actions (default). leader = the whole team\'s actions; requires workspace admin.'), ...page },
+  async ({ sortBy, sortOrder, assignedTo, viewMode, ...r }) => ok(await api('GET', '/api/v1/actions', { params: { ...r, assigned_to: assignedTo, viewMode, sort_by: sortBy, sort_order: sortOrder, limit: r.limit || 25, page: r.page || 1 } })));
+
+server.tool('get_action', 'Get full action details including metadata.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/actions/${a.id}`)));
+
+server.tool('update_action', 'Update an action. Metadata is JSONB-merged.',
+  { id: z.string(), title: z.string().optional(), type: z.string().optional(), status: z.string().optional(), priority: z.string().optional(), dueDate: z.string().optional(), outcome: z.string().optional(), metadata: z.record(z.unknown()).optional() },
+  async ({ id, ...f }) => ok(await api('PUT', `/api/v1/actions/${id}`, { body: body(f) })));
+
+server.tool('complete_action', 'Mark action as completed with optional outcome.',
+  { id: z.string(), outcome: z.string().optional() },
+  async ({ id, outcome }) => { if (outcome) await api('PUT', `/api/v1/actions/${id}`, { body: { outcome } }); return ok(await api('POST', `/api/v1/actions/${id}/complete`)); });
+
+server.tool('delete_action', 'Soft-delete an action.',
+  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/actions/${a.id}`); return ok({ deleted: a.id }); });
+
+server.tool('list_overdue_actions', 'List actions past their due date.',
+  page, async (a) => ok(await api('GET', '/api/v1/actions/overdue', { params: { limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('list_today_actions', 'List actions scheduled for today.',
+  page, async (a) => ok(await api('GET', '/api/v1/actions/today', { params: { limit: a.limit || 25, page: a.page || 1 } })));
+
+// ===== NOTES =====
+
+// The notes column is `content` (renamed from `body` by
+// 20260227_fix_schema_mismatches.sql). These tools kept sending `body`, which
+// the API bound nowhere: create failed validation and update was a silent
+// no-op that still answered 200. Send `content` and keep accepting `body` as
+// the tool-facing argument name so existing agent prompts keep working.
+server.tool('create_note', 'Add a note to a person, company, or opportunity.',
+  { body: z.string().describe('The note text.'), companyId: z.string().optional(), personId: z.string().optional(), opportunityId: z.string().optional() },
+  async ({ body: text, ...rest }) => ok(await api('POST', '/api/v1/notes', { body: { content: text, ...rest } })));
+
+server.tool('list_notes', 'List notes, filterable by entity.',
+  { companyId: z.string().optional(), personId: z.string().optional(), opportunityId: z.string().optional(), search: z.string().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/notes', { params: { ...a, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('update_note', 'Update note content.',
+  { id: z.string(), body: z.string().describe('The new note text.') },
+  async (a) => ok(await api('PUT', `/api/v1/notes/${a.id}`, { body: { content: a.body } })));
+
+server.tool('delete_note', 'Delete a note.',
+  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/notes/${a.id}`); return ok({ deleted: a.id }); });
+
+// ===== BUYER GROUPS =====
+//
+// Buyer groups ARE buyer rooms: the room record cascades to every member seat.
+// Reads below are unchanged. Every WRITE goes through `governedWrite`, the
+// same dryRun/approved/reason/idempotencyKey contract `adrata_api_request`
+// enforces — before this, the typed tools bypassed it entirely and were the
+// least governed path to the most destructive operation in the toolset.
+
+/** Governance fields every buyer-group write tool accepts. */
+const governedWriteArgs = {
+  dryRun: z.boolean().optional().describe('Defaults to true. Returns a preview of the exact call instead of performing it. Set false to execute.'),
+  approved: z.boolean().optional().describe('Required (true) for a live write. Records that the caller confirmed the mutation; it does not by itself grant scope.'),
+  reason: z.string().optional().describe('Required for a live write. Recorded as the audit reason (X-Adrata-Reason).'),
+  idempotencyKey: z.string().optional().describe('Required for a live write. Sent as Idempotency-Key so a retry cannot double-apply.'),
+};
+
+const GOVERNED_WRITE_NOTE =
+  ' Governed write: previews by default. A live write requires dryRun:false plus approved:true, a reason, and an idempotencyKey, and the connection must hold write:buyer-groups (connect_workspace with writeAccess:true).';
+
+/** Shared handler shape: preview object on a dry run, tool payload on a live write. */
+async function runGovernedBuyerGroupWrite(args, request, onSuccess) {
+  try {
+    const outcome = await governedWrite(api, args, request);
+    if (outcome.dryRun) return ok(outcome.preview);
+    return ok(onSuccess(outcome.result));
+  } catch (err) {
+    return ok({ error: true, message: err.message });
+  }
+}
+
+server.tool('list_buyer_groups', 'List buyer groups — the decision-making units at companies.',
+  { companyId: z.string().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/buyer-group', { params: { companyId: a.companyId, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_buyer_group', 'Get buyer group details including members and roles.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/buyer-group/${a.id}`)));
+
+server.tool('create_buyer_group', `Create a buyer group for a company.${GOVERNED_WRITE_NOTE}`,
+  { name: z.string(), companyId: z.string(), ...governedWriteArgs },
+  async (a) => runGovernedBuyerGroupWrite(
+    a,
+    { method: 'POST', path: '/api/v1/buyer-group', body: { name: a.name, companyId: a.companyId } },
+    (result) => result,
+  ));
+
+server.tool('add_buyer_group_member', `Add a person to a buyer group.${GOVERNED_WRITE_NOTE}`,
+  {
+    buyerGroupId: z.string(),
+    personId: z.string(),
+    role: z.string().optional().describe('Champion, Decision Maker, Influencer, Blocker, End User'),
+    ...governedWriteArgs,
+  },
+  async (a) => runGovernedBuyerGroupWrite(
+    a,
+    {
+      method: 'POST',
+      path: `/api/v1/buyer-group/${a.buyerGroupId}/members`,
+      body: { personId: a.personId, role: a.role },
+    },
+    (result) => result,
+  ));
+
+server.tool('get_buyer_group_members', 'List members of a buyer group with roles.',
+  { buyerGroupId: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/buyer-group/${a.buyerGroupId}/members`)));
+
+server.tool('update_buyer_group', `Update a buyer group’s name or the company it belongs to.${GOVERNED_WRITE_NOTE}`,
+  { id: z.string(), name: z.string().optional(), companyId: z.string().optional(), ...governedWriteArgs },
+  async (a) => runGovernedBuyerGroupWrite(
+    a,
+    { method: 'PUT', path: `/api/v1/buyer-group/${a.id}`, body: body({ name: a.name, companyId: a.companyId }) },
+    (result) => result,
+  ));
+
+server.tool('update_buyer_group_member', `Update a member’s role or influence inside a buyer group.${GOVERNED_WRITE_NOTE}`,
+  {
+    buyerGroupId: z.string(),
+    memberId: z.string(),
+    role: z.string().optional().describe('Champion, Decision Maker, Influencer, Blocker, End User'),
+    influenceScore: z.number().optional(),
+    personId: z.string().optional().describe('Link the seat to an existing person record'),
+    ...governedWriteArgs,
+  },
+  async (a) => runGovernedBuyerGroupWrite(
+    a,
+    {
+      method: 'PUT',
+      path: `/api/v1/buyer-group/${a.buyerGroupId}/members/${a.memberId}`,
+      body: body({ role: a.role, influenceScore: a.influenceScore, personId: a.personId }),
+    },
+    (result) => result,
+  ));
+
+server.tool('remove_buyer_group_member',
+  `Remove one person from a buyer group. Does NOT delete the underlying person record. To remove the whole room, use delete_buyer_group instead — it cascades.${GOVERNED_WRITE_NOTE}`,
+  { buyerGroupId: z.string(), memberId: z.string(), ...governedWriteArgs },
+  async (a) => runGovernedBuyerGroupWrite(
+    a,
+    { method: 'DELETE', path: `/api/v1/buyer-group/${a.buyerGroupId}/members/${a.memberId}` },
+    () => ({ removed: a.memberId, buyerGroupId: a.buyerGroupId }),
+  ));
+
+server.tool('delete_buyer_group',
+  `Soft-delete an entire buyer group (buyer room). CASCADES to every member seat in the room, so you do not need to empty it first. Does NOT delete the underlying people or the company.${GOVERNED_WRITE_NOTE}`,
+  { id: z.string(), ...governedWriteArgs },
+  async (a) => runGovernedBuyerGroupWrite(
+    a,
+    { method: 'DELETE', path: `/api/v1/buyer-group/${a.id}`, preview: { cascade: 'members' } },
+    () => ({ deleted: a.id, cascade: 'members' }),
+  ));
+
+server.tool('bulk_delete_buyer_groups',
+  'Soft-delete up to 50 buyer groups in ONE call, each cascading to its members. Use this instead of looping delete_buyer_group when cleaning many rooms out of a workspace.'
+  + ' STRICTEST GATE IN THIS TOOLSET: on top of the governed-write contract (dryRun:false, approved:true, reason, idempotencyKey) a live call must pass confirmCount equal to the number of distinct ids being deleted, so a widened list cannot ride along on an approval given for a smaller one.',
+  {
+    ids: z.array(z.string()).min(1).max(50).describe('Buyer group IDs (max 50 per call)'),
+    confirmCount: z.number().int().optional().describe('Required for a live write. Must equal the number of DISTINCT ids in this call.'),
+    ...governedWriteArgs,
+  },
+  async (a) => {
+    // Dedupe first: the count the caller confirms must be the count of rooms
+    // that actually get deleted, not the length of a list with repeats.
+    const ids = [...new Set(a.ids)];
+    const isLiveWrite = a.dryRun === false;
+    if (isLiveWrite && a.confirmCount !== ids.length) {
+      return ok({
+        error: true,
+        message: `bulk delete refused: confirmCount must equal the ${ids.length} distinct id(s) in this call, got ${a.confirmCount === undefined ? 'nothing' : a.confirmCount}`,
+        distinctIds: ids.length,
+      });
+    }
+    return runGovernedBuyerGroupWrite(
+      a,
+      {
+        method: 'DELETE',
+        path: '/api/v1/buyer-group/bulk',
+        body: { ids },
+        preview: { distinctIds: ids.length, cascade: 'members', requiresConfirmCount: ids.length },
+      },
+      (result) => result,
+    );
+  });
+
+server.tool('get_access_score', 'Get the deterministic Access Score for a buyer group, including sub-scores, risk level, top gaps, and provenance.',
+  { buyerGroupId: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/buyer-group/${a.buyerGroupId}/access-score`)));
+
+server.tool('get_access_graph_projection', 'Inspect the access graph for a buyer group: buyer group coverage plus intro group routes and touchpoints.',
+  { buyerGroupId: z.string().describe('Buyer group ID') },
+  async (a) => ok(await api('GET', `/api/v1/network-graph/projection/buyer-group/${a.buyerGroupId}`)));
+
+server.tool('get_path_to_power', 'Rank safe, reviewable routes to decision authority for a buyer group, including rationale, next actions, and drafts.',
+  { buyerGroupId: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/buyer-group/${a.buyerGroupId}/path-to-power`)));
+
+// ===== COMPANY LISTS / SAVED ACCOUNT LISTS =====
+
+server.tool('list_company_lists', 'List saved company/account lists in Adrata. Use before adding companies to an existing target list.',
+  { type: z.string().optional().describe('Optional list type filter'), ...page },
+  async (a) => ok(await api('GET', '/api/v1/company-lists', { params: { type: a.type, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('create_company_list', 'Create and save a company/account list in Adrata, optionally with company IDs from search or research results.',
+  { name: z.string(), description: z.string().optional(), type: z.string().optional(), companyIds: z.array(z.string()).optional() },
+  async ({ companyIds, ...list }) => {
+    const created = await api('POST', '/api/v1/company-lists', { body: list });
+    const listId = created?.data?.id || created?.id;
+    if (listId && Array.isArray(companyIds) && companyIds.length > 0) {
+      await api('POST', `/api/v1/company-lists/${listId}/add`, { body: { companyIds } });
+    }
+    return ok({ ...created, companyIds: companyIds || [] });
+  });
+
+server.tool('get_company_list', 'Get a saved company/account list with its companies.',
+  { companyListId: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/company-lists/${a.companyListId}`)));
+
+server.tool('add_to_company_list', 'Add company IDs to an existing saved company/account list.',
+  { companyListId: z.string(), companyIds: z.array(z.string()) },
+  async (a) => ok(await api('POST', `/api/v1/company-lists/${a.companyListId}/add`, { body: { companyIds: a.companyIds } })));
+
+// ===== PARTNER ECOSYSTEM =====
+// Partners are typed relationships (ISV/tech, AI lab, hyperscaler, GSI/SI,
+// reseller, marketplace) across motions (co-sell, resell, sell-to, build-with,
+// refer). Attribution splits STRATEGIC (incremental revenue you would not get
+// without the partner) from INFLUENCED (facilitation). "Channel" = the resell
+// motion only.
+
+server.tool('list_partners', 'List partners in the workspace. Filter by partnerType (ISV_TECH, AI_LAB, HYPERSCALER, GSI_SI, RESELLER, MARKETPLACE, ADVISORY, REFERRAL, COMMUNITY) or status (PROSPECT, ONBOARDING, ACTIVE, DORMANT, CHURNED).',
+  { partnerType: z.string().optional(), status: z.string().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/partnerships', { params: { partnerType: a.partnerType, status: a.status, limit: a.limit || 50, offset: ((a.page || 1) - 1) * (a.limit || 50) } })));
+
+server.tool('get_partner', 'Get a single partner with its full profile (type, tier, motions, commitment, target incremental ARR).',
+  { id: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/partnerships/${a.id}`)));
+
+server.tool('create_partner', 'Create a partner relationship. partnerType is required (ISV_TECH, AI_LAB, HYPERSCALER, GSI_SI, RESELLER, MARKETPLACE, ADVISORY, REFERRAL, COMMUNITY). The authenticated user becomes owner unless ownerId is explicitly supplied. motions is an array of CO_SELL, RESELL, SELL_TO, BUILD_WITH, REFER.',
+  { name: z.string(), partnerType: z.string(), companyId: z.string().optional(), tier: z.string().optional().describe('STRATEGIC, SELECT, MANAGED, LONGTAIL'), status: z.string().optional(), motions: z.array(z.string()).optional(), ownerId: z.string().optional(), regions: z.array(z.string()).optional(), commitmentAmount: z.number().optional(), targetIncrementalArr: z.number().optional(), website: z.string().optional(), industry: z.string().optional(), description: z.string().optional() },
+  async (a) => ok(await api('POST', '/api/v1/partnerships', { body: a })));
+
+server.tool('update_partner', 'Update partner fields (type, tier, status, motions, owner, commitment, target ARR).',
+  { id: z.string(), name: z.string().optional(), partnerType: z.string().optional(), tier: z.string().optional(), status: z.string().optional(), motions: z.array(z.string()).optional(), ownerId: z.string().optional(), regions: z.array(z.string()).optional(), commitmentAmount: z.number().optional(), targetIncrementalArr: z.number().optional(), website: z.string().optional(), industry: z.string().optional(), description: z.string().optional() },
+  async ({ id, ...f }) => ok(await api('PUT', `/api/v1/partnerships/${id}`, { body: body(f) })));
+
+server.tool('delete_partner', 'Soft-delete a partner relationship.',
+  { id: z.string() }, async (a) => { await api('DELETE', `/api/v1/partnerships/${a.id}`); return ok({ deleted: a.id }); });
+
+server.tool('rank_partners_for_account', 'Rank the partners best positioned to break into a target account. Returns an explainable break-in probability (0..1) per partner with reasons, blending relationship strength, tier, industry fit, co-sell/referral motions, committed-spend leverage, and prior strategic wins. Use to answer "which partner gets me into / strategic NAR on this account".',
+  { accountId: z.string().describe('The target company/account id to break into'), limit: z.number().optional() },
+  async (a) => ok(await api('GET', '/api/v1/partnerships/rank', { params: { accountId: a.accountId, limit: a.limit || 10 } })));
+
+server.tool('get_partner_revenue', 'Get a partner\'s strategic-revenue rollup: strategic vs influenced incremental ARR (weighted) and deal counts. This is the "without partner X, with partner X + 25%" number.',
+  { id: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/partnerships/${a.id}/revenue`)));
+
+server.tool('attribute_partner_to_deal', 'Credit a partner on an opportunity. attributionType is STRATEGIC (incremental revenue not won without the partner) or INFLUENCED (facilitation). motion: co_sell, joint_solution, services_delivery, funding, intro, information_sharing, marketplace, reference. MONEY WRITE: dry-run by default (returns a preview); live execution requires approved:true, a non-empty auditReason, and an idempotencyKey.',
+  { opportunityId: z.string(), partnerId: z.string(), attributionType: z.enum(['strategic', 'influenced']), motion: z.string().optional(), incrementalAmount: z.number().optional(), evidence: z.record(z.unknown()).optional(), confidence: z.number().optional(), ...moneyWrite },
+  async ({ dryRun, approved, auditReason, idempotencyKey, ...f }) => ok(await executeMoneyWrite(api, {
+    tool: 'attribute_partner_to_deal',
+    path: '/api/v1/partnerships/attributions',
+    payload: body({ ...f, auditReason }),
+    dryRun, approved, auditReason, idempotencyKey,
+  })));
+
+server.tool('list_partner_attributions', `List every partner attribution on an opportunity (who drove strategic vs influenced revenue). The API route has no pagination; limit/offset are applied client-side by this tool (default cap ${CLIENT_PAGE_CAP} rows).`,
+  { opportunityId: z.string(), limit: z.number().optional().describe(`Max rows returned (client-side cap, default ${CLIENT_PAGE_CAP})`), offset: z.number().optional().describe('Rows to skip (client-side)') },
+  async (a) => {
+    const res = await api('GET', '/api/v1/partnerships/attributions', { params: { opportunityId: a.opportunityId } });
+    const { rows, page: pageInfo } = capClientSide(res?.data, a);
+    return ok(pageInfo ? { ...res, data: rows, page: pageInfo } : res);
+  });
+
+server.tool('approve_partner_attribution', 'Approve a partner attribution (finance/ops sign-off). Writes an immutable audit row so strategic revenue stays defensible. MONEY WRITE: dry-run by default (returns a preview); live execution requires approved:true, a non-empty auditReason, and an idempotencyKey.',
+  { attributionId: z.string(), ...moneyWrite },
+  async ({ attributionId, dryRun, approved, auditReason, idempotencyKey }) => ok(await executeMoneyWrite(api, {
+    tool: 'approve_partner_attribution',
+    path: `/api/v1/partnerships/attributions/${attributionId}/approve`,
+    dryRun, approved, auditReason, idempotencyKey,
+  })));
+
+server.tool('create_strategic_work_stream', 'Create a programmatic joint initiative with a partner ("revenue while you sleep"). streamType: JOINT_SOLUTION, PARTNER_PROGRAM, MARKETPLACE_LISTING, CO_SELL_MOTION, CENTER_OF_EXCELLENCE.',
+  { partnerId: z.string(), name: z.string(), streamType: z.string(), description: z.string().optional(), industry: z.string().optional(), useCase: z.string().optional(), region: z.string().optional(), targetIncrementalArr: z.number().optional(), leadsPerQuarter: z.number().optional(), fundingAmount: z.number().optional() },
+  async ({ partnerId, ...f }) => ok(await api('POST', `/api/v1/partnerships/${partnerId}/work-streams`, { body: f })));
+
+server.tool('list_strategic_work_streams', `List a partner's strategic work streams (joint solutions, programs, marketplace listings) with target vs generated ARR. The API route has no pagination; limit/offset are applied client-side by this tool (default cap ${CLIENT_PAGE_CAP} rows).`,
+  { partnerId: z.string(), limit: z.number().optional().describe(`Max rows returned (client-side cap, default ${CLIENT_PAGE_CAP})`), offset: z.number().optional().describe('Rows to skip (client-side)') },
+  async (a) => {
+    const res = await api('GET', `/api/v1/partnerships/${a.partnerId}/work-streams`);
+    const { rows, page: pageInfo } = capClientSide(res?.data, a);
+    return ok(pageInfo ? { ...res, data: rows, page: pageInfo } : res);
+  });
+
+server.tool('create_executive_partner_meeting', 'Log an Executive Partner Meeting (EPM) — the partner analog of a new-business meeting. Capture the mutual engagement that should lead to strategic revenue.',
+  { partnerId: z.string(), title: z.string().optional(), scheduledAt: z.string().optional().describe('RFC3339'), executiveName: z.string().optional(), executiveTitle: z.string().optional(), mutualEngagement: z.string().optional(), expectedStrategicArr: z.number().optional(), notes: z.string().optional() },
+  async ({ partnerId, ...f }) => ok(await api('POST', `/api/v1/partnerships/${partnerId}/epms`, { body: f })));
+
+server.tool('list_executive_partner_meetings', `List a partner's Executive Partner Meetings (EPMs). The API route has no pagination; limit/offset are applied client-side by this tool (default cap ${CLIENT_PAGE_CAP} rows).`,
+  { partnerId: z.string(), limit: z.number().optional().describe(`Max rows returned (client-side cap, default ${CLIENT_PAGE_CAP})`), offset: z.number().optional().describe('Rows to skip (client-side)') },
+  async (a) => {
+    const res = await api('GET', `/api/v1/partnerships/${a.partnerId}/epms`);
+    const { rows, page: pageInfo } = capClientSide(res?.data, a);
+    return ok(pageInfo ? { ...res, data: rows, page: pageInfo } : res);
+  });
+
+server.tool('record_partner_consumption', 'Record committed vs consumed revenue for a partner over a period. Signature != revenue: in a consumption business revenue is realized as usage grows, and partners drive it. driver: services_delivery, marketplace, self_serve, center_of_excellence. MONEY WRITE: dry-run by default (returns a preview); live execution requires approved:true, a non-empty auditReason, and an idempotencyKey.',
+  { partnerId: z.string(), opportunityId: z.string().optional(), companyId: z.string().optional(), periodLabel: z.string().optional().describe('e.g. 2026-Q3, FY26'), committedAmount: z.number().optional(), consumedAmount: z.number().optional(), driver: z.string().optional(), notes: z.string().optional(), ...moneyWrite },
+  async ({ partnerId, dryRun, approved, auditReason, idempotencyKey, ...f }) => ok(await executeMoneyWrite(api, {
+    tool: 'record_partner_consumption',
+    path: `/api/v1/partnerships/${partnerId}/consumption`,
+    payload: body(f),
+    dryRun, approved, auditReason, idempotencyKey,
+  })));
+
+server.tool('list_partner_consumption', `List a partner's consumption records (committed vs consumed per period). The API route has no pagination; limit/offset are applied client-side by this tool (default cap ${CLIENT_PAGE_CAP} rows).`,
+  { partnerId: z.string(), limit: z.number().optional().describe(`Max rows returned (client-side cap, default ${CLIENT_PAGE_CAP})`), offset: z.number().optional().describe('Rows to skip (client-side)') },
+  async (a) => {
+    const res = await api('GET', `/api/v1/partnerships/${a.partnerId}/consumption`);
+    const { rows, page: pageInfo } = capClientSide(res?.data, a);
+    return ok(pageInfo ? { ...res, data: rows, page: pageInfo } : res);
+  });
+
+server.tool('get_partner_consumption_rollup', 'Get a partner\'s committed-vs-consumed rollup with realization rate — the realized-revenue view (vs bookings).',
+  { partnerId: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/partnerships/${a.partnerId}/consumption/rollup`)));
+
+// ===== NETWORK / WARM INTROS =====
+
+server.tool('list_intro_requests', 'List tracked warm introduction requests by status or direction.',
+  { status: z.string().optional().describe('pending, accepted, declined, completed'), direction: z.string().optional().describe('sent, received, all'), ...page },
+  async (a) => ok(await api('GET', '/api/v1/network/intro-requests', { params: { status: a.status, direction: a.direction, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_intro_pipeline', 'Get the warm intro pipeline organized by stage. Use for managing intro workflow across connectors and targets.',
+  {},
+  async () => ok(await api('GET', '/api/v1/network/intro-pipeline')));
+
+server.tool('create_intro_request', 'Create a tracked warm introduction request between a connector and target.',
+  {
+    introducerUserId: z.string().describe('User ID for the connector who can make the introduction'),
+    targetPersonId: z.string().describe('Person ID for the target buyer or prospect'),
+    reason: z.string().describe('Why the intro is valuable and what context the connector should know'),
+    opportunityId: z.string().optional(),
+    companyId: z.string().optional(),
+    metadata: z.record(z.unknown()).optional(),
+  },
+  async (a) => ok(await api('POST', '/api/v1/network/intro-request', { body: a })));
+
+server.tool('update_intro_request', 'Update the status or connector notes on a warm introduction request.',
+  {
+    id: z.string().describe('Intro request ID'),
+    status: z.string().optional().describe('accepted, declined, completed, cancelled'),
+    connectorNotes: z.string().optional(),
+    meetingLink: z.string().optional(),
+    metadata: z.record(z.unknown()).optional(),
+  },
+  async ({ id, ...f }) => ok(await api('PATCH', `/api/v1/network/intro-request/${id}`, { body: body(f) })));
+
+server.tool('find_intro_path', 'Find the relationship path between two people for warm intro planning.',
+  { source: z.string().describe('Source person ID'), target: z.string().describe('Target person ID') },
+  async (a) => ok(await api('GET', `/api/v1/network/path/${a.source}/${a.target}`)));
+
+server.tool('get_network_stats', 'Get network coverage, relationship strength, and warm intro health metrics.',
+  {},
+  async () => ok(await api('GET', '/api/v1/network/stats')));
+
+// ===== AGENT TASKS =====
+
+server.tool('list_agent_tasks', 'List long-running agent/background tasks with status and progress.',
+  { status: z.string().optional().describe('queued, running, completed, failed, cancelled'), type: z.string().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/agent-tasks', { params: { status: a.status, type: a.type, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('create_agent_task', 'Create a long-running agent/background task for research, enrichment, auditing, or custom workflow automation.',
+  {
+    type: z.string().describe('Task type such as account_research, lead_enrichment, sequence_optimization, pipeline_review, or custom'),
+    title: z.string().optional(),
+    description: z.string().optional(),
+    config: z.record(z.unknown()).optional(),
+  },
+  async (a) => ok(await api('POST', '/api/v1/agent-tasks', { body: a })));
+
+server.tool('get_agent_task', 'Get detail, progress, and result for a long-running agent/background task.',
+  { id: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/agent-tasks/${a.id}`)));
+
+server.tool('cancel_agent_task', 'Cancel a queued or running agent/background task.',
+  { id: z.string() },
+  async (a) => ok(await api('DELETE', `/api/v1/agent-tasks/${a.id}`)));
+
+// ===== WEBHOOKS =====
+
+server.tool('list_webhook_events', 'List supported outbound webhook event types, payload schemas, and examples.',
+  {},
+  async () => ok(await api('GET', '/api/v1/webhooks/events')));
+
+server.tool('list_webhooks', 'List outbound webhook subscriptions for the workspace.',
+  { event: z.string().optional(), active: z.boolean().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/webhooks', { params: { event: a.event, active: a.active, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('create_webhook', 'Create an outbound webhook subscription. Returns the signing secret once; store it securely.',
+  {
+    url: z.string().describe('Public HTTPS endpoint URL'),
+    events: z.array(z.string()).describe('Webhook event types from list_webhook_events'),
+    active: z.boolean().optional(),
+    description: z.string().optional(),
+    filterExpression: z.record(z.unknown()).optional(),
+  },
+  async ({ filterExpression, ...f }) => ok(await api('POST', '/api/v1/webhooks', { body: body({ ...f, filter_expression: filterExpression }) })));
+
+server.tool('update_webhook', 'Update an outbound webhook subscription URL, events, active flag, description, or filter expression.',
+  {
+    id: z.string().describe('Webhook subscription ID'),
+    url: z.string().optional(),
+    events: z.array(z.string()).optional(),
+    active: z.boolean().optional(),
+    description: z.string().optional(),
+    filterExpression: z.record(z.unknown()).optional(),
+  },
+  async ({ id, filterExpression, ...f }) => ok(await api('PUT', `/api/v1/webhooks/${id}`, { body: body({ ...f, filter_expression: filterExpression }) })));
+
+server.tool('delete_webhook', 'Delete an outbound webhook subscription.',
+  { id: z.string().describe('Webhook subscription ID') },
+  async (a) => ok(await api('DELETE', `/api/v1/webhooks/${a.id}`)));
+
+server.tool('test_webhook', 'Queue a signed webhook.test delivery to validate a subscription endpoint.',
+  { id: z.string().describe('Webhook subscription ID') },
+  async (a) => ok(await api('POST', `/api/v1/webhooks/${a.id}/test`)));
+
+server.tool('list_webhook_deliveries', 'List recent delivery attempts for a webhook subscription.',
+  { id: z.string().describe('Webhook subscription ID'), ...page },
+  async (a) => ok(await api('GET', `/api/v1/webhooks/${a.id}/deliveries`, { params: { limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_webhook_delivery', 'Get status, response body, and retry metadata for a webhook delivery attempt.',
+  { id: z.string().describe('Webhook subscription ID'), deliveryId: z.string().describe('Webhook delivery ID') },
+  async (a) => ok(await api('GET', `/api/v1/webhooks/${a.id}/deliveries/${a.deliveryId}`)));
+
+server.tool('replay_webhook_delivery', 'Replay a failed or previous webhook delivery.',
+  { id: z.string().describe('Webhook subscription ID'), deliveryId: z.string().describe('Webhook delivery ID') },
+  async (a) => ok(await api('POST', `/api/v1/webhooks/${a.id}/deliveries/${a.deliveryId}/replay`)));
+
+// ===== LEADS =====
+
+server.tool('search_leads', 'Search leads (people with status=LEAD). To update, use update_person.',
+  { query: z.string().optional(), source: z.string().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/leads', { params: { search: a.query, source: a.source, limit: a.limit || 25, page: a.page || 1 } })));
+
+// ===== EMAILS =====
+
+server.tool('search_emails', 'Search emails by subject, sender, recipient, or folder.',
+  { query: z.string().optional(), folder: z.string().optional().describe('inbox, sent, drafts, trash'), personId: z.string().optional(), companyId: z.string().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/emails', { params: { search: a.query, folder: a.folder, personId: a.personId, companyId: a.companyId, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_email', 'Get full email content by ID.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/emails/${a.id}`)));
+
+server.tool('count_emails', 'Count emails by folder or status.',
+  { folder: z.string().optional() },
+  async (a) => ok(await api('GET', '/api/v1/emails/count', { params: { folder: a.folder } })));
+
+// ===== MEETINGS =====
+
+// Meetings are read from the calendar `events` store, not the AI meeting-copilot
+// `meetings`/transcript tables (which only fill in once a call is recorded and
+// transcribed). "List my meetings" / "who is in my meetings" must return the
+// caller's real calendar events with titles, times, and attendee rosters, so
+// these point at `/api/v1/events` (rosters are backfilled from event_attendees
+// by the events read path). The copilot summary/action-item tools below stay on
+// `/api/v1/meetings` since those artifacts only exist for recorded meetings.
+server.tool('list_meetings', 'List your meetings (calendar events) with optional filters.',
+  { upcoming: z.boolean().optional(), personId: z.string().optional(), companyId: z.string().optional(), ...page },
+  async (a) => ok(await api('GET', '/api/v1/events', { params: { start_date: a.upcoming ? new Date().toISOString() : undefined, person_id: a.personId, company_id: a.companyId, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_meeting', 'Get meeting (calendar event) details, including the attendee roster.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/events/${a.id}`)));
+
+server.tool('get_meeting_summary', 'Get AI summary of a meeting.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/meetings/${a.id}/summary`)));
+
+server.tool('get_meeting_action_items', 'Get action items from a meeting.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/meetings/${a.id}/action-items`)));
+
+// ===== INTELLIGENCE =====
+
+server.tool('enrich_company', 'Trigger enrichment for a company — firmographic, news, competitors.',
+  { companyId: z.string() },
+  async (a) => ok(await api('POST', `/api/v1/companies/${a.companyId}/enrich`)));
+
+server.tool('get_company_firmographics', 'Get employee count and revenue metadata for a company, including value/range, source, confidence, freshness, and missing fields.',
+  { companyId: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/companies/${a.companyId}/firmographics`)));
+
+server.tool('enrich_person', 'Trigger enrichment for a person — professional info, social profiles.',
+  { personId: z.string() },
+  async (a) => ok(await api('POST', `/api/v1/people/${a.personId}/enrich`)));
+
+server.tool('get_intent_signals', 'Get buying intent signals for a company.',
+  { companyId: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/intent-signals`, { params: { companyId: a.companyId } })));
+
+// First-party signal store — the canonical customer_signals table the live
+// plays actually fire from (webhook ingest, manual logs, BYOK adapters). This
+// is distinct from get_intent_signals, which returns third-party intent. Reads
+// are workspace-scoped from the token; filter by subject (a company or person),
+// source, signal type, or minimum score, and page with the returned cursor.
+server.tool('list_customer_signals',
+  'List first-party customer signals (the store live plays fire from) for the workspace, or scope to one company/person via subjectType + subjectId. Distinct from get_intent_signals (third-party intent).',
+  {
+    subjectType: z.enum(['company', 'person']).optional().describe('Scope to a subject kind; pair with subjectId'),
+    subjectId: z.string().optional().describe('Company or person ID to scope signals to'),
+    source: z.string().optional().describe('Filter by ingest source, e.g. linkedin_engager'),
+    signalType: z.string().optional().describe('Filter by signal type'),
+    minScore: z.number().optional().describe('Only signals at or above this score'),
+    since: z.string().optional().describe('ISO timestamp lower bound on observed_at'),
+    until: z.string().optional().describe('ISO timestamp upper bound on observed_at'),
+    limit: z.number().optional().describe('Page size (default 50, max 500)'),
+    cursor: z.string().optional().describe('Opaque cursor from a previous page'),
+  },
+  async (a) => ok(await api('GET', '/api/v1/customer-signals', { params: {
+    subjectType: a.subjectType, subjectId: a.subjectId, source: a.source,
+    signalType: a.signalType, minScore: a.minScore, since: a.since,
+    until: a.until, limit: a.limit || 50, cursor: a.cursor,
+  } })));
+
+server.tool('get_deal_authority', 'Get authority mapping and stakeholder analysis for a deal.',
+  { opportunityId: z.string() },
+  // Deal authority is keyed by an `opportunityId` query param, not a path segment.
+  async (a) => ok(await api('GET', '/api/v1/deal-authority/buyer-intelligence', {
+    params: { opportunityId: a.opportunityId },
+  })));
+
+server.tool('get_competitor_intel', 'Get competitive intelligence for a company.',
+  { companyId: z.string() },
+  async (a) => ok(await api('GET', `/api/v1/competitors`, { params: { companyId: a.companyId } })));
+
+// ===== ANALYTICS =====
+
+server.tool('get_pipeline_metrics', 'Pipeline metrics: total value, deal count, win rate, stage distribution. Returns an object; when there are no deals it says so explicitly rather than returning a bare empty list.',
+  { period: z.string().optional().describe('7d, 30d, 90d, ytd') },
+  async (a) => {
+    const res = await api('GET', '/api/v1/analytics/pipeline', { params: { period: a.period } });
+    const stages = Array.isArray(res?.data) ? res.data : (Array.isArray(res) ? res : null);
+
+    // The tool describes an object with totals and a stage distribution, but
+    // the endpoint answers with a bare array of stage rows — an empty one when
+    // the workspace has no opportunities. Passing `[]` straight through made
+    // "no deals" indistinguishable from "metrics unavailable", and gave this
+    // tool a different empty shape from every neighbouring tool.
+    if (stages === null) return ok(res);
+
+    let opportunitiesInWorkspace = null;
+    try {
+      const counts = await api('GET', '/api/v1/data/counts');
+      opportunitiesInWorkspace = (counts?.data ?? counts)?.opportunities ?? null;
+    } catch { /* contextual, not required */ }
+
+    return ok({
+      period: a.period || 'all',
+      stageDistribution: stages,
+      isEmpty: stages.length === 0,
+      opportunitiesInWorkspace,
+      note: stages.length === 0
+        ? (opportunitiesInWorkspace === 0
+          ? 'No pipeline metrics: the workspace has no opportunities yet.'
+          : 'No pipeline metrics for this period, though the workspace does have opportunities — try a wider period.')
+        : null,
+    });
+  });
+
+server.tool('get_forecast_data', 'Sales forecast with predicted revenue by period.',
+  { period: z.string().optional() },
+  async (a) => ok(await api('GET', '/api/v1/forecast', { params: { period: a.period } })));
+
+server.tool('get_activity_summary', 'Aggregated activity metrics (calls, emails, meetings) over time.',
+  { userId: z.string().optional(), days: z.number().optional().describe('Lookback in days (default 7)') },
+  async (a) => ok(await api('GET', '/api/v1/actions/summary', { params: { userId: a.userId, days: a.days || 7 } })));
+
+// ===== FINANCE: INSTALLED BASE (customer's own ERP invoices) =====
+// Read-only, workspace-scoped. Source data is the customer's OWN accounting
+// invoices, which arrive via a Codat connector. That connector is not built yet,
+// so a correctly-functioning workspace can legitimately return zero invoices —
+// every response carries a `coverage` block and a `note` saying so. Report that
+// note as-is; never present an empty installed base as "this account bought
+// nothing", and never estimate an amount.
+
+server.tool('get_installed_base',
+  'Finance/expansion installed base: which accounts bought which SKUs (spend, invoice count, first/last purchase) from the customer\'s own ERP invoices, plus the accounts with no invoice at all. Read-only and scoped to your workspace. Always relay the returned `coverage` and `note` — zero invoices means nothing has been ingested yet, NOT zero spend.',
+  {
+    company_id: z.string().optional().describe('Restrict to one account'),
+    sku: z.string().optional().describe('Restrict to one vendor SKU'),
+    include_never_bought: z.boolean().optional().describe('Include accounts with no ingested invoice (default true)'),
+    limit: z.number().optional().describe('Rows per page (default 100, max 500)'),
+    offset: z.number().optional(),
+  },
+  async (a) => ok(await api('GET', '/api/v1/expansion/installed-base', {
+    params: {
+      company_id: a.company_id,
+      sku: a.sku,
+      include_never_bought: a.include_never_bought,
+      limit: a.limit,
+      offset: a.offset,
+    },
+  })));
+
+server.tool('get_company_invoices',
+  `One account's ingested ERP invoices (latest snapshot per invoice) and the catalog products they resolve to. Read-only and workspace-scoped. An account with no ingested invoices returns an empty list — that is the honest answer, not a zero total. The API route has no pagination; limit/offset are applied client-side to the invoices array (default cap ${CLIENT_PAGE_CAP} rows).`,
+  { company_id: z.string().describe('Adrata company id'), limit: z.number().optional().describe(`Max invoices returned (client-side cap, default ${CLIENT_PAGE_CAP})`), offset: z.number().optional().describe('Invoices to skip (client-side)') },
+  async (a) => {
+    const res = await api('GET', `/api/v1/expansion/installed-base/${a.company_id}/invoices`);
+    const d = res?.data;
+    if (d && Array.isArray(d.invoices)) {
+      const { rows, page: pageInfo } = capClientSide(d.invoices, a);
+      return ok({ ...res, data: { ...d, invoices: rows }, page: pageInfo });
+    }
+    return ok(res);
+  });
+
+// ===== ADRATA CLOUD (bitemporal record substrate) =====
+
+server.tool('get_cloud_records',
+  'Query the Adrata Cloud — the canonical, source-attributed, bitemporal record substrate — as one surface. Filter by entity, field, source, and classification, and read AS OF a point in time: `as_of` is when a fact was TRUE, `as_of_recorded` is what Adrata KNEW at that moment. Read-only and scoped to your workspace. Values are returned exactly as asserted, with their source and confidence; a missing confidence is null, never assumed.',
+  {
+    entity_type: z.string().optional().describe('company | person | opportunity | pursuit | room | buyer_group | action | custom'),
+    entity_id: z.string().optional(),
+    field_name: z.string().optional().describe('Machine name of the field'),
+    field_definition_id: z.string().optional(),
+    source_type: z.string().optional(),
+    source_id: z.string().optional(),
+    classification: z.string().optional().describe('public | internal | confidential | highly_confidential | restricted'),
+    as_of: z.string().optional().describe('RFC 3339 instant — valid time (defaults to now)'),
+    as_of_recorded: z.string().optional().describe('RFC 3339 instant — knowledge time (defaults to now)'),
+    limit: z.number().optional().describe('Rows per page (default 100, max 500)'),
+    offset: z.number().optional(),
+  },
+  async (a) => ok(await api('GET', '/api/v1/cloud/records', {
+    params: {
+      entity_type: a.entity_type,
+      entity_id: a.entity_id,
+      field_name: a.field_name,
+      field_definition_id: a.field_definition_id,
+      source_type: a.source_type,
+      source_id: a.source_id,
+      classification: a.classification,
+      as_of: a.as_of,
+      as_of_recorded: a.as_of_recorded,
+      limit: a.limit,
+      offset: a.offset,
+    },
+  })));
+
+// ===== CAMPAIGNS & SEQUENCES =====
+
+server.tool('list_campaigns', 'List campaigns with optional status filter.',
+  { status: z.string().optional().describe('draft, active, paused, completed'), ...page },
+  async (a) => ok(await api('GET', '/api/v1/campaigns', { params: { status: a.status, limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_campaign', 'Get campaign details and performance metrics.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/campaigns/${a.id}`)));
+
+server.tool('list_sequences', 'List email sequences.',
+  page, async (a) => ok(await api('GET', '/api/v1/sequences', { params: { limit: a.limit || 25, page: a.page || 1 } })));
+
+server.tool('get_sequence', 'Get sequence details including steps.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/sequences/${a.id}`)));
+
+// ===== PRIORITY PURSUITS =====
+
+server.tool('get_priority_pursuits', 'Get Priority Pursuits — your evidence-ranked daily account and next-move list.',
+  page, async (a) => ok(await api('GET', '/api/v1/speedrun', { params: { limit: a.limit || 25, page: a.page || 1 } })));
+
+// Compatibility alias for existing clients. Keep the transport route stable
+// while removing the retired seller-facing product language.
+server.tool('get_speedrun_list', 'Legacy alias for get_priority_pursuits.',
+  page, async (a) => ok(await api('GET', '/api/v1/speedrun', { params: { limit: a.limit || 25, page: a.page || 1 } })));
+
+// ===== USERS =====
+
+server.tool('list_users', 'List workspace users/team members.',
+  page, async (a) => ok(await api('GET', '/api/v1/users', { params: { limit: a.limit || 50, page: a.page || 1 } })));
+
+server.tool('get_user', 'Get user details.',
+  { id: z.string() }, async (a) => ok(await api('GET', `/api/v1/users/${a.id}`)));
+
+server.tool('get_current_user', 'Get the currently authenticated user.',
+  {}, async () => ok(await api('GET', '/api/v1/users/me')));
+
+// ===== RECORD COUNTS =====
+
+server.tool('count_records', 'Get total counts of companies, people, opportunities.',
+  {}, async () => ok(await api('GET', '/api/v1/data/counts')));
+
+// ===== ICP =====
+
+server.tool('list_icp_profiles', 'List the workspace ICP profiles. A workspace selling into several motions keeps one active profile per segment; use this to see them and to get a profileId for segment-specific scoring.',
+  { activeOnly: z.boolean().optional().describe('Default true. Set false to include archived profiles.') },
+  // Profiles live at /api/v1/icp-profiles, NOT under /icp-scoring.
+  async (a) => ok(await api('GET', '/api/v1/icp-profiles', {
+    params: { status: a.activeOnly === false ? undefined : 'active' },
+  })));
+
+server.tool('score_company_icp', 'Score how well a company matches your Ideal Customer Profile. When several profiles are active this scores the company against EVERY segment and returns one score per profile plus the best fit. Pass profileId to score against a single segment.',
+  {
+    companyId: z.string(),
+    profileId: z.string().optional().describe('Score against this ICP profile only. Omit to score against every active profile, one score per segment.'),
+  },
+  // Scoring is a POST-only route; GET on the same path returns 405.
+  async (a) => ok(await api('POST', `/api/v1/icp-scoring/score-company/${encodeURIComponent(a.companyId)}`, {
+    body: a.profileId ? { profile_id: a.profileId } : {},
+  })));
+
+server.tool('get_icp_distribution', 'Get ICP tier distribution (A/B/C/D breakdown) for one ICP profile, plus coverage showing how many companies have been scored at all. Pass profileId to read a specific segment; omit for the workspace default.',
+  { profileId: z.string().optional().describe('Read the distribution for this ICP profile. Omit for the workspace default.') },
+  async (a) => ok(await api('GET', '/api/v1/icp-scoring/distribution', {
+    params: a.profileId ? { profile_id: a.profileId } : {},
+  })));
+
+// ===== WORKFLOW TOOLS =====
+// High-level tools for common sales workflows — find-or-create, batch logging.
+
+server.tool('find_or_create_person',
+  'Find a person by email or name+company, or create them if they don\'t exist. Returns the person record either way. Use this when logging interactions where you\'re not sure if the person exists yet.',
+  {
+    email: z.string().optional().describe('Email to search by (most reliable)'),
+    name: z.string().optional().describe('Full name to search by'),
+    firstName: z.string().optional(),
+    lastName: z.string().optional(),
+    companyName: z.string().optional().describe('Company name — used to find matching company'),
+    companyId: z.string().optional().describe('Company ID if known'),
+    title: z.string().optional(),
+    linkedinUrl: z.string().optional(),
+    phone: z.string().optional(),
+  },
+  async (args) => {
+    // Try to find by email first
+    if (args.email) {
+      const search = await api('GET', '/api/v1/people', { params: { search: args.email, limit: 5, page: 1 } });
+      const people = search?.data || [];
+      const match = people.find(p => p.email?.toLowerCase() === args.email.toLowerCase());
+      if (match) return ok({ found: true, person: match });
+    }
+    // Try by name
+    if (args.name || (args.firstName && args.lastName)) {
+      const q = args.name || `${args.firstName} ${args.lastName}`;
+      const search = await api('GET', '/api/v1/people', { params: { search: q, limit: 10, page: 1 } });
+      const people = search?.data || [];
+      if (people.length === 1) return ok({ found: true, person: people[0] });
+      if (people.length > 1 && args.companyId) {
+        const match = people.find(p => p.companyId === args.companyId);
+        if (match) return ok({ found: true, person: match });
+      }
+    }
+    // Not found — create
+    const createBody = {};
+    if (args.name) createBody.name = args.name;
+    if (args.firstName) createBody.firstName = args.firstName;
+    if (args.lastName) createBody.lastName = args.lastName;
+    if (args.email) createBody.email = args.email;
+    if (args.title) createBody.title = args.title;
+    if (args.phone) createBody.phone = args.phone;
+    if (args.linkedinUrl) createBody.linkedinUrl = args.linkedinUrl;
+    if (args.companyId) createBody.companyId = args.companyId;
+    createBody.status = 'LEAD';
+    const created = await api('POST', '/api/v1/people', { body: createBody });
+    return ok({ found: false, created: true, person: created?.data || created });
+  }
+);
+
+server.tool('find_or_create_company',
+  'Find a company by name or domain, or create it if it doesn\'t exist. Returns the company record either way.',
+  {
+    name: z.string().optional().describe('Company name to search by'),
+    domain: z.string().optional().describe('Company domain (e.g. acme.com)'),
+    industry: z.string().optional(),
+    website: z.string().optional(),
+  },
+  async (args) => {
+    const q = args.domain || args.name;
+    if (q) {
+      const search = await api('GET', '/api/v1/companies', { params: { search: q, limit: 5, page: 1 } });
+      const companies = search?.data || [];
+      if (args.domain) {
+        const match = companies.find(c => c.domain?.toLowerCase() === args.domain.toLowerCase());
+        if (match) return ok({ found: true, company: match });
+      }
+      if (companies.length === 1) return ok({ found: true, company: companies[0] });
+    }
+    // Create
+    const createBody = {};
+    if (args.name) createBody.name = args.name;
+    if (args.domain) createBody.domain = args.domain;
+    if (args.industry) createBody.industry = args.industry;
+    if (args.website) createBody.website = args.website;
+    createBody.status = 'PROSPECT';
+    const created = await api('POST', '/api/v1/companies', { body: createBody });
+    return ok({ found: false, created: true, company: created?.data || created });
+  }
+);
+
+server.tool('log_interaction',
+  'Log a sales interaction — finds the person (or creates them), creates an action with metadata, and optionally updates the person\'s customFields. This is the primary tool for recording outreach activity. One call does everything.',
+  {
+    personEmail: z.string().optional().describe('Email of the person (used to find/create)'),
+    personName: z.string().optional().describe('Name of the person'),
+    personLinkedin: z.string().optional().describe('LinkedIn URL'),
+    companyName: z.string().optional().describe('Company name'),
+    type: z.string().describe('Interaction type: linkedin_connection_request, linkedin_message, email, call, meeting, note'),
+    title: z.string().describe('What happened, e.g. "Sent LinkedIn connection request"'),
+    outcome: z.string().optional().describe('Result: accepted, pending, replied, no_response, meeting_booked'),
+    message: z.string().optional().describe('The message sent (stored in action metadata)'),
+    status: z.string().optional().describe('Action status: COMPLETED (default), PLANNED, IN_PROGRESS'),
+    customFields: z.record(z.unknown()).optional().describe('Additional fields to set on the person record'),
+  },
+  async (args) => {
+    // 1. Find or create the person
+    let personId = null;
+    let companyId = null;
+
+    // Find company first if provided
+    if (args.companyName) {
+      const compSearch = await api('GET', '/api/v1/companies', { params: { search: args.companyName, limit: 3, page: 1 } });
+      const companies = compSearch?.data || [];
+      if (companies.length > 0) companyId = companies[0].id;
+    }
+
+    // Find person
+    const searchQ = args.personEmail || args.personName;
+    if (searchQ) {
+      const personSearch = await api('GET', '/api/v1/people', { params: { search: searchQ, limit: 5, page: 1 } });
+      const people = personSearch?.data || [];
+      const match = args.personEmail
+        ? people.find(p => p.email?.toLowerCase() === args.personEmail.toLowerCase())
+        : people.length === 1 ? people[0] : null;
+      if (match) {
+        personId = match.id;
+        if (!companyId && match.companyId) companyId = match.companyId;
+      }
+    }
+
+    // Create person if not found
+    if (!personId && (args.personEmail || args.personName)) {
+      const createBody = { status: 'LEAD' };
+      if (args.personName) createBody.name = args.personName;
+      if (args.personEmail) createBody.email = args.personEmail;
+      if (args.personLinkedin) createBody.linkedinUrl = args.personLinkedin;
+      if (companyId) createBody.companyId = companyId;
+      const created = await api('POST', '/api/v1/people', { body: createBody });
+      personId = created?.data?.id || created?.id;
+    }
+
+    // 2. Create the action
+    const actionBody = {
+      title: args.title,
+      type: args.type,
+      status: args.status || 'COMPLETED',
+      metadata: {},
+    };
+    if (personId) actionBody.personId = personId;
+    if (companyId) actionBody.companyId = companyId;
+    if (args.outcome) actionBody.outcome = args.outcome;
+    if (args.message) actionBody.metadata.message = args.message;
+    if (args.personLinkedin) actionBody.metadata.profileUrl = args.personLinkedin;
+
+    const action = await api('POST', '/api/v1/actions', { body: actionBody });
+
+    // 3. Update person customFields if provided
+    if (personId && args.customFields) {
+      await api('PATCH', `/api/v1/people/${personId}`, { body: { customFields: args.customFields } });
+    }
+
+    return ok({
+      logged: true,
+      personId,
+      companyId,
+      actionId: action?.data?.id || action?.id,
+      type: args.type,
+      title: args.title,
+    });
+  }
+);
+
+// ===== SCHEMA INTROSPECTION =====
+// These tools let agents discover available fields dynamically — the key
+// differentiator vs competitors (Attio has list-attribute-definitions).
+
+const ENTITY_SCHEMAS = {
+  company: {
+    standard: ['id', 'name', 'domain', 'website', 'industry', 'sector', 'size', 'revenue', 'employeeCount', 'status', 'priority', 'description', 'email', 'phone', 'address', 'city', 'state', 'country', 'postalCode', 'linkedinUrl', 'twitterUrl', 'foundedYear', 'annualRevenue', 'tags', 'lastAction', 'lastActionDate', 'nextAction', 'nextActionDate', 'globalRank', 'ownerId', 'customFields', 'createdAt', 'updatedAt'],
+    statuses: ['ACTIVE', 'INACTIVE', 'PROSPECT', 'CUSTOMER', 'CHURNED', 'ARCHIVED'],
+    priorities: ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'],
+    customFieldsType: 'JSONB — merged on update, stores arbitrary key-value pairs',
+  },
+  person: {
+    standard: ['id', 'name', 'firstName', 'lastName', 'email', 'phone', 'title', 'currentRole', 'department', 'seniority', 'companyId', 'companyName', 'linkedinUrl', 'status', 'priority', 'source', 'engagementScore', 'globalRank', 'lastAction', 'lastActionDate', 'nextAction', 'nextActionDate', 'customFields', 'createdAt', 'updatedAt'],
+    statuses: ['LEAD', 'PROSPECT', 'CUSTOMER', 'CHURNED', 'ARCHIVED', 'ACTIVE', 'INACTIVE'],
+    priorities: ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'],
+    customFieldsType: 'JSONB — merged on update, stores arbitrary key-value pairs',
+  },
+  opportunity: {
+    standard: ['id', 'name', 'description', 'amount', 'stage', 'probability', 'status', 'companyId', 'ownerId', 'revenueType', 'dealType', 'forecastCategory', 'budgetAmount', 'expectedCloseDate', 'closeDate', 'actualCloseDate', 'lostReason', 'customFields', 'createdAt', 'updatedAt'],
+    stages: ['Discovery', 'Qualification', 'Proposal', 'Negotiation', 'Closed Won', 'Closed Lost'],
+    dealTypes: ['NEW_BUSINESS', 'EXPANSION', 'RENEWAL', 'UPSELL', 'CROSS_SELL'],
+    forecastCategories: ['PIPELINE', 'BEST_CASE', 'COMMIT', 'CLOSED_WON', 'OMITTED'],
+    customFieldsType: 'JSONB — merged on update, stores arbitrary key-value pairs',
+  },
+  action: {
+    standard: ['id', 'title', 'description', 'type', 'status', 'priority', 'dueDate', 'completedAt', 'companyId', 'personId', 'assignedTo', 'outcome', 'metadata', 'createdAt', 'updatedAt'],
+    statuses: ['PLANNED', 'IN_PROGRESS', 'COMPLETED', 'CANCELLED', 'OVERDUE'],
+    priorities: ['LOW', 'NORMAL', 'HIGH', 'URGENT'],
+    types: ['email', 'call', 'meeting', 'note', 'task', 'linkedin_connection_request', 'linkedin_message', 'iMessage', 'follow-up'],
+    metadataType: 'JSONB — merged on update, stores type-specific data (message copy, call notes, etc.)',
+  },
+  note: {
+    standard: ['id', 'body', 'companyId', 'personId', 'opportunityId', 'createdAt', 'updatedAt'],
+  },
+  buyer_group: {
+    standard: ['id', 'name', 'companyId', 'createdAt', 'updatedAt'],
+    memberRoles: ['Champion', 'Decision Maker', 'Influencer', 'Blocker', 'End User', 'Technical Evaluator', 'Budget Holder'],
+  },
+};
+
+server.tool('describe_fields',
+  'List all available fields for an entity type, including enums, statuses, and custom field support. Use this to discover what data you can read/write before creating or updating records.',
+  { entity: z.enum(['company', 'person', 'opportunity', 'action', 'note', 'buyer_group']).describe('Entity type to describe') },
+  async ({ entity }) => ok(ENTITY_SCHEMAS[entity]));
+
+server.tool('list_custom_fields',
+  'Discover what custom fields are set across records of a given type. Samples up to 100 records and returns all unique customFields keys found. Use this to understand what custom data has been added.',
+  { entity: z.enum(['company', 'person', 'opportunity']).describe('Entity type to inspect') },
+  async ({ entity }) => {
+    const endpoint = entity === 'company' ? 'companies' : entity === 'person' ? 'people' : 'opportunities';
+    const data = await api('GET', `/api/v1/${endpoint}`, { params: { limit: 100, page: 1 } });
+    const records = data?.data || [];
+    const keySet = new Set();
+    for (const record of records) {
+      const cf = record.customFields;
+      if (cf && typeof cf === 'object') {
+        for (const key of Object.keys(cf)) keySet.add(key);
+      }
+    }
+    return ok({
+      entity,
+      recordsSampled: records.length,
+      customFieldKeys: [...keySet].sort(),
+      note: 'To add a new custom field, just include it in the customFields object when creating or updating a record. No schema migration needed.',
+    });
+  });
+
+// ===== RESOURCES =====
+
+server.resource('entity-guide', 'adrata://guide/entities', async () => ({
+  contents: [{ uri: 'adrata://guide/entities', mimeType: 'text/plain', text: `Adrata Entity Relationships:
+
+Companies → have People (via companyId) → have Opportunities (via companyId)
+People → status determines type: LEAD, PROSPECT, CUSTOMER, ACTIVE
+Opportunities → stages: Discovery → Qualification → Proposal → Negotiation → Closed Won/Lost
+Actions → linked to People and/or Companies, auto-update Last Touch and Next Move fields
+Notes → attached to Companies, People, or Opportunities
+Buyer Groups → belong to Companies, contain People with roles (Champion, Decision Maker, etc.)
+
+Key behaviors:
+- customFields on Companies, People, Opportunities = JSONB-merged on update
+- metadata on Actions = JSONB-merged, use for type-specific data
+- Creating/completing an Action auto-updates Last Touch and Next Move on linked records
+- Leads = People with status LEAD (use update_person to modify)
+- Enrichment triggers async data collection from external sources` }]
+}));
+
+// ===== MEMORY TOOLS =====
+// save_memory, recall, who_am_i, forget — work on all tiers
+registerMemoryTools(server, z, api, AUTH, ok);
+
+// ===== MORNING BRIEF =====
+// morning_brief — the hero experience. Free=teaser, Pro+=full brief
+registerMorningBrief(server, z, api, AUTH, ok);
+
+// ===== SLOAN (AI EXECUTIVE ASSISTANT) =====
+// sloan_status / sloan_handoff / configure_sloan — first-class wrappers over
+// the governed dispatcher (approve_/reject_sloan_draft ride the generic
+// adrata_ai_tool_execute passthrough).
+registerSloanTools(server, z, executeAiCrmTool, ok);
+
+// ===== BILLING TOOLS =====
+// upgrade_account, check_subscription — work on all tiers
+registerBillingTools(server, { api, ok, auth: AUTH });
+
+// ===== RESOURCES: adrata://profile =====
+// Returns user context for Claude to read at session start
+registerProfileResource(server, api, AUTH);
+
+// ===== RESOURCES: recent-research, sales-playbook, workspace =====
+// Additional resources for passive context injection
+registerResources(server, api, AUTH);
+
+// ===== ENTERPRISE TOOLS =====
+// bulk_import, export_data, manage_custom_fields, get_workspace_settings
+// These require OAuth enterprise tier and check workspace capabilities.
+registerEnterpriseTools(server, { z, api, AUTH, ok, API_BASE });
+
+// ===== EMAIL INFRASTRUCTURE TOOLS =====
+// Domain management, email account provisioning, sequence management.
+// Enterprise tier only — calls existing Rust API endpoints.
+registerEmailTools(server, { z, api, AUTH, ok, API_BASE });
+
+// ===== WORK BOARD TOOLS =====
+// Starfield's boards, read and reorganised through the SAME governed endpoints
+// the UI calls — never a second path into the data. Moves and tag changes are
+// writes and carry the standard dryRun/approved/reason/idempotencyKey contract.
+registerWorkBoardTools(server, {
+  z,
+  api,
+  ok,
+  validateApiBridgeRequest,
+  buildMutationHeaders,
+});
+
+// ===== DEMO SCHEDULING: Cal.com integration (free tier) =====
+// schedule_demo and schedule_meeting are registered here; get_demo_availability
+// is overridden in always-loaded.js to use the Cal.com-powered implementation.
+
+server.tool('schedule_demo',
+  'Book a product demo with Adrata. Free tier — no account needed. Creates a calendar event via Cal.com. The attendee receives an email confirmation automatically.',
+  {
+    date: z.string().describe('Date in YYYY-MM-DD format (e.g. "2026-04-15")'),
+    time: z.string().describe('Time in HH:MM 24h format (e.g. "14:00")'),
+    name: z.string().describe('Attendee full name'),
+    email: z.string().describe('Attendee email address'),
+    company: z.string().optional().describe('Attendee company name'),
+    timezone: z.string().optional().describe('IANA timezone (e.g. "America/New_York"). Auto-detected if omitted.'),
+  },
+  async (args) => {
+    const result = await scheduleDemo(args);
+    return ok(result);
+  });
+
+server.tool('schedule_meeting',
+  'Preview or create a meeting through Adrata chat’s governed calendar path. Live creation requires an audit reason and the server-issued confirmation token returned by the first approved request. Provider delivery remains pending until sync confirms it.',
+  {
+    title: z.string().describe('Meeting title'),
+    eventId: z.string().optional().describe('Existing Adrata event ID to update instead of creating a duplicate'),
+    date: z.string().describe('Date in YYYY-MM-DD format'),
+    time: z.string().describe('Time in HH:MM 24h format'),
+    duration: z.number().optional().describe('Duration in minutes (default 30)'),
+    attendees: z.array(z.string()).optional().describe('List of attendee email addresses'),
+    description: z.string().optional().describe('Meeting description or agenda'),
+    timezone: z.string().optional().describe('IANA timezone. Auto-detected if omitted.'),
+    dryRun: z.boolean().optional().describe('Defaults to true. Set false after explicit approval to request a confirmation token.'),
+    reason: z.string().optional().describe('Required audit reason when requesting a live-write confirmation token.'),
+    confirmationToken: z.string().optional().describe('Single-use server token from the approved first request.'),
+  },
+  async (args) => {
+    try {
+      const result = await scheduleMeeting(args, api);
+      return ok(result);
+    } catch (err) {
+      return ok({ error: true, message: err.message, hint: 'Ensure your workspace is connected (use connect_workspace) and calendar integration is enabled.' });
+    }
+  });
+
+// ===== ANALYTICS & TELEMETRY =====
+// Tracks tool invocations, search queries, tier gates, conversions, sessions.
+// Builds on top of existing event logging — adds classification and dashboards.
+// ADRATA_TELEMETRY=off disables all tracking. PII is hashed before storage.
+registerAnalytics(server, { z, api, auth: AUTH, ok, checkToolAccess });
+
+// ===== COMPOSITE TOOLSETS =====
+// 42 composite tools organized into 7 toolsets with dynamic discovery.
+// Only always-loaded tools (list_toolsets, enable_toolset, get_demo_availability,
+// check_inbox) are registered at startup. Other toolsets load on demand via
+// enable_toolset to save tokens (~12K vs ~135K for 450 individual tools).
+// The existing individual tools above remain for backward compatibility.
+registerAlwaysLoadedTools(server, api, AUTH);
+
+// Extensibility surface: custom integration / extension catalog inspection,
+// manifest validation, and deploy-request submission. Free tier so any
+// connected agent can iterate on a manifest end-to-end; the control plane
+// still gates activation on policy review.
+registerExtensibilityTools(server, api, AUTH);
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+const TRANSPORT_MODE = (process.env.ADRATA_MCP_TRANSPORT || 'stdio').toLowerCase();
+
+if (TRANSPORT_MODE === 'http' || TRANSPORT_MODE === 'sse') {
+  // Streamable HTTP transport — single POST /mcp endpoint that can upgrade to SSE
+  const { startHttpTransport } = await import('./transport-http.js');
+  await startHttpTransport(server, {
+    runWithAuthContext,
+  });
+} else {
+  // Default: stdio transport (backward compatible)
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}