@ultimat3/mcp 22.3.6 → 22.5.0

package/CLAUDE.md

@@ -31,9 +31,18 @@ import. The CLI wires it.
 | `input-schema.ts` | Standard Schema → the `JsonSchema` subset `validate-args.ts` enforces |
 | `readonly-sql.ts` | layer 3 of `db.query` — the single-read parse — and `db.migrate`'s branch check |
 | `query-limits.ts` | layer 4 of `db.query` — the row, byte and timeout ceilings, and what truncation reports |
+| `meta-surface.ts` | `surface: 'meta'` catalog: `list_resources` / `describe_resource`, `groups:` boot checks; dispatch stays in `server.ts` |
+| `list-params.ts` | `listParams` whitelist → the schema `manage_resource` enforces (flat keys: `status_eq`) |
+| `meta-errors.ts` · `framework-error.ts` | meta boot refusals · a thrown value read and rendered (split from `server.ts`) |
 
 ## Invariants
 
+- **`manage_resource` is a second DOOR, never a second PATH** (`As of 2026-09-26`): locate (visibility,
+  else the absent answer) → the shared `resolve` (scope → args; a list whitelist's issues win) → `dispatch`,
+  audited under the inner tool. `tools/list` shows what `tools/call` answers PER CALLER: a meta caller
+  cannot call a grouped tool by name, a flat caller never sees the meta tools, and every not-found a
+  meta caller gets carries `META_UNKNOWN_FIX`. Default `'flat'` builds no `MetaSurface`.
+
 - `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a `defineAppMcp` file
   imports one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on
   every access, and a copy would freeze the provider at import time. `index.test.ts` asserts identity.

package/README.md

@@ -178,6 +178,49 @@ beside the action, because a scope is a capability of the CONNECTION's token —
 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`.
 
+### A constant surface: `surface: 'meta'`
+
+A large or sparsely used catalog blows an agent's context one tool per primitive. `surface: 'meta'`
+serves three tools instead, however many primitives sit behind them; tools named in no group
+(`docs`, `whoami`) stay flat beside them. The default is `'flat'` and changes nothing.
+
+```ts
+import { defineAppMcp } from '@ultimat3/mcp';
+
+defineAppMcp({
+  include: 'exposed',
+  surface: (caller) => (caller.role?.startsWith('staff') ? 'meta' : 'flat'), // or 'meta'
+  groups: {
+    payouts: {
+      description: 'Affiliate payout batches',
+      tools: ['previewPayoutBatch', 'listPayoutBatches'],
+    },
+  },
+});
+```
+
+| Tool | Answers |
+|---|---|
+| `list_resources` | `{ resources: [{ name, description, actions: [{ name, kind: 'query'\|'action', description, params, confirms?, scope? }] }] }` — `params` is a one-line hint (`batchId: string, note?: string`) |
+| `describe_resource` | `{ resources: string[] }` (batched) → each action's full `inputSchema` |
+| `manage_resource` | `{ resource, action, params }` → the flat tool's answer, byte for byte |
+
+`manage_resource` is the flat `tools/call` through another door: visibility (a hidden or misaddressed
+pair answers what an absent one does), then the shared resolver's scope and argument gates, then the
+tool's own policy, audited under the tool's name and metered in its bucket. A meta caller cannot call
+a grouped tool by name, and a flat caller never sees the meta tools. `confirms: true` on an
+`McpTool` marks a write a human finishes. Boot refuses `X_MCP_GROUP_UNKNOWN`,
+`X_MCP_GROUP_CONFLICT`, `X_MCP_SURFACE_INVALID` (meta without groups, groups nobody is served) and a
+meta tool name taken by an app tool (`X_MCP_TOOL_DUPLICATE`).
+
+**List params.** A list query declares its whitelist, `mcp: { expose: true, listParams: { filters:
+{ status: ['_eq', '_in'], createdAt: ['_gt', '_lt'] }, sort: ['createdAt'], fields: ['id', 'status'],
+maxLimit: 100 } }`. Keys are FLAT — `status_eq`, `createdAt_gt`, `sort: '-createdAt'`, `fields`,
+`cursor` (opaque keyset), `limit` — because a query's input travels as a query string; the query's
+own `input` declares them and implements them. `describe_resource` publishes the whitelist and
+`manage_resource` refuses anything outside it (`X_MCP_ARGS_INVALID`) before the query runs; a
+whitelisted key the input does not declare is `X_MCP_LIST_PARAMS_INVALID` at boot.
+
 ## Transports
 
 | Transport | Entry | Auth |
@@ -244,6 +287,9 @@ inside their own handler.
 | `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 |
 | `X_MCP_RESOURCE_DUPLICATE` | two resources claim one `ultimate://` URI — refused at registration, as a duplicate tool name is |
+| `X_MCP_GROUP_UNKNOWN` · `X_MCP_GROUP_CONFLICT` | `groups:` names a tool not projected · lists one tool twice |
+| `X_MCP_SURFACE_INVALID` | `surface` and `groups` disagree |
+| `X_MCP_LIST_PARAMS_INVALID` | `listParams` whitelists a key the tool's input does not declare |
 | `X_MCP_RATE_LIMITED` | the caller spent its per-minute allowance for this request's class. Its own code rather than `@ultimat3/http`'s `X_RATE_LIMITED` because the KNOB differs — `rateLimits` on the route, never `rateLimit.buckets` in `app.config.ts` |
 
 ### Error classes
@@ -256,8 +302,12 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `McpAppUnmountedError` | `X_MCP_APP_UNMOUNTED` | `src/errors.ts` |
 | `McpArgsInvalidError` | `X_MCP_ARGS_INVALID` | `src/errors.ts` |
 | `McpBodyTooLargeError` | `X_MCP_BODY_TOO_LARGE` | `src/errors.ts` |
+| `McpGroupConflictError` | `X_MCP_GROUP_CONFLICT` | `src/meta-errors.ts` |
+| `McpGroupUnknownError` | `X_MCP_GROUP_UNKNOWN` | `src/meta-errors.ts` |
+| `McpListParamsInvalidError` | `X_MCP_LIST_PARAMS_INVALID` | `src/meta-errors.ts` |
 | `McpNotBranchDbError` | `X_MCP_NOT_BRANCH_DB` | `src/errors.ts` |
 | `McpProtocolError` | `X_MCP_PROTOCOL` | `src/errors.ts` |
+| `McpSurfaceInvalidError` | `X_MCP_SURFACE_INVALID` | `src/meta-errors.ts` |
 | `McpQueryRejectedError` | `X_MCP_QUERY_REJECTED` | `src/errors.ts` |
 | `McpRateLimitedError` | `X_MCP_RATE_LIMITED` | `src/errors.ts` |
 | `McpResourceDuplicateError` | `X_MCP_RESOURCE_DUPLICATE` | `src/errors.ts` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "22.3.6",
+  "version": "22.5.0",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,13 +31,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.3.6",
-    "@ultimat3/core": "22.3.6",
-    "@ultimat3/entity": "22.3.6",
-    "@ultimat3/http": "22.3.6",
-    "@ultimat3/jobs": "22.3.6",
-    "@ultimat3/policy": "22.3.6",
-    "@ultimat3/query": "22.3.6",
-    "@ultimat3/schema": "22.3.6"
+    "@ultimat3/action": "22.5.0",
+    "@ultimat3/core": "22.5.0",
+    "@ultimat3/entity": "22.5.0",
+    "@ultimat3/http": "22.5.0",
+    "@ultimat3/jobs": "22.5.0",
+    "@ultimat3/policy": "22.5.0",
+    "@ultimat3/query": "22.5.0",
+    "@ultimat3/schema": "22.5.0"
   }
 }

package/src/app-tools.ts

@@ -15,6 +15,7 @@ import { appToolPrimitives } from './app-tool';
 import { McpToolDuplicateError } from './errors';
 import { exposedPrimitives } from './exposed';
 import { toolsFrom, toolsListed } from './from-action';
+import type { McpResourceGroups, McpSurfaceOption } from './meta-surface';
 import type { ListedPrimitive } from './projectable';
 import { asProjectable } from './projectable';
 import type { AnyMcpTool, McpVerbClass } from './registry';
@@ -74,6 +75,26 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
    * ```
    */
   readonly scopes?: McpScopes;
+  /**
+   * `'flat'` (the default — nothing changes for an app that omits it): one tool per primitive.
+   * `'meta'`: a CONSTANT `tools/list` — `list_resources`, `describe_resource`,
+   * `manage_resource` — with every tool named in `groups` behind them; the rest (`docs`,
+   * `whoami`) stay flat beside them. A function decides per population, from the caller alone:
+   *
+   * ```ts
+   * surface: (caller) => (caller.role?.startsWith('staff') ? 'meta' : 'flat'),
+   * ```
+   *
+   * Same policies, scopes, visibility and audit either way: `manage_resource` resolves to the
+   * tool and runs it on the path a flat `tools/call` takes.
+   */
+  readonly surface?: McpSurfaceOption;
+  /**
+   * The meta catalog: resource name → `{ description, tools }`, by TOOL NAME like `scopes`.
+   * Required with a surface that can be `'meta'`; refused with one that cannot. A name no tool
+   * answers to is `X_MCP_GROUP_UNKNOWN`, a tool in two groups `X_MCP_GROUP_CONFLICT`.
+   */
+  readonly groups?: McpResourceGroups;
   /** 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`. */
@@ -164,6 +185,8 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
     resources: input.resources ?? [],
     prompts: toPrompts(input.prompts ?? []),
     serverInfo: { name: input.name ?? 'ultimate-app', version: input.version ?? '0.0.0' },
+    ...(input.surface === undefined ? {} : { surface: input.surface }),
+    ...(input.groups === undefined ? {} : { groups: input.groups }),
   };
   const server = createMcpServer(config);
 

package/src/errors.ts

@@ -19,6 +19,10 @@ export const MCP_ERROR_CODES = [
   'X_MCP_RATE_LIMITED',
   'X_MCP_APP_UNMOUNTED',
   'X_MCP_BODY_TOO_LARGE',
+  'X_MCP_GROUP_UNKNOWN',
+  'X_MCP_GROUP_CONFLICT',
+  'X_MCP_SURFACE_INVALID',
+  'X_MCP_LIST_PARAMS_INVALID',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -39,6 +43,10 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_RATE_LIMITED: "the caller has spent its allowance for this request's class",
   X_MCP_APP_UNMOUNTED: "the app's MCP endpoint is exposed in config and nothing can be mounted",
   X_MCP_BODY_TOO_LARGE: 'one MCP message is larger than the transport holds',
+  X_MCP_GROUP_UNKNOWN: 'defineAppMcp groups a tool this server does not project',
+  X_MCP_GROUP_CONFLICT: 'two resource groups claim one MCP tool',
+  X_MCP_SURFACE_INVALID: 'the MCP meta surface is declared inconsistently',
+  X_MCP_LIST_PARAMS_INVALID: "a tool's listParams names a key its own input does not accept",
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is

package/src/framework-error.ts

@@ -0,0 +1,58 @@
+// A value a tool THREW, read as a framework error (code, title, cause, fix) or rejected as a bug —
+// and its rendering, byte-identical to `UltimateError.format()`. Split from `server.ts`, whose two
+// dispatch paths (a flat `tools/call` and `manage_resource`) and resource reads all share it.
+
+import { FRAMEWORK_CODE, singleLine, stringField } from '@ultimat3/core';
+
+export interface FrameworkError {
+  readonly code: string;
+  /** `''` for a foreign thrown object that carries no title. See `renderFrameworkError`. */
+  readonly title: string;
+  readonly cause: string;
+  readonly fix: string;
+}
+
+/**
+ * Read a thrown framework error, or `undefined` when it is not one (a genuine bug, which
+ * becomes `-32603` with no internals leaked). Structural rather than `instanceof`: the
+ * transport must stay independent of which package threw.
+ */
+export function asFrameworkError(error: unknown): FrameworkError | undefined {
+  // `stringField` from `@ultimat3/core`, never `typeof e.code === 'string'`: the value is whatever
+  // an app's handler, its driver or its SDK threw, so each read is a getter call or a `Proxy`
+  // trap. This runs inside the catch block that owes the caller an answer, and a probe that
+  // raises here leaves the JSON-RPC request with no response at all — not even the `-32603` the
+  // header promises for a genuine bug.
+  const code = stringField(error, 'code');
+  // `FRAMEWORK_CODE`, never `startsWith('X_')`: the substituted `fix:` below interpolates this
+  // value into a COMMAND an agent is told to run, and `X_$(id)` passes a prefix test. A code is
+  // `X_SCREAMING_SNAKE` and nothing else, so a value that is not one is not a framework error —
+  // it takes the `-32603` branch, which leaks nothing of the throw.
+  if (code === undefined || !FRAMEWORK_CODE.test(code)) return undefined;
+  return {
+    code,
+    title: stringField(error, 'title') ?? '',
+    cause: stringField(error, 'cause') ?? 'unknown',
+    // A substituted fix is still a fix an agent will act on, so it has to be runnable. `see docs`
+    // named no docs and no command; `code` is already narrowed to an `X_` string by the guard
+    // above, so the substitute is the one command that explains exactly this code.
+    fix: stringField(error, 'fix') ?? `x errors explain ${code}`,
+  };
+}
+
+/**
+ * The agent-readable form, BYTE-IDENTICAL to `UltimateError.format()` — one denial reads the
+ * same over MCP as it does in the terminal, so an agent that learned the shape from `x` does
+ * not have to learn a second one here. Dropping the title would be a second rendering of the
+ * same contract, and the two would drift.
+ *
+ * The bare-`code` head is the fallback for a foreign thrown object that carries `code`/`cause`
+ * but no title; a real `UltimateError` always has one.
+ */
+export function renderFrameworkError(error: FrameworkError): string {
+  const head =
+    error.title === ''
+      ? singleLine(error.code)
+      : `${singleLine(error.code)}: ${singleLine(error.title)}`;
+  return `${head}\n  cause: ${singleLine(error.cause)}\n  fix:   ${singleLine(error.fix)}`;
+}

package/src/from-action.ts

@@ -27,6 +27,7 @@
 import type { Actor } from '@ultimat3/core';
 import { isMcpExposed } from '@ultimat3/core';
 import { McpToolUndeclaredError } from './errors';
+import type { McpListParams } from './list-params';
 import type { AnyMcpTool, McpCaller, McpRole, McpToolResult, ToolArgs } from './registry';
 import { jsonResult } from './registry';
 import type { JsonSchema } from './wire';
@@ -49,6 +50,8 @@ export interface McpExposure {
   readonly visibleTo?: readonly McpRole[];
   /** Override the projected tool name. Defaults to the primitive's own name. */
   readonly name?: string;
+  /** A list query's whitelist, carried to the tool for the meta surface. See `McpListParams`. */
+  readonly listParams?: McpListParams;
 }
 
 /**
@@ -88,6 +91,7 @@ export function toolFromAction(primitive: ProjectablePrimitive): AnyMcpTool {
     primitive.mcp?.description ?? primitive.description ?? `Run the "${primitive.name}" action.`;
   const mutates = primitive.mutates ?? true;
   const visibleTo = primitive.mcp?.visibleTo;
+  const listParams = primitive.mcp?.listParams;
 
   return {
     name,
@@ -95,6 +99,7 @@ export function toolFromAction(primitive: ProjectablePrimitive): AnyMcpTool {
     inputSchema: primitive.inputJsonSchema ?? NO_ARGS,
     destructive: mutates,
     ...(visibleTo !== undefined ? { visibleTo } : {}),
+    ...(listParams !== undefined ? { listParams } : {}),
     // No `scope` from here: see the header. `defineAppMcp`'s `scopes:` map may add one.
     async handle(args: ToolArgs, caller: McpCaller): Promise<McpToolResult> {
       // ONE authz system, TWO surfaces. This `run` IS `invoke`; the HTTP route reaches the

package/src/index.ts

@@ -86,6 +86,31 @@ export {
   toolsListed,
 } from './from-action';
 export { toWireSchema } from './input-schema';
+export type { ListFilterOp, McpListParams } from './list-params';
+export { DEFAULT_LIST_MAX_LIMIT, listParamsSchema } from './list-params';
+export {
+  McpGroupConflictError,
+  McpGroupUnknownError,
+  McpListParamsInvalidError,
+  McpSurfaceInvalidError,
+  META_UNKNOWN_FIX,
+} from './meta-errors';
+export type {
+  DescribedAction,
+  McpResourceGroup,
+  McpResourceGroups,
+  McpSurface,
+  McpSurfaceOption,
+  MetaAction,
+  MetaResource,
+} from './meta-surface';
+export {
+  DESCRIBE_RESOURCE,
+  LIST_RESOURCES,
+  MANAGE_RESOURCE,
+  META_TOOL_NAMES,
+  oneLineParams,
+} from './meta-surface';
 export type { ListedPrimitive } from './projectable';
 export { asProjectable } from './projectable';
 export type { QueryLimits, QueryResult, QueryRows } from './query-limits';

package/src/list-params.ts

@@ -0,0 +1,120 @@
+// `listParams` — composition pushed into params, not tools: one list query answers filters,
+// `sort`, `fields` and a keyset `cursor` + `limit` over a WHITELIST it declares, instead of an app
+// shipping `listRecentX`, `listPaidX`, `xByOrg`. This file turns the declaration into the schema
+// `describe_resource` publishes and `manage_resource` enforces before the query's own parse.
+//
+// FLAT keys (`status_eq`, not `filters: { status: { eq } }`): a query's input is projected to a
+// query string (`@ultimat3/query` refuses a nested object in `input-shape.ts`), so the one shape
+// every surface can carry is the one this whitelist publishes.
+
+import { finiteCount } from '@ultimat3/core';
+import { McpListParamsInvalidError } from './meta-errors';
+import type { JsonSchema } from './wire';
+
+/** The five comparison operators. A filter key is `<field><op>`: `status_eq`, `amount_gt`. */
+export type ListFilterOp = '_eq' | '_in' | '_gt' | '_lt' | '_cont';
+
+/** The largest page `limit` may ask for when a query declares no `maxLimit`. */
+export const DEFAULT_LIST_MAX_LIMIT = 100;
+
+/**
+ * What a list query composes over. Every member is a whitelist: a filter field with the operators
+ * it takes, the sortable fields, the fields a sparse response may pick.
+ *
+ * The query's own `input` declares the same keys — `status_eq`, `sort`, `fields`, `cursor`,
+ * `limit` — and implements them; the dispatcher refuses anything outside the whitelist before the
+ * query runs, and a whitelisted key the input does not declare is refused at BOOT
+ * (`X_MCP_LIST_PARAMS_INVALID`), because the query would silently never read it. `cursor` is
+ * opaque and keyset, never an offset.
+ */
+export interface McpListParams {
+  readonly filters?: Readonly<Record<string, readonly ListFilterOp[]>>;
+  readonly sort?: readonly string[];
+  readonly fields?: readonly string[];
+  /** Ceiling for `limit`. Defaults to `DEFAULT_LIST_MAX_LIMIT`. */
+  readonly maxLimit?: number;
+}
+
+const SCALAR: JsonSchema = {
+  anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'boolean' }],
+};
+
+const ORDERED: JsonSchema = { anyOf: [{ type: 'string' }, { type: 'number' }] };
+
+function operandSchema(op: ListFilterOp): JsonSchema {
+  switch (op) {
+    case '_in':
+      return { type: 'array', items: SCALAR };
+    case '_cont':
+      return { type: 'string', minLength: 1 };
+    case '_gt':
+    case '_lt':
+      return ORDERED;
+    case '_eq':
+      return SCALAR;
+  }
+}
+
+/** The whitelisted keys and their wire schemas, in declaration order. */
+export function listParamsProperties(spec: McpListParams): readonly [string, JsonSchema][] {
+  const out: [string, JsonSchema][] = [];
+  for (const [field, ops] of Object.entries(spec.filters ?? {})) {
+    for (const op of new Set(ops)) out.push([`${field}${op}`, operandSchema(op)]);
+  }
+  if (spec.sort !== undefined && spec.sort.length > 0) {
+    out.push([
+      'sort',
+      {
+        type: 'string',
+        description: 'a field, ascending; prefix "-" for descending',
+        enum: spec.sort.flatMap((field) => [field, `-${field}`]),
+      },
+    ]);
+  }
+  if (spec.fields !== undefined && spec.fields.length > 0) {
+    out.push(['fields', { type: 'array', items: { type: 'string', enum: spec.fields } }]);
+  }
+  out.push([
+    'cursor',
+    { type: 'string', maxLength: 1024, description: 'opaque keyset cursor from the last page' },
+  ]);
+  // Refused rather than published: `maximum: NaN` is a ceiling `validateArgs` never trips.
+  const maxLimit = finiteCount(
+    'listParams',
+    'maxLimit',
+    spec.maxLimit ?? DEFAULT_LIST_MAX_LIMIT,
+    1,
+  );
+  out.push(['limit', { type: 'integer', minimum: 1, maximum: maxLimit }]);
+  return out;
+}
+
+/**
+ * The schema `manage_resource` validates a list call against: the tool's own input with every
+ * list key NARROWED to the whitelist, and nothing else admitted. `Object.fromEntries` (a define,
+ * never `[k] =`) because a field name is the app's string and `__proto__` must land as a key.
+ */
+export function listParamsSchema(spec: McpListParams, base: JsonSchema): JsonSchema {
+  const properties = Object.fromEntries([
+    ...Object.entries(base.properties ?? {}),
+    ...listParamsProperties(spec),
+  ]);
+  return {
+    type: 'object',
+    properties,
+    ...(base.required === undefined ? {} : { required: base.required }),
+    additionalProperties: false,
+  };
+}
+
+/**
+ * Boot-time: every whitelisted key must be one the tool's input declares. A key the input does not
+ * declare is either refused by the query's parse or stripped by it — the second is a filter an
+ * agent was promised and the query never applied, which is worse than no filter at all.
+ */
+export function assertListParams(name: string, spec: McpListParams, base: JsonSchema): void {
+  const declared = base.properties ?? {};
+  for (const [key] of listParamsProperties(spec)) {
+    if (!Object.hasOwn(declared, key)) throw new McpListParamsInvalidError({ name, key });
+  }
+}

package/src/meta-call.ts

@@ -0,0 +1,83 @@
+// A META caller's `tools/call`: the three meta tools, and the refusal of a grouped tool called by
+// its flat name. Split from `server.ts` for the size ceiling only — it holds no gate of its own:
+// every call it runs goes back through the server's `resolve` → `dispatch`, the flat path.
+
+import { auditToolCall } from './audit';
+import { META_UNKNOWN_FIX } from './meta-errors';
+import type { MetaSurface } from './meta-surface';
+import { DESCRIBE_RESOURCE, LIST_RESOURCES, META_TOOL_ENTRIES, schemaOf } from './meta-surface';
+import type { McpCaller, ToolRegistry, ToolResolution } from './registry';
+import { jsonResult } from './registry';
+import { validateArgs } from './validate-args';
+import type { JsonRpcId, JsonRpcResponse } from './wire';
+import { errorResponse, METHOD_NOT_FOUND, resultResponse } from './wire';
+
+/** The server's own two steps, handed in so this file cannot grow a second path. */
+export interface MetaHost {
+  readonly tools: ToolRegistry;
+  dispatch(
+    id: JsonRpcId,
+    name: string,
+    resolved: ToolResolution,
+    caller: McpCaller,
+  ): Promise<JsonRpcResponse>;
+  notFound(id: JsonRpcId, name: string, caller: McpCaller, fix: string): JsonRpcResponse;
+}
+
+export interface MetaRequest {
+  readonly id: JsonRpcId;
+  readonly name: string;
+  readonly rawArgs: unknown;
+  readonly caller: McpCaller;
+}
+
+/** `undefined` hands an ungrouped tool (`docs`, `whoami`) to the flat path. */
+export async function metaCall(
+  host: MetaHost,
+  meta: MetaSurface,
+  request: MetaRequest,
+): Promise<JsonRpcResponse | undefined> {
+  const { id, name, caller } = request;
+  const entry = META_TOOL_ENTRIES.find((tool) => tool.name === name);
+  if (entry === undefined) {
+    return meta.isGrouped(name) ? host.notFound(id, name, caller, META_UNKNOWN_FIX) : undefined;
+  }
+  const args = validateArgs(entry.inputSchema, request.rawArgs ?? {});
+  if (!args.ok) {
+    return host.dispatch(id, name, { kind: 'invalid-args', name, issues: args.issues }, caller);
+  }
+  if (name === LIST_RESOURCES) {
+    auditToolCall({ tool: name, outcome: 'ok', caller });
+    return resultResponse(id, jsonResult({ resources: meta.listResources(caller) }));
+  }
+  if (name === DESCRIBE_RESOURCE) {
+    const described = meta.describe(args.value['resources'] as readonly string[], caller);
+    if (!described.ok) {
+      // Absent and hidden are one answer, with no `data`, exactly as for a tool.
+      auditToolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
+      return errorResponse(
+        id,
+        METHOD_NOT_FOUND,
+        `resource not found: ${described.name} — ${META_UNKNOWN_FIX}`,
+      );
+    }
+    auditToolCall({ tool: name, outcome: 'ok', caller });
+    return resultResponse(id, jsonResult({ resources: described.resources }));
+  }
+  // `manage_resource`: address → the SAME resolve and dispatch a flat call takes, audited under
+  // the tool it reached. Visibility first (a hidden pair is an absent pair), then the shared
+  // resolver's scope → args. A list whitelist's issues REPLACE the tool schema's: both are pure
+  // checks with nothing run between them, so which is evaluated first is invisible — the answer
+  // names the whitelist, which is the contract `describe_resource` published.
+  const resource = args.value['resource'] as string;
+  const action = args.value['action'] as string;
+  const tool = meta.locate(resource, action, caller);
+  if (tool === undefined) return host.notFound(id, action, caller, META_UNKNOWN_FIX);
+  const input = args.value['params'] ?? {};
+  let resolved = host.tools.resolve(action, input, caller);
+  if (resolved.kind !== 'scope-denied' && resolved.kind !== 'not-found') {
+    const listed = validateArgs(schemaOf(tool), input);
+    if (!listed.ok) resolved = { kind: 'invalid-args', name: action, issues: listed.issues };
+  }
+  return host.dispatch(id, action, resolved, caller);
+}

package/src/meta-errors.ts

@@ -0,0 +1,68 @@
+// The boot-time refusals of the META surface (`surface: 'meta'` + `groups:` in `defineAppMcp`).
+// Codes and titles are registered in `errors.ts` with the rest of the package's; these classes
+// sit apart only so that file stays under the size ceiling.
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * The one instruction safe on both branches of outcome 1 for a META caller — the twin of
+ * `TOOL_UNKNOWN_FIX`. Every not-found a meta caller receives carries THIS sentence, grouped name or
+ * flat, absent or hidden: a second wording for one branch would be the oracle outcome 1 removes.
+ */
+export const META_UNKNOWN_FIX =
+  'call tools/list and list_resources to read the catalog this caller may use';
+
+/** `groups:` names a tool no projected or hand-written tool answers to. */
+export class McpGroupUnknownError extends UltimateError {
+  readonly projected: readonly string[];
+
+  constructor(input: { group: string; name: string; projected: readonly string[] }) {
+    const projected = input.projected.length > 0 ? input.projected.join(', ') : 'nothing';
+    super({
+      code: 'X_MCP_GROUP_UNKNOWN',
+      cause: `groups["${input.group}"] names "${input.name}", which this server does not project (projected: ${projected})`,
+      fix: `in defineAppMcp, spell it as one of the projected names above — or drop "${input.name}" from groups["${input.group}"].tools`,
+    });
+    this.projected = input.projected;
+  }
+}
+
+/**
+ * One tool claimed by two groups. `manage_resource` addresses a tool as `{ resource, action }`, so
+ * a tool in two resources has two addresses — and which one `list_resources` shows would be
+ * decided by object key order.
+ */
+export class McpGroupConflictError extends UltimateError {
+  readonly groups: readonly [string, string];
+
+  constructor(input: { name: string; groups: readonly [string, string] }) {
+    super({
+      code: 'X_MCP_GROUP_CONFLICT',
+      cause: `tool "${input.name}" is listed in two groups ("${input.groups[0]}" and "${input.groups[1]}"); a tool belongs to one resource`,
+      fix: `in defineAppMcp, keep "${input.name}" in the one group an agent should find it under, and remove the other entry`,
+    });
+    this.groups = input.groups;
+  }
+}
+
+/** A `listParams` key the tool's own input does not declare — a promise the query never keeps. */
+export class McpListParamsInvalidError extends UltimateError {
+  constructor(input: { name: string; key: string }) {
+    super({
+      code: 'X_MCP_LIST_PARAMS_INVALID',
+      cause: `tool "${input.name}" whitelists "${input.key}" in listParams, and its input schema does not declare "${input.key}" — the query would never read it`,
+      fix: `add "${input.key}" to the input of "${input.name}" (the query implements it), or drop it from mcp.listParams`,
+    });
+  }
+}
+
+/** `surface` and `groups` disagree: a meta surface with nothing behind it, or groups nobody sees. */
+export class McpSurfaceInvalidError extends UltimateError {
+  constructor(input: { cause: string }) {
+    super({
+      code: 'X_MCP_SURFACE_INVALID',
+      cause: input.cause,
+      fix: "in defineAppMcp, declare groups: { <resource>: { description, tools: [...] } } together with surface: 'meta' (or surface: (caller) => 'meta' | 'flat'), or drop both",
+    });
+  }
+}

package/src/meta-surface.ts

@@ -0,0 +1,298 @@
+// The META surface: three tools — `list_resources`, `describe_resource`, `manage_resource` — in
+// place of one tool per primitive, so `tools/list` stays the same size however many primitives an
+// app grows. The catalog, the lazy schemas and the address book live here; the DISPATCH stays in
+// `server.ts`, on the same resolve → run → audit path a flat `tools/call` takes, so the three
+// security outcomes, the policy inside `invoke` and the synchronous audit line are one code path
+// reached through two doors — never a second implementation.
+//
+// A grouped tool is reachable ONLY through `manage_resource` for a meta caller, and a flat caller
+// never sees the meta tools: what `tools/list` shows is what `tools/call` answers, per caller.
+
+import { McpToolDuplicateError } from './errors';
+import { assertListParams, listParamsSchema } from './list-params';
+import { McpGroupConflictError, McpGroupUnknownError, McpSurfaceInvalidError } from './meta-errors';
+import type { AnyMcpTool, McpCaller, ToolListEntry } from './registry';
+import { visibleToCaller } from './registry';
+import type { JsonSchema } from './wire';
+import { NO_ARGS } from './wire';
+
+export type McpSurface = 'flat' | 'meta';
+
+/**
+ * Which surface a caller is served. A function decides per POPULATION — staff meta, customers flat
+ * — from the caller alone, never the arguments. A function that throws or answers anything but the
+ * literal `'meta'` serves `'flat'`: the two surfaces reach the same tools under the same gates, so
+ * the fallback changes the shape of the catalog, never what the caller may do.
+ */
+export type McpSurfaceOption = McpSurface | ((caller: McpCaller) => McpSurface);
+
+/** One resource of the meta catalog: a slice or feature, and the tools it answers, by name. */
+export interface McpResourceGroup {
+  /** What the resource is, for an agent choosing where to look. */
+  readonly description: string;
+  /** Tool names — a projected action/query or a hand-written tool. One group per tool. */
+  readonly tools: readonly string[];
+}
+
+/** Resource name → its group. The key is what `manage_resource({ resource })` names. */
+export type McpResourceGroups = Readonly<Record<string, McpResourceGroup>>;
+
+export const LIST_RESOURCES = 'list_resources';
+export const DESCRIBE_RESOURCE = 'describe_resource';
+export const MANAGE_RESOURCE = 'manage_resource';
+export const META_TOOL_NAMES: readonly string[] = [
+  LIST_RESOURCES,
+  DESCRIBE_RESOURCE,
+  MANAGE_RESOURCE,
+];
+
+/** The three constant entries, as `tools/list` publishes them. */
+export const META_TOOL_ENTRIES: readonly ToolListEntry[] = [
+  {
+    name: DESCRIBE_RESOURCE,
+    description:
+      "Full input schemas for the actions of one or more resources (batched). Call it before manage_resource when list_resources' one-line params are not enough. Read-only.",
+    inputSchema: {
+      type: 'object',
+      properties: { resources: { type: 'array', items: { type: 'string' } } },
+      required: ['resources'],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: LIST_RESOURCES,
+    description:
+      'The catalog: every resource this caller may use, each with its actions (query or action), a one-line parameter hint and whether a write waits for a human to confirm. Read-only.',
+    inputSchema: NO_ARGS,
+  },
+  {
+    name: MANAGE_RESOURCE,
+    description:
+      'Run one action of one resource: { resource, action, params }. Same policies, scopes and audit as calling the action directly. Writes may change state or send mail — read the action first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        resource: { type: 'string' },
+        action: { type: 'string' },
+        params: { type: 'object' },
+      },
+      required: ['resource', 'action'],
+      additionalProperties: false,
+    },
+  },
+];
+
+export interface MetaAction {
+  readonly name: string;
+  readonly kind: 'query' | 'action';
+  readonly description: string;
+  /** One line an agent can compose a call from: `radicado: string, note?: string`. */
+  readonly params: string;
+  readonly confirms?: true;
+  readonly scope?: string;
+}
+
+export interface MetaResource {
+  readonly name: string;
+  readonly description: string;
+  readonly actions: readonly MetaAction[];
+}
+
+export interface DescribedAction extends Omit<MetaAction, 'params'> {
+  readonly inputSchema: JsonSchema;
+}
+
+export class MetaSurface {
+  readonly #option: McpSurfaceOption;
+  readonly #groups: ReadonlyMap<string, McpResourceGroup>;
+  /** Tool name → the resource that answers it. */
+  readonly #home: ReadonlyMap<string, string>;
+  readonly #tools: ReadonlyMap<string, AnyMcpTool>;
+
+  private constructor(
+    option: McpSurfaceOption,
+    groups: ReadonlyMap<string, McpResourceGroup>,
+    home: ReadonlyMap<string, string>,
+    tools: ReadonlyMap<string, AnyMcpTool>,
+  ) {
+    this.#option = option;
+    this.#groups = groups;
+    this.#home = home;
+    this.#tools = tools;
+  }
+
+  /**
+   * Validate at BOOT and build, or `undefined` for a flat-only server. Every refusal is one an
+   * author would otherwise meet as a tool silently missing from, or doubly present in, a catalog.
+   */
+  static build(input: {
+    readonly surface?: McpSurfaceOption | undefined;
+    readonly groups?: McpResourceGroups | undefined;
+    readonly tools: readonly AnyMcpTool[];
+  }): MetaSurface | undefined {
+    for (const tool of input.tools) {
+      if (tool.listParams !== undefined) {
+        assertListParams(tool.name, tool.listParams, tool.inputSchema);
+      }
+    }
+    const option = input.surface ?? 'flat';
+    const entries = Object.entries(input.groups ?? {});
+    if (option === 'flat') {
+      if (entries.length === 0) return undefined;
+      throw new McpSurfaceInvalidError({
+        cause: `groups: declares ${entries.length} resource(s), and surface is 'flat' for every caller, so no caller would ever see them`,
+      });
+    }
+    if (option !== 'meta' && typeof option !== 'function') {
+      throw new McpSurfaceInvalidError({ cause: `surface is ${JSON.stringify(option)}` });
+    }
+    if (entries.length === 0) {
+      throw new McpSurfaceInvalidError({
+        cause:
+          "surface can be 'meta', and groups: declares no resource, so list_resources would always answer empty",
+      });
+    }
+    const tools = new Map(input.tools.map((tool) => [tool.name, tool]));
+    for (const name of META_TOOL_NAMES) {
+      if (tools.has(name)) throw new McpToolDuplicateError({ name });
+    }
+    const home = new Map<string, string>();
+    for (const [group, declared] of entries) {
+      for (const name of declared.tools) {
+        if (!tools.has(name)) {
+          throw new McpGroupUnknownError({ group, name, projected: [...tools.keys()].sort() });
+        }
+        const claimed = home.get(name);
+        if (claimed !== undefined) {
+          throw new McpGroupConflictError({ name, groups: [claimed, group] });
+        }
+        home.set(name, group);
+      }
+    }
+    return new MetaSurface(option, new Map(entries), home, tools);
+  }
+
+  /** The surface this caller is served. Fail-closed to `'flat'` — see `McpSurfaceOption`. */
+  surfaceFor(caller: McpCaller): McpSurface {
+    const option = this.#option;
+    if (typeof option !== 'function') return option;
+    try {
+      return option(caller) === 'meta' ? 'meta' : 'flat';
+    } catch {
+      return 'flat';
+    }
+  }
+
+  /** True when a META caller must reach this tool through `manage_resource`, not by its name. */
+  isGrouped(name: string): boolean {
+    return this.#home.has(name);
+  }
+
+  /** `list_resources`: only what this caller may see; a resource with nothing visible is absent. */
+  listResources(caller: McpCaller): readonly MetaResource[] {
+    const out: MetaResource[] = [];
+    for (const [name, group] of sorted(this.#groups)) {
+      const actions = this.#visibleActions(group, caller).map(
+        (tool): MetaAction => ({ ...headOf(tool), params: oneLineParams(schemaOf(tool)) }),
+      );
+      if (actions.length > 0) out.push({ name, description: group.description, actions });
+    }
+    return out;
+  }
+
+  /**
+   * `describe_resource`: the full schemas, or the FIRST name this caller cannot see. Absent and
+   * hidden are one answer, exactly as they are for a tool.
+   */
+  describe(
+    names: readonly string[],
+    caller: McpCaller,
+  ):
+    | { readonly ok: true; readonly resources: readonly unknown[] }
+    | { readonly ok: false; readonly name: string } {
+    const resources: unknown[] = [];
+    for (const name of new Set(names)) {
+      // A `Map`, so a name like `__proto__` or `constructor` is just a missing key.
+      const group = this.#groups.get(name);
+      const actions = group === undefined ? [] : this.#visibleActions(group, caller);
+      if (group === undefined || actions.length === 0) return { ok: false, name };
+      resources.push({
+        name,
+        description: group.description,
+        actions: actions.map(
+          (tool): DescribedAction => ({ ...headOf(tool), inputSchema: schemaOf(tool) }),
+        ),
+      });
+    }
+    return { ok: true, resources };
+  }
+
+  /**
+   * The tool `{ resource, action }` addresses, or `undefined` when that pair is not a visible
+   * member — the caller then gets the not-found an absent tool gets. Visibility is checked HERE so
+   * a hidden tool is never reached; scope, arguments and policy stay with the shared resolver.
+   */
+  locate(resource: string, action: string, caller: McpCaller): AnyMcpTool | undefined {
+    if (this.#home.get(action) !== resource) return undefined;
+    const tool = this.#tools.get(action);
+    if (tool === undefined || !visibleToCaller(tool, caller)) return undefined;
+    return tool;
+  }
+
+  #visibleActions(group: McpResourceGroup, caller: McpCaller): readonly AnyMcpTool[] {
+    return [...group.tools]
+      .sort()
+      .map((name) => this.#tools.get(name))
+      .filter((tool): tool is AnyMcpTool => tool !== undefined && visibleToCaller(tool, caller));
+  }
+}
+
+/** The schema a meta call is validated against: the list whitelist when one is declared. */
+export function schemaOf(tool: AnyMcpTool): JsonSchema {
+  return tool.listParams === undefined
+    ? tool.inputSchema
+    : listParamsSchema(tool.listParams, tool.inputSchema);
+}
+
+function headOf(tool: AnyMcpTool): Omit<MetaAction, 'params'> {
+  return {
+    name: tool.name,
+    kind: tool.destructive === false ? 'query' : 'action',
+    description: tool.description,
+    ...(tool.confirms === true ? { confirms: true } : {}),
+    ...(tool.scope === undefined ? {} : { scope: tool.scope }),
+  };
+}
+
+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;
+
+/**
+ * `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.
+ */
+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)`;
+}
+
+function typeHint(schema: JsonSchema): string {
+  if (schema.enum !== undefined) return schema.enum.map((v) => JSON.stringify(v)).join('|');
+  if (schema.const !== undefined) return JSON.stringify(schema.const);
+  if (schema.anyOf !== undefined) return schema.anyOf.map(typeHint).join('|');
+  if (schema.type === 'array') {
+    if (schema.items === undefined) return 'array';
+    const item = typeHint(schema.items);
+    return item.includes('|') ? `(${item})[]` : `${item}[]`;
+  }
+  return schema.type ?? 'any';
+}

package/src/projectable.ts

@@ -11,6 +11,7 @@ import { isQuery, queryName, sourceFor } from '@ultimat3/query';
 import { asCallerContext } from './caller-context';
 import type { McpExposure, ProjectablePrimitive } from './from-action';
 import { toWireSchema } from './input-schema';
+import type { McpListParams } from './list-params';
 
 /**
  * What `defineAppMcp`'s `actions:`/`queries:` accept.
@@ -90,6 +91,7 @@ function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined
     expose: isMcpExposed(declared),
     ...(declared.description === undefined ? {} : { description: declared.description }),
     ...(declared.visibleTo === undefined ? {} : { visibleTo: declared.visibleTo }),
+    ...(declared.listParams === undefined ? {} : { listParams: declared.listParams }),
   };
 }
 
@@ -98,4 +100,6 @@ interface DeclaredMcp {
   readonly expose: boolean;
   readonly description?: string;
   readonly visibleTo?: readonly string[];
+  /** `QueryMcp` only; an action has no list to compose. */
+  readonly listParams?: McpListParams;
 }

package/src/registry.ts

@@ -20,6 +20,7 @@
 
 import type { Actor } from '@ultimat3/core';
 import { McpToolDuplicateError } from './errors';
+import type { McpListParams } from './list-params';
 import type { ArgIssue } from './validate-args';
 import { validateArgs } from './validate-args';
 import type { JsonSchema } from './wire';
@@ -95,6 +96,17 @@ export interface McpTool<A extends ToolArgs = ToolArgs> {
    * cheap read chatter by omission.
    */
   readonly destructive?: boolean;
+  /**
+   * A list query's whitelist of `filters` / `sort` / `fields` / `cursor` + `limit`. Published by
+   * `describe_resource` and enforced by `manage_resource` alongside the tool's own input schema;
+   * the flat surface ignores it (the tool's `inputSchema` is its contract there).
+   */
+  readonly listParams?: McpListParams;
+  /**
+   * A catalog hint: this write answers "awaiting confirmation" and a human finishes it. Shown by
+   * `list_resources` so an agent plans for the hand-off; it changes nothing about the call.
+   */
+  readonly confirms?: boolean;
   // Method syntax (not a property) so a tool declared with narrower args stays assignable.
   handle(args: A, caller: McpCaller): Promise<McpToolResult>;
 }

package/src/server.ts

@@ -3,16 +3,27 @@
 // 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 { FRAMEWORK_CODE, singleLine, stringField } from '@ultimat3/core';
 import { formatIssues } from '@ultimat3/schema';
 import { auditResourceRead, auditToolCall, outcomeForCode, outcomeForResult } from './audit';
 import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './errors';
+import { asFrameworkError, renderFrameworkError } from './framework-error';
+import { metaCall } from './meta-call';
+import { META_UNKNOWN_FIX } from './meta-errors';
+import type { McpResourceGroups, McpSurfaceOption } from './meta-surface';
+import { MANAGE_RESOURCE, META_TOOL_ENTRIES, META_TOOL_NAMES, MetaSurface } from './meta-surface';
 import { promptListEntry, promptsGet } from './prompts-get';
-import type { AnyMcpTool, McpCaller, McpToolResult, McpVerbClass, ToolListEntry } from './registry';
+import type {
+  AnyMcpTool,
+  McpCaller,
+  McpToolResult,
+  McpVerbClass,
+  ToolListEntry,
+  ToolResolution,
+} from './registry';
 import { ToolRegistry } from './registry';
 import type { McpPrompt, McpResource } from './resources';
 import { ResourceRegistry } from './resources';
-import type { JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
+import type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
 import {
   defaultServerInfo,
   errorResponse,
@@ -49,6 +60,10 @@ export interface CreateMcpServerInput {
   readonly resources?: readonly McpResource[];
   readonly prompts?: readonly McpPrompt[];
   readonly serverInfo?: ServerInfo;
+  /** `'flat'` (the default): one tool per primitive. See `McpSurfaceOption`. */
+  readonly surface?: McpSurfaceOption | undefined;
+  /** The meta catalog's resources. Required with a surface that can be `'meta'`. */
+  readonly groups?: McpResourceGroups | undefined;
 }
 
 /** The set of JSON-RPC methods this server answers. Kept in sync with `classify`. */
@@ -66,11 +81,17 @@ const METHODS = [
 export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
   const tools = new ToolRegistry().registerAll(input.tools ?? []);
   const resources = new ResourceRegistry().registerAll(input.resources ?? []);
+  const meta = MetaSurface.build({
+    surface: input.surface,
+    groups: input.groups,
+    tools: input.tools ?? [],
+  });
   return new McpServer(
     tools,
     resources,
     input.prompts ?? [],
     input.serverInfo ?? defaultServerInfo(),
+    meta,
   );
 }
 
@@ -79,17 +100,21 @@ export class McpServer {
   readonly resources: ResourceRegistry;
   private readonly prompts: readonly McpPrompt[];
   private readonly serverInfo: ServerInfo;
+  /** `undefined` for a flat-only server — every existing app, byte for byte. */
+  private readonly meta: MetaSurface | undefined;
 
   constructor(
     tools: ToolRegistry,
     resources: ResourceRegistry,
     prompts: readonly McpPrompt[],
     serverInfo: ServerInfo,
+    meta?: MetaSurface,
   ) {
     this.tools = tools;
     this.resources = resources;
     this.prompts = prompts;
     this.serverInfo = serverInfo;
+    this.meta = meta;
   }
 
   async handle(
@@ -160,7 +185,19 @@ export class McpServer {
 
   /** Role-filtered catalog. Exposed so a transport can answer a cheap capability probe. */
   list(caller: McpCaller): readonly ToolListEntry[] {
-    return this.tools.list(caller);
+    const flat = this.tools.list(caller);
+    const meta = this.metaFor(caller);
+    if (meta === undefined) return flat;
+    // Constant: the three meta tools plus whatever the app left ungrouped (`docs`, `whoami`).
+    return [...flat.filter((tool) => !meta.isGrouped(tool.name)), ...META_TOOL_ENTRIES].sort(
+      (a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0),
+    );
+  }
+
+  /** The meta surface when THIS caller is served it, else `undefined`. */
+  private metaFor(caller: McpCaller): MetaSurface | undefined {
+    const meta = this.meta;
+    return meta !== undefined && meta.surfaceFor(caller) === 'meta' ? meta : undefined;
   }
 
   /**
@@ -174,10 +211,18 @@ export class McpServer {
    */
   classify(body: unknown): McpVerbClass {
     if (!isJsonRpcRequest(body) || body.method !== 'tools/call') return 'read';
-    const name = paramsOf(body)?.['name'];
+    const params = paramsOf(body);
+    const name = params?.['name'];
     // An unresolvable call is refused before it runs, so charging it the strict bucket
     // only costs a broken client — it never hands an unproven verb the cheap one.
     if (typeof name !== 'string') return 'write';
+    if (this.meta !== undefined && name === MANAGE_RESOURCE) {
+      // Billed as the tool it reaches, so the dispatcher is never a cheap door to a write.
+      const args = params?.['arguments'];
+      const action = isRecord(args) ? args['action'] : undefined;
+      return typeof action === 'string' ? this.tools.verbClass(action) : 'write';
+    }
+    if (this.meta !== undefined && META_TOOL_NAMES.includes(name)) return 'read';
     return this.tools.verbClass(name);
   }
 
@@ -190,9 +235,45 @@ export class McpServer {
       return errorResponse(id, INVALID_PARAMS, 'tools/call params.name must be a string');
     }
 
+    const meta = this.metaFor(caller);
+    if (meta !== undefined) {
+      const answered = await metaCall(
+        {
+          tools: this.tools,
+          dispatch: (at, tool, resolved, who) => this.dispatch(at, tool, resolved, who),
+          notFound: (at, tool, who, fix) => this.notFound(at, tool, who, fix),
+        },
+        meta,
+        { id, name, rawArgs: params['arguments'], caller },
+      );
+      if (answered !== undefined) return answered;
+    }
+    return this.dispatch(
+      id,
+      name,
+      this.tools.resolve(name, params['arguments'] ?? {}, caller),
+      caller,
+    );
+  }
+
+  /** 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' });
+    return errorResponse(id, METHOD_NOT_FOUND, `tool not found: ${name} — ${fix}`);
+  }
+
+  /**
+   * Resolve → run → audit, for a flat `tools/call` and for `manage_resource` alike: ONE path, so
+   * the two surfaces cannot answer the same call differently.
+   */
+  private async dispatch(
+    id: JsonRpcId,
+    name: string,
+    resolved: ToolResolution,
+    caller: McpCaller,
+  ): Promise<JsonRpcResponse> {
     // Three outcomes, deliberately different — and every one of them audited, including the
     // one that tells the caller nothing. See `audit.ts`.
-    const resolved = this.tools.resolve(name, params['arguments'] ?? {}, caller);
     switch (resolved.kind) {
       // OUTCOME 1. Absent AND role-hidden collapse to the same answer, with no `data` at
       // all: any extra field would be the difference a prober is looking for. The message
@@ -200,8 +281,12 @@ export class McpServer {
       // nothing about whether the name exists: the same sentence for a stale name and for a
       // tool this role may never see, so the hint is not a second oracle.
       case 'not-found':
-        auditToolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
-        return errorResponse(id, METHOD_NOT_FOUND, `tool not found: ${name} — ${TOOL_UNKNOWN_FIX}`);
+        return this.notFound(
+          id,
+          name,
+          caller,
+          this.metaFor(caller) ? META_UNKNOWN_FIX : TOOL_UNKNOWN_FIX,
+        );
       // OUTCOME 2. The caller can already see this tool, so naming the missing scope leaks
       // nothing — and the fix travels with it, built by the error that owns the wording.
       case 'scope-denied': {
@@ -369,55 +454,5 @@ function protocolRefusal(message: string, error: McpProtocolError): JsonRpcRespo
   });
 }
 
-interface FrameworkError {
-  readonly code: string;
-  /** `''` for a foreign thrown object that carries no title. See `renderFrameworkError`. */
-  readonly title: string;
-  readonly cause: string;
-  readonly fix: string;
-}
-
-/**
- * Read a thrown framework error, or `undefined` when it is not one (a genuine bug, which
- * becomes `-32603` with no internals leaked). Structural rather than `instanceof`: the
- * transport must stay independent of which package threw.
- */
-function asFrameworkError(error: unknown): FrameworkError | undefined {
-  // `stringField` from `@ultimat3/core`, never `typeof e.code === 'string'`: the value is whatever
-  // an app's handler, its driver or its SDK threw, so each read is a getter call or a `Proxy`
-  // trap. This runs inside the catch block that owes the caller an answer, and a probe that
-  // raises here leaves the JSON-RPC request with no response at all — not even the `-32603` the
-  // header promises for a genuine bug.
-  const code = stringField(error, 'code');
-  // `FRAMEWORK_CODE`, never `startsWith('X_')`: the substituted `fix:` below interpolates this
-  // value into a COMMAND an agent is told to run, and `X_$(id)` passes a prefix test. A code is
-  // `X_SCREAMING_SNAKE` and nothing else, so a value that is not one is not a framework error —
-  // it takes the `-32603` branch, which leaks nothing of the throw.
-  if (code === undefined || !FRAMEWORK_CODE.test(code)) return undefined;
-  return {
-    code,
-    title: stringField(error, 'title') ?? '',
-    cause: stringField(error, 'cause') ?? 'unknown',
-    // A substituted fix is still a fix an agent will act on, so it has to be runnable. `see docs`
-    // named no docs and no command; `code` is already narrowed to an `X_` string by the guard
-    // above, so the substitute is the one command that explains exactly this code.
-    fix: stringField(error, 'fix') ?? `x errors explain ${code}`,
-  };
-}
-
-/**
- * The agent-readable form, BYTE-IDENTICAL to `UltimateError.format()` — one denial reads the
- * same over MCP as it does in the terminal, so an agent that learned the shape from `x` does
- * not have to learn a second one here. Dropping the title would be a second rendering of the
- * same contract, and the two would drift.
- *
- * The bare-`code` head is the fallback for a foreign thrown object that carries `code`/`cause`
- * but no title; a real `UltimateError` always has one.
- */
-function renderFrameworkError(error: FrameworkError): string {
-  const head =
-    error.title === ''
-      ? singleLine(error.code)
-      : `${singleLine(error.code)}: ${singleLine(error.title)}`;
-  return `${head}\n  cause: ${singleLine(error.cause)}\n  fix:   ${singleLine(error.fix)}`;
-}
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);