@ultimat3/mcp 24.0.0 → 25.0.0

package/src/meta-surface.ts

@@ -268,40 +268,82 @@ export function schemaOf(tool: AnyMcpTool): JsonSchema {
  * every quote — a staff catalog measured 32.5k characters — and `JSON.parse` was never its reader's
  * job: the model's is. Same facts, same order; `describe_resource` stays JSON because a schema is.
  *
+ * Every per-action tag costs once per action, so each is stated where it is cheapest and still
+ * exact (#590): a scope shared by every action of the resource — or of one kind — is said once on
+ * the resource line (`hoistScopes`); only `action` is tagged, because untagged means `query` and
+ * the header says so. The kind comes from `destructive` (`headOf`), never from the name.
+ *
  * ```text
- * cases — Court cases of the account.
- *   listCases (query) {radicado?: string} — List the account's cases.
- *   closeCase (action; confirms; scope cases:write) {id: string} — Close a case.
+ * cases (scope cases) — Court cases of the account.
+ *   listCases {radicado?: string} — List the account's cases.
+ *   closeCase (action; confirms) {id: string} — Close a case.
  * ```
  */
 export function renderCatalog(resources: readonly MetaResource[]): string {
   if (resources.length === 0) return 'No resources are available to this caller.';
   const lines = [
-    `${resources.length} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas.`,
+    `${resources.length} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas. Untagged = read-only query; (action) may write; (confirms) waits for a human; … = more in describe_resource.`,
   ];
   for (const resource of resources) {
-    lines.push('', `${resource.name} — ${oneLine(resource.description)}`);
+    const hoisted = hoistScopes(resource.actions);
+    const said = hoisted.line === '' ? '' : ` (${hoisted.line})`;
+    lines.push('', `${resource.name}${said} — ${oneLine(resource.description)}`);
     for (const action of resource.actions) {
       const tags = [
-        action.kind,
+        ...(action.kind === 'action' ? ['action'] : []),
         ...(action.confirms === true ? ['confirms'] : []),
-        ...(action.scope === undefined ? [] : [`scope ${action.scope}`]),
-      ].join('; ');
-      lines.push(`  ${action.name} (${tags}) {${action.params}} — ${oneLine(action.description)}`);
+        ...(action.scope === undefined || hoisted.kinds.has(action.kind)
+          ? []
+          : [`scope ${action.scope}`]),
+      ];
+      const tagged = tags.length === 0 ? '' : ` (${tags.join('; ')})`;
+      lines.push(`  ${action.name}${tagged} {${action.params}} — ${oneLine(action.description)}`);
     }
   }
   return lines.join('\n');
 }
 
+/**
+ * The scopes said once on the resource line, and the kinds whose actions no longer repeat theirs.
+ * One scope for every action → `scope cases`. Otherwise per kind, because a token split into
+ * `cases:read` / `cases:write` is the common shape: `query scope cases:read; action scope
+ * cases:write`. A kind is hoisted only when EVERY action of it carries the SAME scope — one
+ * unscoped action among scoped ones must not inherit a gate the registry does not enforce.
+ * Computed over what THIS caller sees: the catalog is per caller.
+ */
+function hoistScopes(actions: readonly MetaAction[]): {
+  readonly line: string;
+  readonly kinds: ReadonlySet<MetaAction['kind']>;
+} {
+  const all = sharedScope(actions);
+  if (all !== undefined) return { line: `scope ${all}`, kinds: new Set(['query', 'action']) };
+  const parts: string[] = [];
+  const kinds = new Set<MetaAction['kind']>();
+  for (const kind of ['query', 'action'] as const) {
+    const scope = sharedScope(actions.filter((action) => action.kind === kind));
+    if (scope === undefined) continue;
+    parts.push(`${kind} scope ${scope}`);
+    kinds.add(kind);
+  }
+  return { line: parts.join('; '), kinds };
+}
+
+/** The scope every action carries, or `undefined` when there is none, one lacks it or two differ. */
+function sharedScope(actions: readonly MetaAction[]): string | undefined {
+  const first = actions[0]?.scope;
+  if (first === undefined) return undefined;
+  return actions.every((action) => action.scope === first) ? first : undefined;
+}
+
 /** A description authored across lines is still one catalog line. */
 const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
 
 function headOf(tool: AnyMcpTool): Omit<MetaAction, 'params'> {
   return {
     name: tool.name,
-    // `=== true`, as `ToolRegistry.verbClass` meters it: an omitted `destructive` is a read in the
-    // rate limiter, so listing it as an action gave one tool two answers.
-    kind: tool.destructive === true ? 'action' : 'query',
+    // `=== false`, as `ToolRegistry.verbClass` meters it — one answer per tool. An omitted flag is
+    // an action: the header's "untagged = read-only query" holds only for a DECLARED read.
+    kind: tool.destructive === false ? 'query' : 'action',
     description: tool.description,
     ...(tool.confirms === true ? { confirms: true } : {}),
     ...(tool.scope === undefined ? {} : { scope: tool.scope }),
@@ -312,27 +354,44 @@ function sorted<V>(map: ReadonlyMap<string, V>): readonly [string, V][] {
   return [...map.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
-/** Past this, the hint says "see describe_resource" instead of pretending to be complete. */
-const HINT_MAX = 240;
+/** Fields a hint names before `…` — every required one is named regardless. */
+const HINT_FIELDS = 4;
+/** Optional fields stop being added once the hint is this long; required ones never stop. */
+const HINT_MAX = 100;
+/** Literals an enum hint names before `|…`. */
+const HINT_LITERALS = 8;
 
 /**
  * `name: type` per property, `?` when optional, an enum as its literals — the hint
  * `list_resources` carries so a common call needs no `describe_resource` round-trip.
+ *
+ * Cut by FIELDS, never by characters (#590): a character cut sliced `limit?: integer` into
+ * `limit?: i…`. Every required field is named, in declared order, because a call without one
+ * fails; optional fields follow until `HINT_FIELDS` names or `HINT_MAX` characters, and a trailing
+ * `…` says some were left out. `describe_resource` always has the full schema.
  */
 export function oneLineParams(schema: JsonSchema): string {
   const required = new Set(schema.required ?? []);
-  const parts = Object.entries(schema.properties ?? {}).map(
-    ([key, child]) => `${key}${required.has(key) ? '' : '?'}: ${typeHint(child)}`,
-  );
-  const line = parts.join(', ');
-  if (line.length <= HINT_MAX) return line;
-  return `${line.slice(0, HINT_MAX - 1)}… (describe_resource has the rest)`;
+  const fields = Object.entries(schema.properties ?? {}).map(([key, child]) => ({
+    required: required.has(key),
+    text: `${key}${required.has(key) ? '' : '?'}: ${typeHint(child)}`,
+  }));
+  const named = new Set(fields.filter((field) => field.required));
+  let length = [...named].reduce((sum, field) => sum + field.text.length + 2, 0);
+  for (const field of fields) {
+    if (field.required) continue;
+    if (named.size >= HINT_FIELDS || length + field.text.length > HINT_MAX) break;
+    named.add(field);
+    length += field.text.length + 2;
+  }
+  const parts = fields.filter((field) => named.has(field)).map((field) => field.text);
+  return named.size < fields.length ? [...parts, '…'].join(', ') : parts.join(', ');
 }
 
 function typeHint(schema: JsonSchema): string {
-  if (schema.enum !== undefined) return schema.enum.map((v) => JSON.stringify(v)).join('|');
+  if (schema.enum !== undefined) return literals(schema.enum.map((v) => JSON.stringify(v)));
   if (schema.const !== undefined) return JSON.stringify(schema.const);
-  if (schema.anyOf !== undefined) return schema.anyOf.map(typeHint).join('|');
+  if (schema.anyOf !== undefined) return literals(schema.anyOf.map(typeHint));
   if (schema.type === 'array') {
     if (schema.items === undefined) return 'array';
     const item = typeHint(schema.items);
@@ -340,3 +399,9 @@ function typeHint(schema: JsonSchema): string {
   }
   return schema.type ?? 'any';
 }
+
+/** A union cut at an alternative, never inside one. */
+function literals(alternatives: readonly string[]): string {
+  if (alternatives.length <= HINT_LITERALS) return alternatives.join('|');
+  return [...alternatives.slice(0, HINT_LITERALS), '…'].join('|');
+}

package/src/mount-errors.ts

@@ -23,7 +23,7 @@ export class McpPathDuplicateError extends UltimateError {
     super({
       code: 'X_MCP_PATH_DUPLICATE',
       cause: `${input.file} exports mcp endpoints #${first} and #${second}, and both claim ${input.method} ${input.path}`,
-      fix: `give endpoint #${second} in ${input.file} its own path — defineAppMcp({ path: '/mcp/<population>', ... }); endpoint #0 mounts at ai.mcp.path and every other at its own defineAppMcp path`,
+      fix: `give endpoint #${second} in ${input.file} its own path — defineAppMcp({ path: '/mcp/<population>', ... }); every endpoint mounts at its own defineAppMcp path (default /mcp)`,
     });
     this.path = input.path;
     this.endpoints = input.endpoints;

package/src/oauth-metadata.ts

@@ -4,7 +4,7 @@
 // authorization server(s) a client goes to for a token. The authorization server itself is the
 // APP's — its consent page, its token endpoint, its revocation list — never this package's.
 
-import { McpOAuthInvalidError } from './errors';
+import { McpOAuthInvalidError } from './errors-transport';
 
 /** The well-known suffix RFC 9728 §3 defines. */
 export const PROTECTED_RESOURCE_WELL_KNOWN = '/.well-known/oauth-protected-resource';

package/src/projectable.ts

@@ -4,28 +4,20 @@
 // primitive out is a different way to NAME a tool, never a second way to run one.
 
 import type { AnyAction } from '@ultimat3/action';
+import { actionName, guardActionBeforeInput, invoke, isAction } from '@ultimat3/action';
 import {
-  guardBeforeInput as actionGuardBeforeInput,
-  actionName,
+  type Actor,
   actorOf,
-  invoke,
-  isAction,
-} from '@ultimat3/action';
-import { type Actor, isMcpExposed, useContext } from '@ultimat3/core';
+  isMcpExposed,
+  type McpExposureDeclaration,
+  useContext,
+} from '@ultimat3/core';
 import type { AnyQuery } from '@ultimat3/query';
-import {
-  isQuery,
-  guardBeforeInput as queryGuardBeforeInput,
-  queryName,
-  readAnswer,
-  sourceFor,
-} from '@ultimat3/query';
+import { guardQueryBeforeInput, isQuery, queryName, readAnswer, sourceFor } from '@ultimat3/query';
 import { toWireOutputSchema, toWireSchema } from '@ultimat3/schema';
 import { asCallerContext } from './caller-context';
-import type { McpExposure, ProjectablePrimitive } from './from-action';
+import type { ProjectablePrimitive } from './from-action';
 import { takeIdempotencyKeyArg, withIdempotencyKeyArg } from './idempotency-arg';
-import type { McpListParams } from './list-params';
-import type { McpToolAnnotations } from './registry';
 import type { JsonSchema } from './wire';
 
 /**
@@ -33,7 +25,7 @@ import type { JsonSchema } from './wire';
  *
  * The real primitives come first because they are what an app writes: `actions: [publishPost]`.
  * Until 2026-08 this list took `ProjectablePrimitive` alone, which no `action()` or `query()`
- * structurally satisfies — they carry `as`/`tool`, never `run` — so the only value that could
+ * structurally satisfies — they carry `as` and their projections, never `run` — so the only value that could
  * reach `X_MCP_TOOL_UNDECLARED` was a hand-built fake, and the gate refused nothing an app could
  * actually declare. `ProjectablePrimitive` stays in the union for surfaces that build their
  * catalog programmatically (`@ultimat3/admin`) and for tests that project a stand-in.
@@ -75,7 +67,7 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
     admit: (actor: Actor) =>
       asCallerContext(actor, () => {
         const ctx = useContext();
-        actionGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
+        guardActionBeforeInput(target.policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
       }),
     // The actor rides in on the options: `invoke` swaps it inside the one execution path.
     run: keyed
@@ -90,7 +82,7 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
 export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
   const exposure = exposureOf(target.mcp);
   // A `single: true` read answers ONE row, or not-found — what its route answers (404) and what
-  // `tool().read()` answers. Handing an agent `[]` for a missing id said "found, and empty".
+  // `@ultimat3/query`'s `readAnswer` makes every read answer. Handing an agent `[]` for a missing id said "found, and empty".
   const single = target.single === true;
   // Only a query that DECLARED its rows (`rows: Post.$schema`) has a known answer shape. A list
   // read answers the rows as a list, so the structured copy is `{ rows }` — `structuredContent`
@@ -110,7 +102,7 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
     admit: (actor: Actor) =>
       asCallerContext(actor, () => {
         const ctx = useContext();
-        queryGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, query: name }, 'server');
+        guardQueryBeforeInput(target.policy, { actor: actorOf(ctx), ctx, query: name }, 'server');
       }),
     run: ({ input, actor }) =>
       asCallerContext(actor, async () => {
@@ -118,7 +110,8 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
         // and is what `live`, `paginate` and `explain` build on too. Executed without the
         // cache tiers on purpose: an agent diffing two tool calls must be reading the rows,
         // not a TTL.
-        const source = await sourceFor(target, input);
+        // `'mcp'`: an agent's call spends the read's declared `rateLimit:`, the one bucket its route draws on.
+        const source = await sourceFor(target, input, { surface: 'mcp' });
         // `@ultimat3/query`'s one rule for what a read answers: rows, or a single read's row.
         return readAnswer(target, await source.execute());
       }),
@@ -138,7 +131,7 @@ export function toRowsOutputSchema(rows: unknown): JsonSchema | undefined {
 }
 
 /**
- * An action and a query declare MCP exposure with the same fields, so one typed path reads
+ * An action and a query declare core's ONE `McpExposureDeclaration`, so one typed path reads
  * both. Narrow on purpose, through `@ultimat3/core`'s `isMcpExposed`: only a literal
  * `expose: true` counts, so nothing is exposed by accident — an undeclared `mcp` block yields
  * no exposure at all.
@@ -149,7 +142,9 @@ export function toRowsOutputSchema(rows: unknown): JsonSchema | undefined {
  * projected tool was visible to every caller and the first outcome existed only for the
  * hand-written tools that build their own `McpTool`.
  */
-function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined {
+function exposureOf(
+  declared: McpExposureDeclaration | undefined,
+): McpExposureDeclaration | undefined {
   if (declared === undefined) return undefined;
   return {
     expose: isMcpExposed(declared),
@@ -160,14 +155,3 @@ function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined
     ...(declared.annotations === undefined ? {} : { annotations: declared.annotations }),
   };
 }
-
-/** `ActionMcp` and `QueryMcp` are the same shape; restating it binds to neither. */
-interface DeclaredMcp {
-  readonly expose: boolean;
-  readonly description?: string;
-  readonly visibleTo?: readonly string[];
-  /** `QueryMcp` only; an action has no list to compose. */
-  readonly listParams?: McpListParams;
-  readonly title?: string;
-  readonly annotations?: McpToolAnnotations;
-}

package/src/registry.ts

@@ -131,9 +131,10 @@ export interface McpTool<A extends ToolArgs = ToolArgs> {
   /** Who may see and call this tool. Absent = everyone. See `McpVisibility`. */
   readonly visibleTo?: McpVisibility;
   /**
-   * Marks a tool that changes state. Drives the transport's rate-limit bucket and is
-   * asserted by tests over the dev server, so a new mutating tool cannot be metered as
-   * cheap read chatter by omission.
+   * Marks a tool that changes state. Drives the transport's rate-limit bucket and the meta
+   * catalog's `(action)` tag. Only `false` declares a read: an OMITTED flag counts as a write
+   * (`As of 2026-10`), as a projected action and an app tool already default — so a new mutating
+   * tool cannot be metered or listed as cheap read chatter by omission.
    */
   readonly destructive?: boolean;
   /**
@@ -309,7 +310,7 @@ export class ToolRegistry {
   verbClass(name: string): McpVerbClass {
     const tool = this.#tools.get(name);
     if (tool === undefined) return 'write';
-    return tool.destructive === true ? 'write' : 'read';
+    return tool.destructive === false ? 'read' : 'write';
   }
 }
 
@@ -326,7 +327,7 @@ export function textResult(text: string, isError = false): McpToolResult {
  * spent a third of a large answer on indentation (a staff catalog measured 32.5k characters).
  * `JSON.stringify` is deterministic for one value, so two calls still diff.
  *
- * TOTAL, because the value is an app's: `toolFromAction` hands an action's own return value
+ * TOTAL, because the value is an app's: `toolFrom` hands an action's own return value
  * straight here, and `JSON.stringify` answers `undefined` for a handler that returned nothing —
  * a `text` that is not a string is an invalid MCP frame — and THROWS on a bigint, a cycle or a
  * `toJSON` the value carries. A throw would leave the server's catch reporting a bug in the tool

package/src/scopes.ts

@@ -4,13 +4,13 @@
 // other is its authz rule, and both belong beside the code they guard. A SCOPE is neither.
 // It is a capability of the CONNECTION — what the token was issued to do — so it is grouped
 // here, once per scope, naming the tools that capability covers. That is also why
-// `toolFromAction` never invents one: a projection cannot know what a token means.
+// `toolFrom` never invents one: a projection cannot know what a token means.
 //
 // Without this map the second outcome is unreachable for a generated app. `ToolRegistry`
 // enforces `scope`, the framework's own dev tools declare one, and until 2026-08 nothing an
 // app could write ever set the field — an enforced gate no app declaration could engage.
 
-import { McpScopeConflictError, McpScopeUnknownError } from './errors';
+import { McpScopeConflictError, McpScopeUncoveredError, McpScopeUnknownError } from './errors';
 import type { AnyMcpTool } from './registry';
 
 /**
@@ -25,14 +25,19 @@ export type McpScopes = Readonly<Record<string, readonly string[]>>;
 /**
  * Attach each declared scope to the tool it covers, refusing anything ambiguous at BOOT.
  *
- * Two refusals, because both silently ship an ungated tool otherwise:
+ * Three refusals, because each silently ships an ungated tool otherwise:
  *
  *  - a name no tool in the catalog answers to (`X_MCP_SCOPE_UNKNOWN`) — a typo, or a primitive
  *    that was renamed or never listed. Skipping it leaves the tool reachable with no scope at
  *    all, which is the opposite of what the author wrote;
  *  - one tool claimed by two scopes (`X_MCP_SCOPE_CONFLICT`) — a tool carries ONE scope, so
  *    the second claim would either overwrite the first or be dropped, and which one wins would
- *    be decided by object key order.
+ *    be decided by object key order;
+ *  - a projected tool no scope names (`X_MCP_SCOPE_UNCOVERED`). The registry gates a tool only
+ *    when it carries a scope, so an unnamed one answered EVERY token — while `bearerMount`, handed
+ *    the same map, serves an unnamed primitive to nobody. Giving a map is declaring the cut; a
+ *    tool outside it is a mistake, not a public tool. A tool that arrived with its own `scope`
+ *    (a ready `McpTool`) is covered by it.
  *
  * Runs AFTER duplicate names are refused, so a name resolves to exactly one tool.
  */
@@ -64,6 +69,12 @@ export function withScopes(
     }
   }
 
+  const uncovered = tools
+    .filter((tool) => tool.scope === undefined && !required.has(tool.name))
+    .map((tool) => tool.name)
+    .sort();
+  if (uncovered.length > 0) throw new McpScopeUncoveredError({ uncovered });
+
   return tools.map((tool) => {
     const scope = required.get(tool.name);
     return scope === undefined ? tool : { ...tool, scope };

package/src/server-voice.ts

@@ -8,7 +8,7 @@ import { formatIssues } from '@ultimat3/schema';
 import type { McpCaller, McpToolResult } from './registry';
 import type { ArgIssue } from './validate-args';
 
-/** See `CreateMcpServerInput.instructions`. */
+/** See `McpServerInput.instructions`. */
 export type McpInstructions = string | ((caller: McpCaller) => string | undefined);
 
 /** The server's per-caller wording: `initialize`'s advice and the audience of every `fix:` line. */

package/src/server.ts

@@ -3,9 +3,11 @@
 // and an already-resolved caller, and returns a response or `null` for a notification.
 // Both transports (http, stdio) and every test drive this one function.
 
-import type { ErrorAudience } from '@ultimat3/core';
+import type { Clock, ErrorAudience } from '@ultimat3/core';
 import { fixFor } from '@ultimat3/core';
-import { auditResourceRead, auditToolCall, outcomeForResult } from './audit';
+import { outcomeForResult } from './audit';
+import type { McpAuditHook, McpAuditor } from './audit-hook';
+import { LOG_ONLY_AUDITOR, mcpAuditor } from './audit-hook';
 import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './errors';
 import { asFrameworkError, forAudience } from './framework-error';
 import { metaCall } from './meta-call';
@@ -27,7 +29,7 @@ import { ResourceRegistry } from './resources';
 import type { McpInstructions, McpServerVoice } from './server-voice';
 import { instructionsFor, invalidArgsResult } from './server-voice';
 import { admitted, thrownResponse } from './tool-thrown';
-import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
+import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, McpWire, ServerInfo } from './wire';
 import {
   defaultServerInfo,
   errorResponse,
@@ -38,28 +40,14 @@ import {
   isNotification,
   MCP_PROTOCOL_VERSION,
   METHOD_NOT_FOUND,
+  messageUnitOf,
   paramsOf,
   resultResponse,
 } from './wire';
 
-/**
- * Which wire one message arrived on, so a refusal can name the unit THAT transport counts in.
- * `handle` is transport-independent and stays so — this is a hint for the wording of one fix, never
- * a branch in dispatch. HTTP carries its mounted path because `mcpHttpRoute({ path })` is a knob:
- * a batch refusal that told every client to retry `POST /mcp` was wrong for an app mounted at
- * `/app-mcp`, which is how this came to be threaded rather than spelled.
- */
-export type McpWire =
-  | { readonly transport: 'http'; readonly path: string }
-  | { readonly transport: 'stdio' };
-
-/** The unit a transport counts one request in — or the neutral word when no wire said. */
-const messageUnitOf = (wire: McpWire | undefined): string => {
-  if (wire === undefined) return 'message';
-  return wire.transport === 'http' ? `POST ${wire.path}` : 'line';
-};
+export type { McpWire } from './wire';
 
-export interface CreateMcpServerInput {
+export interface McpServerInput {
   readonly tools?: readonly AnyMcpTool[];
   readonly resources?: readonly McpResource[];
   readonly prompts?: readonly McpPrompt[];
@@ -82,6 +70,10 @@ export interface CreateMcpServerInput {
    * serves `'caller'`.
    */
   readonly errorAudience?: ErrorAudience | undefined;
+  /** Every gate decision as data, after its log line — see `audit-hook.ts`. The route reads it too. */
+  readonly onAudit?: McpAuditHook | undefined;
+  /** Stamps each `onAudit` event's `at`. */
+  readonly clock?: Clock | undefined;
 }
 
 /** The set of JSON-RPC methods this server answers. Kept in sync with `classify`. */
@@ -96,7 +88,7 @@ const METHODS = [
   'prompts/get',
 ] as const;
 
-export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
+export function mcpServer(input: McpServerInput = {}): McpServer {
   const tools = new ToolRegistry().registerAll(input.tools ?? []);
   const resources = new ResourceRegistry().registerAll(input.resources ?? []);
   const meta = MetaSurface.build({
@@ -111,6 +103,9 @@ export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
     input.serverInfo ?? defaultServerInfo(),
     meta,
     { instructions: input.instructions, errorAudience: input.errorAudience ?? 'developer' },
+    input.onAudit === undefined && input.clock === undefined
+      ? LOG_ONLY_AUDITOR
+      : mcpAuditor({ onAudit: input.onAudit, clock: input.clock }),
   );
 }
 
@@ -122,6 +117,8 @@ export class McpServer {
   /** `undefined` for a flat-only server — every existing app, byte for byte. */
   private readonly meta: MetaSurface | undefined;
   private readonly voice: McpServerVoice;
+  /** Where every decision is audited — the log line, then `onAudit`. Public for the HTTP route. */
+  readonly audit: McpAuditor;
 
   constructor(
     tools: ToolRegistry,
@@ -130,6 +127,7 @@ export class McpServer {
     serverInfo: ServerInfo,
     meta?: MetaSurface,
     voice: McpServerVoice = { errorAudience: 'developer' },
+    audit: McpAuditor = LOG_ONLY_AUDITOR,
   ) {
     this.tools = tools;
     this.resources = resources;
@@ -137,6 +135,7 @@ export class McpServer {
     this.serverInfo = serverInfo;
     this.meta = meta;
     this.voice = voice;
+    this.audit = audit;
   }
 
   async handle(
@@ -275,6 +274,7 @@ export class McpServer {
       const answered = await metaCall(
         {
           tools: this.tools,
+          audit: this.audit,
           dispatch: (at, tool, resolved, who) => this.dispatch(at, tool, resolved, who),
           notFound: (at, tool, who, fix) => this.notFound(at, tool, who, fix),
         },
@@ -293,7 +293,7 @@ export class McpServer {
 
   /** OUTCOME 1, the one answer for absent and hidden alike. See `dispatch`. */
   private notFound(id: JsonRpcId, name: string, caller: McpCaller, fix: string): JsonRpcResponse {
-    auditToolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
+    this.audit.toolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
     return errorResponse(id, METHOD_NOT_FOUND, `tool not found: ${name} — ${fix}`);
   }
 
@@ -327,7 +327,7 @@ export class McpServer {
       // nothing — and the fix travels with it, built by the error that owns the wording.
       case 'scope-denied': {
         const denial = new McpScopeDeniedError({ name, scope: resolved.scope });
-        auditToolCall({
+        this.audit.toolCall({
           tool: name,
           outcome: 'scope-denied',
           caller,
@@ -346,9 +346,10 @@ export class McpServer {
         // they send gets the denial `handle` would give, never the issue list — which describes
         // the arguments of a tool they may not call.
         const refused = admitted(resolved.tool, caller);
-        if (refused !== undefined) return thrownResponse(id, name, refused, caller, audience);
+        if (refused !== undefined)
+          return thrownResponse(id, name, refused, caller, audience, this.audit);
         const invalid = invalidArgsResult(name, resolved.issues, audience);
-        auditToolCall({ tool: name, outcome: 'invalid-args', caller, code: invalid.code });
+        this.audit.toolCall({ tool: name, outcome: 'invalid-args', caller, code: invalid.code });
         return resultResponse(id, invalid.result);
       }
       case 'ok':
@@ -359,13 +360,13 @@ export class McpServer {
     try {
       result = await resolved.tool.handle(resolved.args, caller);
     } catch (error) {
-      return thrownResponse(id, name, error, caller, audience);
+      return thrownResponse(id, name, error, caller, audience, this.audit);
     }
 
     // A tool may answer `isError` itself (admin renders its own denial). Outcome 3 unless it
     // NAMED the code it refused with, in which case the same classifier a thrown error goes
     // through decides — a tool's own argument check is not a denial a prober drove.
-    auditToolCall({
+    this.audit.toolCall({
       tool: name,
       outcome: outcomeForResult(result),
       caller,
@@ -406,7 +407,7 @@ export class McpServer {
       // `code` on the audit line either, because the wire carries none — the tool surface's
       // `X_MCP_TOOL_UNKNOWN` is an error class this branch has no twin for.
       case 'not-found':
-        auditResourceRead({ uri, outcome: 'hidden', caller });
+        this.audit.resourceRead({ uri, outcome: 'hidden', caller });
         return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`);
       // OUTCOME 2. The caller can already see this resource, so naming the missing scope leaks
       // nothing — and the fix travels with it, built by the error that owns the wording.
@@ -416,7 +417,7 @@ export class McpServer {
           scope: resolved.scope,
           subject: 'resource',
         });
-        auditResourceRead({
+        this.audit.resourceRead({
           uri,
           outcome: 'scope-denied',
           caller,
@@ -444,16 +445,16 @@ export class McpServer {
       if (contents === undefined) {
         // The resolver said `ok` and the registry then had nothing: a bug here, not a walk, so it
         // is `failed` in the log while the caller still gets the same not-found it would have.
-        auditResourceRead({ uri, outcome: 'failed', caller });
+        this.audit.resourceRead({ uri, outcome: 'failed', caller });
         return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`);
       }
-      auditResourceRead({ uri, outcome: 'ok', caller });
+      this.audit.resourceRead({ uri, outcome: 'ok', caller });
       return resultResponse(id, { contents: [contents] });
     } catch (error) {
       const thrown = asFrameworkError(error);
       if (thrown !== undefined) {
         const framework = forAudience(thrown, this.voice.errorAudience);
-        auditResourceRead({ uri, outcome: 'failed', caller, code: framework.code });
+        this.audit.resourceRead({ uri, outcome: 'failed', caller, code: framework.code });
         return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`, {
           code: framework.code,
           cause: framework.cause,
@@ -463,7 +464,7 @@ export class McpServer {
       }
       // No internals: a provider's own message names a path, a query or a host the caller has no
       // business seeing, exactly as a failing tool's does.
-      auditResourceRead({ uri, outcome: 'failed', caller });
+      this.audit.resourceRead({ uri, outcome: 'failed', caller });
       return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`);
     }
   }

package/src/tool-thrown.ts

@@ -3,7 +3,8 @@
 // raised it. Split from `server.ts` for the file ceiling; the server is its only caller.
 
 import type { ErrorAudience } from '@ultimat3/core';
-import { auditToolCall, outcomeForCode } from './audit';
+import { outcomeForCode } from './audit';
+import type { McpAuditor } from './audit-hook';
 import { asFrameworkError, renderFrameworkError } from './framework-error';
 import type { AnyMcpTool, McpCaller } from './registry';
 import type { JsonRpcId, JsonRpcResponse } from './wire';
@@ -21,10 +22,11 @@ export function thrownResponse(
   error: unknown,
   caller: McpCaller,
   audience: ErrorAudience,
+  audit: McpAuditor,
 ): JsonRpcResponse {
   const framework = asFrameworkError(error);
   if (framework !== undefined) {
-    auditToolCall({
+    audit.toolCall({
       tool: name,
       outcome: outcomeForCode(framework.code),
       caller,
@@ -35,7 +37,7 @@ export function thrownResponse(
       isError: true,
     });
   }
-  auditToolCall({ tool: name, outcome: 'failed', caller });
+  audit.toolCall({ tool: name, outcome: 'failed', caller });
   return errorResponse(id, INTERNAL_ERROR, `tool "${name}" failed unexpectedly`);
 }