@ultimat3/mcp 24.0.0 → 25.0.0

package/src/confirmation-postgres.ts

@@ -0,0 +1,143 @@
+// The shared confirmation store: one Postgres table, the open row held unique by a partial index so
+// two identical agent calls racing open ONE row, and every transition a single conditional UPDATE.
+// Statements are spelled out so an operator can run the exact one a log line names.
+
+import type { PgExecutor } from '@ultimat3/core';
+import { McpConfirmationContestedError } from './confirmation-errors';
+import type {
+  McpConfirmation,
+  McpConfirmationStatus,
+  McpConfirmationStore,
+} from './confirmation-store';
+
+export const SQL_MCP_CONFIRMATION_OPEN = `
+insert into x_mcp_confirmations
+  (id, actor_id, org_id, tool, input_digest, sealed_arguments, created_at, expires_at)
+values ($1, $2, $3, $4, $5, $6, $7, $8)
+on conflict (actor_id, tool, input_digest) where consumed_at is null do nothing
+returning *
+`;
+
+export const SQL_MCP_CONFIRMATION_OPEN_ROW = `
+select * from x_mcp_confirmations
+where actor_id = $1 and tool = $2 and input_digest = $3 and consumed_at is null
+`;
+
+export const SQL_MCP_CONFIRMATION_GET = 'select * from x_mcp_confirmations where id = $1';
+
+export const SQL_MCP_CONFIRMATION_DECIDE = `
+update x_mcp_confirmations set status = $2, decided_by = $3, decided_at = $4
+where id = $1 and status = 'pending' and consumed_at is null and expires_at > $4
+returning *
+`;
+
+export const SQL_MCP_CONFIRMATION_CONSUME = `
+update x_mcp_confirmations set consumed_at = $2 where id = $1 and consumed_at is null returning id
+`;
+
+export const SQL_MCP_CONFIRMATION_PURGE = `
+with purged as (delete from x_mcp_confirmations where expires_at < $1 returning 1)
+select count(*)::int as purged from purged
+`;
+
+interface Row {
+  readonly id: string;
+  readonly actor_id: string;
+  readonly org_id: string | null;
+  readonly tool: string;
+  readonly input_digest: string;
+  readonly sealed_arguments: string;
+  readonly status: string;
+  readonly created_at: Date | string;
+  readonly expires_at: Date | string;
+  readonly decided_at: Date | string | null;
+  readonly decided_by: string | null;
+  readonly consumed_at: Date | string | null;
+}
+
+export interface PostgresConfirmationStoreOptions {
+  /**
+   * A real `PgExecutor` over the process's client — read on every call, so a declaration evaluated
+   * before the boot opened the pool still reaches it: `{ query: (text, values) => db().query(…) }`.
+   */
+  readonly executor: PgExecutor;
+}
+
+export function postgresConfirmationStore(
+  options: PostgresConfirmationStoreOptions,
+): McpConfirmationStore {
+  const exec = options.executor;
+  const first = async (sql: string, params: readonly unknown[]) => {
+    const row = (await exec.query<Row>(sql, params))[0];
+    return row === undefined ? undefined : toConfirmation(row);
+  };
+  return {
+    async open(draft) {
+      // Bounded: the insert and the read can both come back empty only when a concurrent consume
+      // freed the key between them, and the next insert then wins it.
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        const created = await first(SQL_MCP_CONFIRMATION_OPEN, [
+          draft.id,
+          draft.actorId,
+          draft.orgId,
+          draft.tool,
+          draft.inputDigest,
+          draft.sealedArguments,
+          draft.createdAt,
+          draft.expiresAt,
+        ]);
+        if (created !== undefined) return { row: created, created: true };
+        const held = await first(SQL_MCP_CONFIRMATION_OPEN_ROW, [
+          draft.actorId,
+          draft.tool,
+          draft.inputDigest,
+        ]);
+        if (held !== undefined) return { row: held, created: false };
+      }
+      // Never reported as created: the caller would tell the agent a row exists that does not.
+      throw new McpConfirmationContestedError(draft.tool);
+    },
+    get: (id) => first(SQL_MCP_CONFIRMATION_GET, [id]),
+    decide: (id, status, by, at) => first(SQL_MCP_CONFIRMATION_DECIDE, [id, status, by, at]),
+    async consume(id, at) {
+      return (await exec.query(SQL_MCP_CONFIRMATION_CONSUME, [id, at])).length === 1;
+    },
+    async purge(before) {
+      const rows = await exec.query<{ purged: number | string }>(SQL_MCP_CONFIRMATION_PURGE, [
+        before,
+      ]);
+      return Number(rows[0]?.purged ?? 0);
+    },
+  };
+}
+
+const STATUSES: ReadonlySet<string> = new Set<McpConfirmationStatus>([
+  'pending',
+  'approved',
+  'rejected',
+]);
+
+/** Every Postgres client answers `timestamptz` as a `Date` or an ISO string; both read the same. */
+const dateOf = (value: Date | string): Date => (value instanceof Date ? value : new Date(value));
+const maybeDate = (value: Date | string | null): Date | null =>
+  value === null ? null : dateOf(value);
+
+function toConfirmation(row: Row): McpConfirmation {
+  // A status this file never writes is a row someone edited by hand: read as `rejected`, the one
+  // reading that can neither run the call nor be decided again.
+  const status = STATUSES.has(row.status) ? (row.status as McpConfirmationStatus) : 'rejected';
+  return {
+    id: row.id,
+    actorId: row.actor_id,
+    orgId: row.org_id,
+    tool: row.tool,
+    inputDigest: row.input_digest,
+    sealedArguments: row.sealed_arguments,
+    status,
+    createdAt: dateOf(row.created_at),
+    expiresAt: dateOf(row.expires_at),
+    decidedAt: maybeDate(row.decided_at),
+    decidedBy: row.decided_by,
+    consumedAt: maybeDate(row.consumed_at),
+  };
+}

package/src/confirmation-schema.ts

@@ -0,0 +1,34 @@
+// The DDL of `mcpConfirmations`' one framework table, and nothing else: a LEAF module, so the
+// boot's `FRAMEWORK_SCHEMA` (`@ultimat3/cli`) applies it in every role through
+// `@ultimat3/mcp/schema` without pulling the MCP server, its transports or `@ultimat3/action`
+// into a worker's module graph. Imports nothing, by design.
+
+/** The table. One name, read by this DDL and by `confirmation-postgres.ts`'s statements. */
+export const MCP_CONFIRMATIONS_TABLE = 'x_mcp_confirmations';
+
+/**
+ * Applied by the boot, never by an app migration — the rule `SQL_IDEMPOTENCY_TABLE` follows.
+ * `create … if not exists` throughout, so every boot can run it; a new column is an
+ * `alter table … add column if not exists`, never an edit to the `create`.
+ */
+export const SQL_MCP_CONFIRMATIONS_TABLE = `
+create table if not exists x_mcp_confirmations (
+  id           uuid        primary key,
+  actor_id     text        not null,
+  org_id       text,
+  tool         text        not null,
+  input_digest text        not null,
+  sealed_arguments text    not null,
+  status       text        not null default 'pending',
+  created_at   timestamptz not null,
+  expires_at   timestamptz not null,
+  decided_at   timestamptz,
+  decided_by   text,
+  consumed_at  timestamptz
+);
+
+create unique index if not exists x_mcp_confirmations_open_idx
+  on x_mcp_confirmations (actor_id, tool, input_digest) where consumed_at is null;
+
+create index if not exists x_mcp_confirmations_expires_at_idx on x_mcp_confirmations (expires_at);
+`;

package/src/confirmation-store.ts

@@ -0,0 +1,136 @@
+// Where a pending MCP confirmation lives between the agent's call and a human's decision: the row,
+// the store contract both drivers answer, and the memory driver. Postgres is
+// `confirmation-postgres.ts`; `confirmation-store.contract.test.ts` holds the two to one answer.
+
+/** `pending` until a human decides; a decision is final. Expiry and consumption are timestamps. */
+export type McpConfirmationStatus = 'pending' | 'approved' | 'rejected';
+
+/**
+ * One call an agent made that a human has to confirm: WHO asked, WHICH tool, and WHAT with — the
+ * arguments SEALED (never plaintext at rest) so the person deciding sees exactly what they approve,
+ * and their keyed digest, which the approval must match.
+ */
+export interface McpConfirmation {
+  readonly id: string;
+  /** The asking agent actor's id. */
+  readonly actorId: string;
+  /** Its org, so an app's `check` can keep a decision inside the tenant. `null` when it has none. */
+  readonly orgId: string | null;
+  readonly tool: string;
+  /**
+   * `keyedFingerprint` of the validated arguments (`h1:<key id>:<HMAC>`) — keyed because it is stored.
+   * The approval binds to it; a rotated signing secret makes the same call a new confirmation.
+   */
+  readonly inputDigest: string;
+  /** The validated arguments as JSON, `seal()`ed for `MCP_CONFIRMATION_ARGUMENTS_PURPOSE`. */
+  readonly sealedArguments: string;
+  readonly status: McpConfirmationStatus;
+  readonly createdAt: Date;
+  /** After this instant the row can be neither decided nor used. */
+  readonly expiresAt: Date;
+  readonly decidedAt: Date | null;
+  /** The deciding actor's id. */
+  readonly decidedBy: string | null;
+  /**
+   * When the asking agent's next identical call took the outcome — ran it, or was told it was
+   * rejected or expired. A consumed row is history: the same call afterwards asks again.
+   */
+  readonly consumedAt: Date | null;
+}
+
+export type McpConfirmationDraft = Pick<
+  McpConfirmation,
+  | 'id'
+  | 'actorId'
+  | 'orgId'
+  | 'tool'
+  | 'inputDigest'
+  | 'sealedArguments'
+  | 'createdAt'
+  | 'expiresAt'
+>;
+
+export interface McpConfirmationStore {
+  /**
+   * The OPEN (unconsumed) row for this actor + tool + digest, or a new pending one built from
+   * `draft` when there is none — atomically, so two identical calls racing open ONE row.
+   */
+  open(draft: McpConfirmationDraft): Promise<{ row: McpConfirmation; created: boolean }>;
+  get(id: string): Promise<McpConfirmation | undefined>;
+  /**
+   * Pending, unconsumed and unexpired at `at` → `status`. `undefined` when the row is not in that
+   * state (or does not exist): a decision is taken once, and the caller re-reads to say why.
+   */
+  decide(
+    id: string,
+    status: 'approved' | 'rejected',
+    by: string,
+    at: Date,
+  ): Promise<McpConfirmation | undefined>;
+  /** Unconsumed → consumed at `at`. `false` when another call took it first. */
+  consume(id: string, at: Date): Promise<boolean>;
+  /** Delete every row that expired before `before`, and answer how many — run it from a `task`. */
+  purge(before: Date): Promise<number>;
+}
+
+const openKey = (row: Pick<McpConfirmation, 'actorId' | 'tool' | 'inputDigest'>): string =>
+  JSON.stringify([row.actorId, row.tool, row.inputDigest]);
+
+/**
+ * Per PROCESS: right for a test and for `x dev`, and a lie for a fleet — an agent's call opens the
+ * row on one replica and a human's approval lands on another. A deployment passes
+ * `postgresConfirmationStore({ executor })`.
+ */
+export function memoryConfirmationStore(): McpConfirmationStore {
+  const rows = new Map<string, McpConfirmation>();
+  /** open-key → id of the row no call has consumed yet. At most one per key, as Postgres' index. */
+  const open = new Map<string, string>();
+  const put = (row: McpConfirmation): McpConfirmation => {
+    rows.set(row.id, row);
+    return row;
+  };
+  return {
+    async open(draft) {
+      const existing = open.get(openKey(draft));
+      const held = existing === undefined ? undefined : rows.get(existing);
+      if (held !== undefined) return { row: held, created: false };
+      const row = put({
+        ...draft,
+        status: 'pending',
+        decidedAt: null,
+        decidedBy: null,
+        consumedAt: null,
+      });
+      open.set(openKey(row), row.id);
+      return { row, created: true };
+    },
+    async get(id) {
+      return rows.get(id);
+    },
+    async decide(id, status, by, at) {
+      const row = rows.get(id);
+      if (row === undefined || row.status !== 'pending' || row.consumedAt !== null)
+        return undefined;
+      if (row.expiresAt.getTime() <= at.getTime()) return undefined;
+      return put({ ...row, status, decidedBy: by, decidedAt: at });
+    },
+    async consume(id, at) {
+      const row = rows.get(id);
+      if (row === undefined || row.consumedAt !== null) return false;
+      put({ ...row, consumedAt: at });
+      open.delete(openKey(row));
+      return true;
+    },
+    async purge(before) {
+      let purged = 0;
+      for (const row of [...rows.values()]) {
+        if (row.expiresAt.getTime() >= before.getTime()) continue;
+        rows.delete(row.id);
+        // An unconsumed row IS its key's open row: `open` holds exactly the unconsumed one per key.
+        if (row.consumedAt === null) open.delete(openKey(row));
+        purged += 1;
+      }
+      return purged;
+    },
+  };
+}

package/src/confirmations.ts

@@ -0,0 +1,147 @@
+// `mcpConfirmations` — human confirmation for named MCP tools, as a FACTORY OVER `action`, never a
+// ninth primitive. What it returns IS the decision action (`{ id, decision: 'approve' | 'reject' }`):
+// registered like any other, it has its route, OpenAPI operation, typed client and audit record, and
+// its policy is decided by `guard()` like every other write. The gate the agent meets lives in
+// `confirmation-gate.ts`, applied by `defineAppMcp({ confirmations })`.
+
+import type { Action } from '@ultimat3/action';
+import { action } from '@ultimat3/action';
+import type { Clock, SealKeySource } from '@ultimat3/core';
+import { finiteCount, systemClock } from '@ultimat3/core';
+import type { KnownPermission, PolicyArgs, PolicyDecision } from '@ultimat3/policy';
+import { can, denied } from '@ultimat3/policy';
+import type { JsonValue } from '@ultimat3/schema';
+import { t } from '@ultimat3/schema';
+import { decideConfirmation } from './confirmation-decide';
+import { McpConfirmationToolUnknownError } from './confirmation-errors';
+import type { McpConfirmation, McpConfirmationStore } from './confirmation-store';
+
+/** Ten minutes: long enough for a person to read a request, short enough to go stale. */
+export const DEFAULT_MCP_CONFIRMATION_TTL_MS = 600_000;
+
+const decisionInput = () =>
+  t.object({
+    id: t.uuid,
+    decision: t.enum(['view', 'approve', 'reject'] as const),
+    /** What the person approves: the `arguments` `view` returned. Required to approve. */
+    arguments: t.optional(t.record(t.json())),
+  });
+
+const decisionOutput = () =>
+  t.object({
+    id: t.string,
+    tool: t.string,
+    status: t.enum(['pending', 'approved', 'rejected'] as const),
+    decidedAt: t.nullable(t.date),
+    expiresAt: t.date,
+    arguments: t.record(t.json()),
+  });
+
+type DecisionInput = ReturnType<typeof decisionInput>;
+type DecisionOutput = ReturnType<typeof decisionOutput>;
+
+/**
+ * What a decision is asked with. `view` reads the request exactly as the agent sent it; `approve`
+ * must carry those `arguments` back, so what a person approves is what they were shown.
+ */
+export interface McpConfirmationDecision {
+  readonly id: string;
+  readonly decision: 'view' | 'approve' | 'reject';
+  readonly arguments?: Readonly<Record<string, JsonValue>>;
+}
+
+export interface McpConfirmationsInput<TTools extends string = string> {
+  /** The tools whose every call waits for a person. Each must be one the server projects. */
+  readonly tools: readonly TTools[];
+  /** `memoryConfirmationStore()` for a test or `x dev`; `postgresConfirmationStore()` for a fleet. */
+  readonly store: McpConfirmationStore;
+  /** What the deciding actor must hold — the action's permission, read by `can()`. */
+  readonly permission: KnownPermission;
+  /**
+   * WHO may view and decide WHICH confirmation — the app's rule, over the decider and the loaded
+   * row (`row.orgId`, `row.actorId`): "an admin, or the user whose agent asked". Absent, the decider
+   * must be in the asking agent's org (`row.orgId === (actor.orgId ?? null)`) and a missing row is
+   * refused; crossing tenants takes an explicit `check`. An agent never decides one whatever this says.
+   */
+  readonly check?: (args: PolicyArgs<unknown, McpConfirmation>) => boolean | PolicyDecision;
+  /** How long a confirmation stays decidable and usable. Defaults to `DEFAULT_MCP_CONFIRMATION_TTL_MS`. */
+  readonly ttlMs?: number | undefined;
+  /** Stamps creation, expiry and decision. Defaulted, never read inline, so a test can move it. */
+  readonly clock?: Clock | undefined;
+  /** Record every decision through core's `AuditSink`, like any `audit: true` action. */
+  readonly audit?: boolean | undefined;
+  /** Where the seal key is read (`.secrets.key` / `ULTIMATE_SECRETS_KEY`). Defaults to the app's. */
+  readonly sealKeys?: SealKeySource | undefined;
+}
+
+/** The decision action, carrying what the gate needs. `defineAppMcp({ confirmations })` reads it. */
+export interface McpConfirmations<TTools extends string = string>
+  extends Action<DecisionInput, DecisionOutput> {
+  /** The gated names, as written — typed, so a test or a screen can name one without a cast. */
+  readonly tools: readonly TTools[];
+  readonly store: McpConfirmationStore;
+  readonly ttlMs: number;
+  readonly clock: Clock;
+  readonly sealKeys: SealKeySource;
+}
+
+/**
+ * ```ts
+ * // apps/web/app/orders/actions/confirm-refunds.ts
+ * export const confirmRefunds = mcpConfirmations({
+ *   tools: ['refundOrder'],
+ *   store: postgresConfirmationStore({ executor }),
+ *   permission: 'order:refund',
+ * });
+ * // apps/web/app/mcp.ts
+ * export const mcp = defineAppMcp({ include: 'exposed', confirmations: confirmRefunds, … });
+ * ```
+ */
+export function mcpConfirmations<const TTools extends string>(
+  input: McpConfirmationsInput<TTools>,
+): McpConfirmations<TTools> {
+  if (input.tools.length === 0)
+    throw new McpConfirmationToolUnknownError({ unknown: [], known: [] });
+  const ttlMs = finiteCount(
+    'mcpConfirmations',
+    'ttlMs',
+    input.ttlMs ?? DEFAULT_MCP_CONFIRMATION_TTL_MS,
+    1,
+  );
+  const clock = input.clock ?? systemClock;
+  const { store, check } = input;
+  const sealKeys: SealKeySource = input.sealKeys ?? {};
+
+  const decide = action({
+    input: decisionInput(),
+    output: decisionOutput(),
+    // The agent refusal is IN the policy, so it is decided by `guard()` — the one authz path — and
+    // reads as the same `X_FORBIDDEN` on every surface. A confirmation an agent can grant is a
+    // confirmation the agent that asked can grant.
+    policy: can<unknown, McpConfirmation>(input.permission, (args) => {
+      if (args.actor?.kind === 'agent') return denied('mcp-confirmation.agent-decider');
+      return (check ?? sameTenant)(args);
+    }),
+    ...(input.audit === true ? { audit: true } : {}),
+    row: async ({ input: asked }) => (await store.get(asked.id)) ?? null,
+    // The view and the decision: state only — the policy above has already decided who.
+    handle: ({ input: asked, ctx }) =>
+      decideConfirmation({ store, clock, sealKeys }, asked, ctx.actor.id),
+  });
+  return Object.assign(decide, {
+    tools: Object.freeze([...input.tools]),
+    store,
+    ttlMs,
+    clock,
+    sealKeys,
+  });
+}
+
+/**
+ * The default `check`: the decider is in the asking agent's org, and a missing row is refused — so
+ * "unknown id" and "another tenant's id" are one answer. An org-less agent's row is decided only by
+ * an org-less person; anything wider is an explicit `check`.
+ */
+function sameTenant(args: PolicyArgs<unknown, McpConfirmation>): boolean {
+  return args.row !== null && args.row.orgId === (args.actor?.orgId ?? null);
+}

package/src/dev-host.ts

@@ -12,7 +12,7 @@ import type { DevCapabilities, DevHost, DevIntrospection } from './dev-server';
 import { devTools } from './dev-server';
 import type { FrameworkResourceProviders } from './resources';
 import { frameworkResources } from './resources';
-import { createMcpServer, type McpServer } from './server';
+import { type McpServer, mcpServer } from './server';
 
 /**
  * The description half of a real app's `DevHost`. `routes` and `policies` are supplied by
@@ -39,14 +39,14 @@ export function frameworkIntrospection(
   };
 }
 
-export interface CreateDevServerInput {
+export interface DevMcpServerInput {
   readonly host: DevHost;
   readonly resources?: FrameworkResourceProviders;
 }
 
 /** `x mcp serve` and `POST /mcp` in dev both build the server through this. */
-export function createDevServer(input: CreateDevServerInput): McpServer {
-  return createMcpServer({
+export function devMcpServer(input: DevMcpServerInput): McpServer {
+  return mcpServer({
     tools: devTools(input.host),
     resources: frameworkResources(input.resources ?? {}),
     serverInfo: { name: 'ultimate-dev', version: frameworkVersion() },

package/src/errors-transport.ts

@@ -0,0 +1,94 @@
+// The refusals a TRANSPORT raises before dispatch: one message too large for the wire, a caller
+// past its rate allowance, an `oauth` block that cannot be published. Split from `errors.ts`,
+// which keeps the code registry; this module loads it, so every title is registered first.
+
+import { UltimateError } from '@ultimat3/core';
+// why a side-effect import: the codes these classes raise are REGISTERED by `errors.ts`, and a
+// process that imports only a transport must still render their titles.
+import './errors';
+
+/**
+ * One message larger than the transport holds. Its own code, for the reason `X_MCP_RATE_LIMITED`
+ * below is not `X_RATE_LIMITED`: `@ultimat3/http`'s `X_BODY_INVALID` names `bodyLimitBytes` on the
+ * HTTP pipeline, and this route never passes through it — the knob is `mcpHttpRoute`'s (or
+ * `defineAppMcp`'s, which forwards it), and over stdio it is `serveStdio({ lineLimitBytes })`, a
+ * ceiling in characters rather than bytes. One class for both transports, because the condition is
+ * one: the peer sent more in one message than this end agreed to hold, and the two answers must
+ * name the same code so an agent learns it once.
+ *
+ * Measured through ai-maxxing's `POST /mcp` on 2026-09-07: the 413 was a bare `-32600` reading
+ * `request body is at least N bytes, limit is M` — two numbers and no next step, while the 401,
+ * 403 and 429 beside it all carried `{ code, cause, fix }`. A box agent sending a large
+ * `promptSession` had nothing to act on. The fix names both moves, send less or raise the cap,
+ * because which one is right is the author's call: a prompt can be split, a paged result cannot
+ * always be, and a cap set by default was never a decision anyone made about this app.
+ */
+export class McpBodyTooLargeError extends UltimateError {
+  readonly limit: number;
+
+  constructor(input: { transport: 'http' | 'stdio'; limit: number; over?: number | undefined }) {
+    const http = input.transport === 'http';
+    // A NUMBER in the fix, never a `<n>`: the contract is a one-line edit that runs as written. The
+    // cap itself would run and change nothing; twice the larger of the cap and what arrived is a
+    // value that admits this message, whichever of the two was the shorter measure. Both are
+    // finite non-negative integers by the transports' own screens, so the product is too.
+    const raised = 2 * Math.max(input.limit, input.over ?? 0);
+    super({
+      code: 'X_MCP_BODY_TOO_LARGE',
+      cause: http
+        ? `request body is at least ${input.over ?? input.limit} bytes, limit is ${input.limit}`
+        : `one message exceeded ${input.limit} characters and was dropped`,
+      fix: http
+        ? `send less in one request — page a large read, split a long prompt across calls — or raise the cap where the route is built: mcpHttpRoute({ bodyLimitBytes: ${raised} }) or defineAppMcp({ bodyLimitBytes: ${raised} })`
+        : `send one JSON-RPC message per line, each under the cap — split a large tool result into paged calls — or raise it where the transport is started: serveStdio({ lineLimitBytes: ${raised} })`,
+      // The numbers as FIELDS, not only prose: a `--json` reader and the wire's `data` both want
+      // the limit without re-parsing a sentence.
+      meta: {
+        transport: input.transport,
+        limit: input.limit,
+        ...(input.over === undefined ? {} : { over: input.over }),
+      },
+    });
+    this.limit = input.limit;
+  }
+}
+
+/**
+ * The transport's own throttle, and its own CODE rather than `@ultimat3/http`'s `X_RATE_LIMITED`
+ * — not because the maths differ (they are the same `Bucket`, the same store and the same
+ * `rateLimitDecision`) but because the KNOB does. `X_RATE_LIMITED` tells an operator to raise
+ * `rateLimit.buckets` through `configureHttp()`, which governs the HTTP pipeline and not this route: all
+ * MCP traffic is one URL and the class comes from the parsed body, so `mcpHttpRoute` meters itself.
+ * A fix line that runs and changes nothing is worse than none — the same rule
+ * `@ultimat3/realtime`'s `SubscriptionLimitError` follows when it names the knob over the default.
+ *
+ * The bucket key names the ACTOR and never reaches the caller: a 429 is provokable by anyone
+ * holding a valid token, and an org id or an actor id in the body of one is a leak wearing a
+ * throttle's clothes.
+ */
+export class McpRateLimitedError extends UltimateError {
+  constructor(input: { verbClass: string; limit: number; retryAfterSeconds: number }) {
+    super({
+      code: 'X_MCP_RATE_LIMITED',
+      cause: `this caller has spent its ${input.limit} ${input.verbClass} requests per minute; the bucket refills in ${input.retryAfterSeconds}s`,
+      fix: `wait ${input.retryAfterSeconds}s — the Retry-After header carries the same number — or raise it where the route is built: mcpHttpRoute({ rateLimits: { ${input.verbClass}: <n> } }), or defineAppMcp({ rateLimits })`,
+      // why `meta` and not only the sentence: `transport-http.ts` writes `Retry-After` by hand, so
+      // this route is correct today. `@ultimat3/http`'s `retryAfterOf` reads the header off
+      // `meta.retryAfterSeconds` — so the day an MCP host is mounted inside that pipeline, an error
+      // carrying the number only in its prose sheds a caller with no delay to honour, which is the
+      // stampede `admit` exists to spread.
+      meta: { retryAfterSeconds: input.retryAfterSeconds },
+    });
+  }
+}
+
+/** `defineAppMcp({ oauth })` refused at boot — see `oauth-metadata.ts`. */
+export class McpOAuthInvalidError extends UltimateError {
+  constructor(reason: string) {
+    super({
+      code: 'X_MCP_OAUTH_INVALID',
+      cause: `defineAppMcp({ oauth }) cannot be published as protected-resource metadata: ${reason}`,
+      fix: "defineAppMcp({ ..., oauth: { authorizationServers: ['https://www.example.com'] } }) — at least one absolute https (or http://localhost) issuer URL; resource and resourceDocumentation, when set, absolute URLs with no fragment",
+    });
+  }
+}