@ultimat3/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @ultimat3/mcp 🤖
+
+The MCP surface. An agent that can reach this package needs no framework documentation — it
+asks instead of guessing.
+
+## The dev server: `x mcp serve`
+
+| Tool | Scope | Answers |
+|---|---|---|
+| `routes.list` | `dev:read` | route table — url, render mode, offline strategy, hydrate, budget |
+| `schema.describe` | `dev:read` | entities with columns, types, invariants |
+| `policies.list` | `dev:read` | every policy: permission, subject, enforcement points |
+| `actions.describe` | `dev:read` | actions + queries: input/output schema, policy, cache tags, MCP exposure |
+| `jobs.inspect` | `dev:read` | job definitions, retry policy, steps (omit `name` for all) |
+| `queue.depth` | `dev:read` | pending / running / failed per queue |
+| `manifest.read` | `dev:read` | `x.manifest.json` verbatim |
+| `errors.explain` | `dev:read` | stable `X_*` code → cause + exact fix command + docs |
+| `db.query` | `db:read` | **read-only, enforced four ways** — SELECT-only role, `BEGIN READ ONLY`, one-statement parse, 5s/1000-row/256 KiB caps |
+| `db.migrate` | `db:migrate` | **branch DB only** — refuses production and any non-branch target |
+| `tests.run` | `dev:test` | runs the suite (executes project code) |
+| `verify.run` | `dev:test` | `x verify` — the shippable contract |
+| `logs.tail` | `dev:logs` | last N lines, optionally per runtime role |
+
+`db.query` and `db.migrate` are gated *and* say so in their own description, so a model that
+reads only the catalog still knows what it is holding.
+
+### `db.query`'s four layers
+
+| Layer | Mechanism | Where |
+|---|---|---|
+| 1. Role | `ultimate_readonly` — `NOLOGIN`, `SELECT` on every table present and future, nothing on sequences; assumed with `SET LOCAL ROLE` inside the transaction, never via a second connection string | `@ultimat3/db` |
+| 2. Transaction | `BEGIN READ ONLY` … `ROLLBACK` on one reserved connection — Postgres refuses the write even if a grant is wrong | `@ultimat3/db` |
+| 3. Parse | one statement, a read leader, no mutating keyword at statement level, no lock — clause **or** `pg_advisory_*` call — and no call into a banned function family, matched by prefix of the called name — quoted and schema-qualified spellings included — so a new spelling is refused by default and a column sharing a prefix is not; on a form with literals and comments blanked | `readonly-sql.ts` |
+| 4. Limits | `SET LOCAL statement_timeout`, a hard 1000-row ceiling (`limit` clamps into it, never past it) and a 256 KiB byte cap | `query-limits.ts` |
+
+The answer carries `guards` — the layers that actually engaged — plus `truncatedBy` and `bytes`.
+A layer that could not engage (a managed Postgres that refuses `CREATE ROLE`) is **absent from
+the list**, never assumed. Truncation is never silent.
+
+## One authz system, two surfaces
+
+Every `action` with `mcp: { expose: true }` becomes a tool for free, and the tool's `handle`
+calls the **same `action.run`** the HTTP route calls. Policy evaluation lives inside `run`.
+
+```
+HTTP  POST /api/publishPost  ─┐
+                              ├─→ action.run({ input, actor }) ─→ policy ─→ handler
+MCP   tools/call publishPost ─┘
+```
+
+`mcp: { visibleTo: [...] }` on the action or query travels with the projection too — the only
+declaration surface outcome 1 has for a projected tool. Catalog audience, never authz.
+
+The projection itself declares **no `scope`** — a projection cannot know what a token means.
+`defineAppMcp`'s `scopes:` map (below) may attach one afterward, as a capability of the
+CONNECTION rather than a second gate: it decides before the policy runs and never reads the
+input, so the two cannot disagree. There is no MCP-specific authorization code to review
+beyond it.
+
+## Security posture: three outcomes, hidden ≠ forbidden
+
+| Refused by | Declared by | Answer | Wire |
+|---|---|---|---|
+| role | `visibleTo` | omitted from `tools/list`, **ToolNotFound** on call, no `data` | `-32601` |
+| scope | `scope` | **Forbidden**, naming the missing scope + a runnable fix | `-32600`, `X_MCP_SCOPE_DENIED` |
+| policy | the primitive's own `policy` | `isError` result carrying code/cause/fix | `X_FORBIDDEN` |
+
+Forbidden confirms a tool exists, which turns an authz boundary into a catalog an agent can
+enumerate by probing. So a role-hidden tool is indistinguishable from an absent one — even
+for a caller holding every scope in the system. A scope refusal is the opposite case: the
+caller was already shown the tool and can legitimately fix this, so hiding it would only
+strand a well-behaved client.
+
+| Rule | Detail |
+|---|---|
+| A role list is fail-closed | a `visibleTo` role list admits only the roles it names, so a caller carrying no role matches none of them |
+| A predicate audience sees the caller and nothing else | it is handed `McpCaller` — never the call arguments, so two calls with different inputs cannot answer differently. Must return the literal `true`; if it throws, the tool is hidden |
+| `tools/list` is answered per caller | filtered on every call against the caller the transport resolved — one per HTTP request, one per stdio connection — never a static catalog |
+| Gate order | visibility → scope → arguments → policy; the scope gate never waits on a policy run against attacker-supplied input |
+| Every outcome is audited | one line per `tools/call`; hidden/scope/policy at `warn`, ok at `info` — see `audit.ts` |
+| Audit lines carry no payload | tool, outcome, actor, code. Never arguments, never rows |
+| No trusted-tool mode | there is no flag that skips policy evaluation |
+
+Executable contract: `security.test.ts`. Rationale: [`docs/architecture/11-ai-surface.md`](../../docs/architecture/11-ai-surface.md).
+
+## Their apps are AI-first too
+
+A generated app exposes its own MCP surface with one call, so the user's agents can drive the
+user's app:
+
+```ts
+// apps/admin/src/mcp.ts
+import { defineAppMcp, t } from '@ultimat3/mcp';
+
+export const mcp = defineAppMcp({
+  name: 'acme-admin',
+  include: 'exposed',                    // every action/query with mcp: { expose: true }
+  resources: [orgExport],
+  prompts: ['apps/web/app/posts/prompts/summarize.v3.md'],
+  tools: {
+    seatReport: {                        // the key IS the tool name
+      description: 'Seats used, remaining and the plan limit. Read-only.',
+      input: t.object({}),               // any Standard Schema
+      policy: 'org:administer',          // an existing permission, never a new rule
+      destructive: false,
+      async handle({ ctx }) {
+        return seats(await ctx.orgs.byId(ctx.actor.orgId));
+      },
+    },
+  },
+  scopes: { 'admin:seats': ['seatReport'] },   // scope name → tool NAMES, by string
+  resolveToken: (token) => sessions.resolveAgentToken(token),
+});
+
+// app.config.ts
+routes: [mcp.route]                      // POST /mcp, rate-limited per method class
+```
+
+`include: 'exposed'` reads the action and query registries instead of asking for
+`actions: [...]` / `queries: [...]` — the registries already know who opted in, and a
+second hand-maintained list is a thing that goes stale silently. The explicit arrays still
+work and win over the registry's copy of the same name.
+
+The two lists are read differently, on purpose. `include` **sweeps**: it holds every primitive
+the app registered, so one that never opted in is passed over. `actions:`/`queries:` are
+**written out**: naming a primitive there is the request to expose it, so one that never declared
+`mcp: { expose: true }` is `X_MCP_TOOL_UNDECLARED` at boot — a listed tool is never silently
+missing from the catalog, and exposure stays declared next to the policy. Two primitives reaching
+one tool name is `X_MCP_TOOL_DUPLICATE`, also at boot.
+
+Both lists take the primitives themselves, exactly as the app declared them:
+
+```ts
+import { publishPost } from '../api/posts';
+
+defineAppMcp({ name: 'postly', actions: [publishPost] });
+// X_MCP_TOOL_UNDECLARED unless publishPost declared mcp: { expose: true }
+```
+
+One adapter serves both routes, so a written-out primitive runs through the same `invoke` (or
+`sourceFor`) the swept one does — the list changes which tools are NAMED, never how one runs.
+An action that was never handed to `defineApi` has no export name, and is
+`X_ACTION_UNREGISTERED` rather than a tool called `''` that nothing could call.
+
+A hand-written tool's `policy` is a permission, evaluated through the same `guard()` an
+HTTP request goes through, so a tool cannot acquire a second authz path. A tool without one
+is `X_MCP_TOOL_UNSAFE` at boot, and an unmarked tool is metered as a write.
+
+`scopes:` (type `McpScopes`, applied through the exported `withScopes`) is outcome 2's
+declaration surface: a scope name → the TOOL NAMES it covers, however each one reached the
+catalog — a projected action, a projected query, or a key in `tools`. It lives here, not
+beside the action, because a scope is a capability of the CONNECTION's token — what
+`x token grant <scope>` names — not a fact about the operation; the policy beside the action
+stays the only rule that reads the input. A name this server does not project is
+`X_MCP_SCOPE_UNKNOWN` at boot; one tool claimed by two scopes is `X_MCP_SCOPE_CONFLICT`.
+
+## Transports
+
+| Transport | Entry | Auth |
+|---|---|---|
+| HTTP | `mcpHttpRoute({ server, resolveToken })` → `POST /mcp` | `Authorization: Bearer <token>` → `Actor { kind: 'agent' }` |
+| stdio | `serveStdio({ server, caller })` | none — the peer already owns the shell |
+
+The HTTP transport exports a route *descriptor*, not a mounted handler: `@ultimat3/http`
+owns the lifecycle, and the descriptor stays drivable from a bare `Request` in a test. It
+carries `rateLimitClass(body)` because all MCP traffic is one URL — a per-route bucket would
+charge `initialize` to the write bucket and throttle an agent on its handshake.
+
+Reads: 120/min. Writes: 20/min. Unresolvable calls bill the write bucket (fail-closed).
+
+## Resources
+
+| URI | Contents |
+|---|---|
+| `ultimate://manifest` | `x.manifest.json` — the generated facts |
+| `ultimate://openapi.json` | OpenAPI 3.1 projected from actions and queries |
+| `ultimate://routes` | route table |
+| `ultimate://schema` | entities, columns, invariants |
+
+Providers are injected thunks: `@ultimat3/manifest` and `@ultimat3/render` sit in this same
+tier, so the CLI wires them and this package owns only the shape and the URIs.
+
+## Argument validation
+
+`tools/list` hands the agent a JSON Schema, so that document is the thing enforced — there is
+no second private validator a tool could be judged against instead. `validate-args.ts`
+implements the emitted subset (objects, arrays, enums, `required`, `additionalProperties`,
+bounds, `default`) and applies declared defaults. Actions still re-parse authoritatively
+inside their own handler.
+
+## Errors
+
+| Code | Meaning |
+|---|---|
+| `X_MCP_TOOL_UNKNOWN` | no visible tool by that name — absent and role-hidden are one answer |
+| `X_MCP_SCOPE_DENIED` | visible, but the connection's token lacks the scope |
+| `X_MCP_SCOPE_UNKNOWN` | `defineAppMcp`'s `scopes:` names a tool this server does not project |
+| `X_MCP_SCOPE_CONFLICT` | two scopes in `defineAppMcp`'s `scopes:` claim one tool |
+| `X_MCP_ARGS_INVALID` | arguments failed the declared schema |
+| `X_MCP_PROTOCOL` | malformed envelope, unknown method, bad auth header |
+| `X_MCP_QUERY_REJECTED` | `db.query` given anything but one read-only statement |
+| `X_MCP_NOT_BRANCH_DB` | `db.migrate` aimed at a production or otherwise non-branch database |

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ultimat3/mcp",
+  "version": "1.0.0",
+  "description": "MCP server, dev tools, and the action-to-tool projection — one authz system, two surfaces",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/mcp"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/action": "1.0.0",
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/entity": "1.0.0",
+    "@ultimat3/jobs": "1.0.0",
+    "@ultimat3/policy": "1.0.0",
+    "@ultimat3/query": "1.0.0",
+    "@ultimat3/schema": "1.0.0"
+  }
+}

package/src/app-tool.ts

@@ -0,0 +1,103 @@
+// The AUTHORING shape of a hand-written app tool, and its normalization into a runtime one.
+//
+// An app declares tools as a NAMED RECORD — the key is the tool name, so the name is written
+// once — and gives a Standard Schema plus a `resource:verb` permission. None of that is what the
+// registry runs, so this file is the mapping to `ProjectablePrimitive`, which `toolsFrom` then
+// projects exactly as it projects an action. One projection, not two.
+//
+// The load-bearing line is `guard(...)` in `run` below: it is the SAME function `invoke` calls
+// for an HTTP request, reached through the same `@ultimat3/action` policy gate. A hand-written
+// tool therefore has no authz of its own — it borrows the action tier's, so a rule change cannot
+// apply to routes and miss tools.
+
+import { actorOf, guard } from '@ultimat3/action';
+import type { Ctx } from '@ultimat3/core';
+import { useContext, withChildContext } from '@ultimat3/core';
+import type { KnownPermission } from '@ultimat3/policy';
+import { can } from '@ultimat3/policy';
+import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
+import { McpToolUnsafeError } from './errors';
+import type { ProjectablePrimitive } from './from-action';
+import { toWireSchema } from './input-schema';
+import type { McpRole } from './registry';
+
+export interface AppToolArgs<TInput extends StandardSchemaV1> {
+  readonly input: InferOutput<TInput>;
+  /** The ambient request context, with `actor` set to the MCP caller. */
+  readonly ctx: Ctx;
+}
+
+export interface AppToolDefinition<TInput extends StandardSchemaV1 = StandardSchemaV1> {
+  /** Says what it does AND whether it costs money or sends mail. Agents read only this. */
+  readonly description: string;
+  /** A Standard Schema. The tool's only argument contract, published by `tools/list`. */
+  readonly input: TInput;
+  /** An existing `resource:verb` permission. Never a new rule invented for MCP. */
+  readonly policy: KnownPermission;
+  /** Catalog visibility, not authz — the policy still decides. */
+  readonly visibleTo?: readonly McpRole[];
+  /**
+   * Defaults to `true`. Fail-closed on purpose: an unmarked tool is metered in the strict
+   * rate-limit bucket, so forgetting the flag costs throughput rather than safety.
+   */
+  readonly destructive?: boolean;
+  // Method syntax (not a property) so a tool declared with narrower args stays assignable.
+  handle(args: AppToolArgs<TInput>): unknown;
+}
+
+/** Schema-erased view — what the normalizer walks once the per-tool types have done their job. */
+export interface AnyAppToolDefinition {
+  readonly description: string;
+  readonly input: StandardSchemaV1;
+  readonly policy: KnownPermission;
+  readonly visibleTo?: readonly McpRole[];
+  readonly destructive?: boolean;
+  handle(args: { readonly input: unknown; readonly ctx: Ctx }): unknown;
+}
+
+/**
+ * The authored record, keyed by tool name. Written as a mapped type over the schemas so each
+ * tool's `handle` infers `input` from that tool's own schema instead of every tool sharing one.
+ */
+export type AppTools<TSchemas extends Readonly<Record<string, StandardSchemaV1>>> = {
+  readonly [K in keyof TSchemas]: AppToolDefinition<TSchemas[K]>;
+};
+
+/** Normalize the authored record into primitives, in the record's own key order. */
+export function appToolPrimitives(
+  tools: Readonly<Record<string, AnyAppToolDefinition>>,
+): readonly ProjectablePrimitive[] {
+  return Object.entries(tools).map(([name, def]) => appToolPrimitive(name, def));
+}
+
+export function appToolPrimitive(name: string, def: AnyAppToolDefinition): ProjectablePrimitive {
+  // Boot-time, not call-time: an unguarded tool must never reach a client, and a server that
+  // starts and then refuses every call is indistinguishable from one that is merely broken.
+  if (typeof def.policy !== 'string' || def.policy.length === 0) {
+    throw new McpToolUnsafeError({ name });
+  }
+  const policy = can(def.policy);
+  const visibleTo = def.visibleTo;
+
+  return {
+    name,
+    description: def.description,
+    // Authoring one implies exposing it — a hand-written tool exists only to be a tool.
+    mcp: {
+      expose: true,
+      description: def.description,
+      ...(visibleTo !== undefined ? { visibleTo } : {}),
+    },
+    inputJsonSchema: toWireSchema(def.input),
+    mutates: def.destructive ?? true,
+    run: ({ input, actor }) =>
+      // The caller is the actor for the WHOLE call. A child context is how the framework
+      // impersonates, so the policy subject and whatever `handle` reads off `ctx.actor` are
+      // the same identity by construction rather than by two call sites agreeing.
+      withChildContext({ actor }, async () => {
+        const ctx = useContext();
+        guard(policy, { actor: actorOf(ctx), input, ctx, action: name }, 'mcp');
+        return def.handle({ input, ctx });
+      }),
+  };
+}

package/src/app-tools.ts

@@ -0,0 +1,190 @@
+// `defineAppMcp` — one call that makes a GENERATED app's own dashboard AI-first.
+//
+// The framework's dev server drives the framework. This is the other half: a user's app
+// exposes its own actions and queries as MCP tools so the user's agents can drive the
+// user's app. Same projection, same policies, same registry — an app gets a real MCP server
+// for the price of `mcp: { expose: true }` on the primitives it already wrote.
+//
+// Deliberately one function: an app author should never have to know that `ToolRegistry`,
+// `frameworkResources` and `mcpHttpRoute` exist.
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { AnyAppToolDefinition, AppTools } from './app-tool';
+import { appToolPrimitives } from './app-tool';
+import { McpToolDuplicateError } from './errors';
+import { exposedPrimitives } from './exposed';
+import { toolsFrom, toolsListed } from './from-action';
+import type { ListedPrimitive } from './projectable';
+import { asProjectable } from './projectable';
+import type { AnyMcpTool } from './registry';
+import type { McpPrompt, McpResource } from './resources';
+import { toPrompts } from './resources';
+import type { McpScopes } from './scopes';
+import { withScopes } from './scopes';
+import type { CreateMcpServerInput } from './server';
+import { createMcpServer, type McpServer } from './server';
+import type { McpRouteDescriptor, ResolvedToken } from './transport-http';
+import { mcpHttpRoute } from './transport-http';
+
+/** Schema map behind the authored `tools` record; inferred per tool, never written by hand. */
+export type AppToolSchemas = Readonly<Record<string, StandardSchemaV1>>;
+
+export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSchemas> {
+  /** Server identity the client shows the user. Defaults to the package name at boot. */
+  readonly name?: string;
+  readonly version?: string;
+  /**
+   * `'exposed'` projects every registered action and query that declared
+   * `mcp: { expose: true }`, and quietly passes over the rest — that list is every primitive the
+   * app registered, not one anyone wrote out. Additive: `actions`/`queries` below still work,
+   * and an explicitly listed primitive wins over the registry's copy of the same name.
+   */
+  readonly include?: 'exposed';
+  /**
+   * Actions to project, as the app declared them: `actions: [publishPost]`. Naming one here IS
+   * the request to expose it, so a listed action that never declared `mcp: { expose: true }` is
+   * `X_MCP_TOOL_UNDECLARED` at boot rather than a tool missing from the catalog — exposure stays
+   * declared next to the policy, never in this list.
+   */
+  readonly actions?: readonly ListedPrimitive[];
+  /** Queries to project. Same rule, same error. */
+  readonly queries?: readonly ListedPrimitive[];
+  /** App-specific readable documents (a catalog export, a report). */
+  readonly resources?: readonly McpResource[];
+  /** Prompts the app ships: a path to a versioned artifact, or the full descriptor. */
+  readonly prompts?: readonly (string | McpPrompt)[];
+  /**
+   * Hand-written tools for things no primitive covers. Rare — prefer an action. Authored as a
+   * record whose KEY is the tool name; the array of ready `McpTool`s stays accepted for
+   * surfaces that build their catalog programmatically (`@ultimat3/admin` does).
+   */
+  readonly tools?: readonly AnyMcpTool[] | AppTools<TSchemas>;
+  /**
+   * Scope name → the tools that capability covers, by tool name. The connection gate, and the
+   * second of the three outcomes: a caller that may SEE a tool but whose token does not carry
+   * its scope is refused `X_MCP_SCOPE_DENIED` naming the scope, BEFORE the policy runs.
+   *
+   * Declared here rather than on the primitive because a scope is a property of the TOKEN, not
+   * of the operation — `x token grant orders:write` and this map name the same thing, and the
+   * policy beside the action stays the only rule that reads the input.
+   *
+   * ```ts
+   * scopes: { 'orders:write': ['refundOrder'], 'catalog:admin': ['reindexCatalog'] },
+   * ```
+   */
+  readonly scopes?: McpScopes;
+  /** Bearer-token resolution. Omit to expose no HTTP route (stdio/embedded only). */
+  resolveToken?(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
+  /** Mount path. Defaults to `/mcp`. */
+  readonly path?: string;
+}
+
+export interface AppMcp {
+  readonly server: McpServer;
+  /** The projected catalog, so a test can assert exactly what the app exposes. */
+  readonly tools: readonly AnyMcpTool[];
+  /** `undefined` when no `resolveToken` was given. */
+  readonly route: McpRouteDescriptor | undefined;
+}
+
+/**
+ * Project an app's primitives into a ready MCP server.
+ *
+ * ```ts
+ * // apps/admin/src/mcp.ts
+ * export const mcp = defineAppMcp({
+ *   name: 'acme-admin',
+ *   include: 'exposed',
+ *   prompts: ['apps/web/app/posts/prompts/summarize.v3.md'],
+ *   tools: {
+ *     seatReport: {
+ *       description: 'Seats used, remaining and the plan limit. Read-only.',
+ *       input: t.object({}),
+ *       policy: 'org:administer',
+ *       async handle({ ctx }) {
+ *         return seats(await ctx.orgs.byId(ctx.actor.orgId));
+ *       },
+ *     },
+ *   },
+ *   resolveToken: (token) => sessions.resolveAgentToken(token),
+ * });
+ * ```
+ */
+export function defineAppMcp<TSchemas extends AppToolSchemas>(
+  input: DefineAppMcpInput<TSchemas>,
+): AppMcp {
+  // `toolsListed`, not `toolsFrom`: these two arrays are what the author wrote out, so an
+  // undeclared entry is a mistake to report, not a primitive to pass over. ONE call over both
+  // arrays, because `toolsListed` collects every offender before throwing — calling it twice
+  // would throw on the first undeclared action and never look at the queries, so the author
+  // fixes one list, re-boots, and meets a second `X_MCP_TOOL_UNDECLARED`.
+  const listed = toolsListed(
+    [...(input.actions ?? []), ...(input.queries ?? [])].map(asProjectable),
+  );
+  // An explicitly listed primitive is a refinement of the registry's entry, not a rival to it,
+  // so `include` fills the gaps rather than colliding with what the caller already spelled out.
+  const included =
+    input.include === 'exposed' ? notNamed(toolsFrom(exposedPrimitives()), listed) : [];
+  const named = [...listed, ...included, ...handWritten(input.tools)];
+  // Unique names FIRST: the scope map addresses tools by name, so a duplicate would make
+  // "which tool did this scope gate?" unanswerable before the question is worth asking.
+  assertUniqueNames(named);
+  const projected = withScopes(named, input.scopes);
+
+  const config: CreateMcpServerInput = {
+    tools: projected,
+    resources: input.resources ?? [],
+    prompts: toPrompts(input.prompts ?? []),
+    serverInfo: { name: input.name ?? 'ultimate-app', version: input.version ?? '0.0.0' },
+  };
+  const server = createMcpServer(config);
+
+  const resolveToken = input.resolveToken;
+  const route =
+    resolveToken === undefined
+      ? undefined
+      : mcpHttpRoute({
+          server,
+          resolveToken,
+          ...(input.path !== undefined ? { path: input.path } : {}),
+        });
+
+  return { server, tools: projected, route };
+}
+
+/**
+ * The record form is normalized into primitives and then handed to the SAME `toolsFrom` that
+ * projects an action — which is what makes "one projection, one authz path" true rather than
+ * asserted. The array form is already a projected catalog and passes through untouched, so a
+ * surface that builds its tools programmatically (`@ultimat3/admin`) keeps working verbatim.
+ */
+function handWritten(
+  tools: readonly AnyMcpTool[] | AppTools<AppToolSchemas> | undefined,
+): readonly AnyMcpTool[] {
+  if (tools === undefined) return [];
+  if (Array.isArray(tools)) return tools as readonly AnyMcpTool[];
+  return toolsFrom(appToolPrimitives(tools as Readonly<Record<string, AnyAppToolDefinition>>));
+}
+
+function notNamed(
+  tools: readonly AnyMcpTool[],
+  exclude: readonly AnyMcpTool[],
+): readonly AnyMcpTool[] {
+  const taken = new Set(exclude.map((tool) => tool.name));
+  return tools.filter((tool) => !taken.has(tool.name));
+}
+
+/**
+ * A duplicate tool name is caught here rather than at first call: two primitives projecting
+ * to one name means the agent silently reaches the wrong one, which is the worst failure
+ * mode available. Boot-time, loud, and named.
+ */
+function assertUniqueNames(tools: readonly AnyMcpTool[]): void {
+  const seen = new Set<string>();
+  for (const tool of tools) {
+    if (seen.has(tool.name)) {
+      throw new McpToolDuplicateError({ name: tool.name });
+    }
+    seen.add(tool.name);
+  }
+}

package/src/audit.ts

@@ -0,0 +1,92 @@
+// One structured line per `tools/call`, whatever the outcome — including the outcomes that
+// deliberately tell the caller nothing.
+//
+// The three-outcome model works by giving a prober no signal. That is a property of the
+// ANSWER, not of the system: enumeration is a pattern across many requests, so the refusal
+// that reveals nothing to the caller still has to be visible to whoever reads the logs.
+// Hence ToolNotFound is audited at `warn` — a run of them is the detectable shape of a name
+// walk. Fields carry the decision, never the data it was made about.
+
+import type { LogFields, Logger } from '@ultimat3/core';
+import { logger } from '@ultimat3/core';
+import type { McpCaller } from './registry';
+
+/** What happened to one `tools/call`. The three security outcomes, plus the two that are not. */
+export type McpOutcome =
+  /** Ran, and the tool answered. */
+  | 'ok'
+  /** OUTCOME 1: absent, or hidden from this caller's role. Answered ToolNotFound. */
+  | 'hidden'
+  /** OUTCOME 2: visible, but the connection's token lacks the tool's scope. */
+  | 'scope-denied'
+  /** OUTCOME 3: ran, and the tool's own policy refused this input. */
+  | 'policy-denied'
+  /** Arguments failed the schema the agent was handed. Not an authz outcome. */
+  | 'invalid-args'
+  /**
+   * The handler threw something that is not an authz denial: a non-authz framework refusal
+   * (`db.migrate` aimed at prod), or a bug. Both want a human — a projected action rejecting
+   * input MCP already validated means the JSON Schema and the real schema have drifted.
+   */
+  | 'failed';
+
+/**
+ * Codes that mean authz said no, wherever in the stack it decided. `X_POLICY_DENIED` used to sit
+ * here and matched nothing: `@ultimat3/policy` owns the denial and throws `X_FORBIDDEN`, so the
+ * entry classified a code no build can produce — and every real denial that reached it still had
+ * to be recognised by one of the other two.
+ */
+const DENIAL_CODES: ReadonlySet<string> = new Set(['X_FORBIDDEN', 'X_UNAUTHENTICATED']);
+
+/** Classify a code a tool threw. Denials are outcome 3; everything else wants a human. */
+export function outcomeForCode(code: string): McpOutcome {
+  return DENIAL_CODES.has(code) ? 'policy-denied' : 'failed';
+}
+
+export interface McpAuditEntry {
+  readonly tool: string;
+  readonly outcome: McpOutcome;
+  readonly caller: McpCaller;
+  /** The scope the call needed, on a `scope-denied` outcome. */
+  readonly scope?: string;
+  /** The `X_*` code the outcome carried, when it carried one. */
+  readonly code?: string;
+}
+
+/**
+ * Severity per outcome. Every refusal a prober can drive is `warn` so one alert rule covers
+ * the whole enumeration surface; `invalid-args` is a well-behaved client misreading a schema,
+ * and an unexpected throw is the only `error` because it is the only one that is a bug.
+ */
+const LEVEL: Readonly<Record<McpOutcome, 'info' | 'warn' | 'error'>> = Object.freeze({
+  ok: 'info',
+  hidden: 'warn',
+  'scope-denied': 'warn',
+  'policy-denied': 'warn',
+  'invalid-args': 'info',
+  failed: 'error',
+});
+
+/**
+ * Audit one call. `log` is a parameter so a test can read the line it produced; production
+ * callers pass nothing and get the process logger, which is the only sink — there is no
+ * switch that turns auditing off.
+ *
+ * Deliberately NOT logged: the call's arguments and anything the tool loaded. A denial reason
+ * that names `post p_42 in org o_9` is a row leak wearing an audit line's clothes.
+ */
+export function auditToolCall(entry: McpAuditEntry, log: Logger = logger): void {
+  const fields: LogFields = {
+    surface: 'mcp',
+    tool: entry.tool,
+    outcome: entry.outcome,
+    actor: entry.caller.actor.id,
+    actorKind: entry.caller.actor.kind,
+    ...(entry.caller.role === undefined ? {} : { role: entry.caller.role }),
+    ...(entry.scope === undefined ? {} : { scope: entry.scope }),
+    ...(entry.code === undefined ? {} : { code: entry.code }),
+  };
+  // `<subsystem>.<event>.<outcome>`, matching every other structured line in the framework,
+  // so `x logs --json | grep mcp.tool-call.hidden` is the whole enumeration alert.
+  log[LEVEL[entry.outcome]](`mcp.tool-call.${entry.outcome}`, fields);
+}