The differentiator. Not a chat widget, not an "AI SDK integration" — the framework is built so an agent can read it, drive it, and verify its own work, and so the apps it generates have the same property.

As of 2026-08. Stable API — semver from here (Upgrading). The MCP registry, wire protocol, dev-tool catalog, read-only SQL guard, and action projection are built, and so are the four that used to be contracted: llm() is an action factory (packages/ai/src/llm.ts), prompts are versioned, postgresVectorStore() fuses pgvector cosine with Postgres FTS via RRF, and evals gate on a committed baseline inside x verify's eval step.

x dev starts an MCP server on the dev socket. Point Claude Code (or any MCP client) at it and the agent stops guessing.

Sixteen tools As of 2026-09-19 — the whole catalog, spelled exactly as they must be called. No aliases; renaming one is a major.

None of them is exposed in ROLE=web. db.query accepts one statement, whose leading keyword must be SELECT/WITH/EXPLAIN/SHOW/TABLE/VALUES — necessary, never sufficient. Batches, any write keyword at statement level (a data-modifying CTE included), locking clauses (FOR UPDATE/FOR SHARE), EXPLAIN ANALYZE, and whole function families matched by prefix of the called name, quoted and schema-qualified spellings included — file access (pg_read_*, pg_ls_*, lo_*, dblink), locks (pg_advisory_*), session settings (set_config), sleeps (pg_sleep*), catalog writes (pg_import_*) and the functions that run a query handed to them as text (query_to_xml*, cursor_to_xml*, table_to_xml*, schema_to_xml*, database_to_xml*, ts_stat, ts_rewrite) — are refused, not discouraged — X_MCP_QUERY_REJECTED, enforced before the host sees the string. What the scan cannot read is refused, never decoded: a Unicode-escaped quoted identifier (U&"…") is X_MCP_QUERY_REJECTED (As of 2026-10). A keyword is matched as Postgres lexes an identifier, so a column set2 is a column, not SET. Its Postgres SELECT-only role is conditional on the connection's own rights; the answer's guards array names the defences that engaged. db.migrate refuses a target that is not a branch database — X_MCP_NOT_BRANCH_DB.

Enforced As of 2026-08-24. mcpHttpRoute meters itself, per caller, per class, per minute. It has to: all MCP traffic is one POST /mcp, so the HTTP pipeline's own buckets — which key on the route — cannot tell an initialize handshake from a migration.

mcp: { expose: true, description: 'Publish a draft post' },

That line is the entire integration. From the existing declaration:

The projected tool's run is invoke — the same entry point the HTTP route calls (packages/mcp/src/projectable.ts). Policy runs inside it, so there is nothing to keep in sync. The projection itself adds no MCP scope: a second gate hard-coded into the projection would sit in front of the only gate that matters, and the two would eventually disagree. defineAppMcp's scopes: map may still attach one from outside — a property of the connection's token, never invented by the projection.

No MCP-specific permission table, no service account with broad rights. Exposure is opt-in; silence exposes nothing.

The user's own agents can therefore operate the user's product — refund an order, re-run an import, publish a post — with the exact permissions that user has in the UI. See Admin dashboard and Actions.

As of 22.10, MCP 2025-06-18. Every piece is optional for the app; the defaults come from the declaration already written.

mcp: {
  expose: true,
  description: 'Tag a post. Adds, never removes.',
  title: 'Tag post',
  annotations: { destructiveHint: false },
},

An outputSchema is structure only — type, properties, required, items, enum, const, anyOf. A client validates structuredContent against it and refuses the call on a miss, so a bound, a pattern or additionalProperties: false on rows read from the database would be a promise nothing enforces on the way out. The meta tools publish their own hints: list_resources / describe_resource read-only, manage_resource a write (it reaches every grouped tool); manage_resource answers the inner tool's structuredContent byte for byte.

What the model reads is compact. A tool's text block is one-line JSON (the 2-space form until 22.10 spent a third of a large answer on indentation). list_resources answers plain text, one line per resource and one per action, each fact said once where it is cheapest (As of 2026-10):

2 resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas. Untagged = read-only query; (action) may write; (confirms) waits for a human; … = more in describe_resource.

org (scope app:use) — The organisation
  transferOrg (action) {} — Transfer the org

posts (query scope app:use; action scope posts:write) — Blog posts
  listPosts {status_eq?: string|number|boolean, title_cont?: string, sort?: "createdAt"|"-createdAt", …} — Posts, filtered
  publishPost (action; confirms) {postId: string} — Publish a draft post

The same catalog as data, for a test: mcp.server.catalog(caller) — every action keeps its own scope there. describe_resource stays compact JSON with the full schema — a schema is JSON.

Hold the standing surface to a number. tools/list rides every step and list_resources sits in the transcript all session:

import { assertMcpSurfaceBudget } from '@ultimat3/mcp';

test('the staff surface stays small', async () => {
  // The derivation beside the number: the size measureMcpSurface reported, × a margin.
  await assertMcpSurfaceBudget(mcp.server, staffCaller, { toolsList: 4_000, listResources: 12_000 });
});

measureMcpSurface(server, caller) returns { toolsList, listResources, instructions } in characters, off the wire; the assert refuses every surface over its ceiling in one X_MCP_SURFACE_OVER_BUDGET.

Refusals speak to the caller. defineAppMcp renders an error's callerFix — what a remote agent can do — where the framework's own fix names a command only the app's developer can run: X_FORBIDDEN says to ask the account owner for the permission, not x policy explain; a missing scope says to ask for a token that carries it; an invalid argument says to correct the field against the published schema. The developer's fix stays in the log line, --json, and on mcpServer (the dev server), whose default is errorAudience: 'developer'; defineAppMcp({ errorAudience: 'developer' }) restores it for an app. A 5xx cause is the server's own business (As of 2026-10): for the caller audience, a thrown 5xx code core's hasPublicCause does not list (X_DB_STATEMENT_FAILED carries the Postgres message and the statement) renders a fixed sentence as its cause and x errors explain <code> --json (or its callerFix) as its fix — in a tool result and in a resources/read error's data alike, the verdict a production problem document gives. The developer audience keeps both. An app's own error takes the same two fields, plus docs:

class RefundWindowError extends UltimateError {
  constructor() {
    super({
      code: 'X_FORBIDDEN',
      cause: 'the payment is 142 days old; refunds are limited to 90 days',
      fix: 'x policy explain refund:create --json',
      callerFix: 'issue a credit note instead',
      docs: 'docs://recipes/issue-a-credit-note',
    });
  }
}

A docs other than the framework's one Error-Codes page is a fourth line of the tool result — docs: docs://recipes/issue-a-credit-note — and is the docs member of the problem document over HTTP. A production problem document carries callerFix as its fix; a dev one keeps the developer's.

As of 2026-09-05. defineAppMcp({ …, resolveToken }) builds mcp.route, and app.config.ts declares ai: { mcp: { expose: true } } by default (the path is defineAppMcp's own, /mcp by default) — and until this date nothing between the two served it: POST /mcp was X_ROUTE_NOT_FOUND under x dev and in every container. The contract is one file:

As of Unreleased. mcp may be a non-empty array of defineAppMcp values — one endpoint per population, each with its own catalog, instructions, groups, scopes and oauth. Same export name, same file; the order is the contract:

// apps/web/mcp.ts
export const mcp = [
  defineAppMcp({ name: 'notificado', include: 'exposed', scopes: CUSTOMER_SCOPES, resolveToken: customerToken, oauth }),
  defineAppMcp({ name: 'notificado-admin', path: '/mcp/admin', tools: staffTools, surface: 'meta', groups, scopes: STAFF_SCOPES, resolveToken: staffToken, oauth }),
  defineAppMcp({ name: 'notificado-afiliados', path: '/mcp/afiliados', tools: affiliateTools, scopes: AFFILIATE_SCOPES, resolveToken: affiliateToken, oauth }),
];

The same discovery serves an app's RuntimeOverrides: apps/<app>/runtime.ts exporting runtime reaches x dev (its middleware, rate-limit store and plain routes) and runRole when apps/web/server.ts passes none — one middleware chain in development and in the container, not two. runtime.routes (As of 22.6.0) is the one escape hatch for a URL no primitive projects to and a wire format none speaks — an OAuth token endpoint answering RFC 6749 JSON to a form-encoded POST — mounted after the framework's routes and before the pages, through the whole pipeline.

defineAppMcp({ oauth }) makes the endpoint an OAuth 2.1 protected resource per the MCP authorization spec (2025-06-18; unchanged in 2025-11-25) and RFC 9728 (As of 22.6.0):

export const mcp = defineAppMcp({
  include: 'exposed',
  scopes: MCP_SCOPES,
  resolveToken,
  oauth: {
    authorizationServers: ['https://www.example.com'], // issuer(s); https, or http on localhost
    resourceName: 'Example',
    // resource: 'https://www.example.com/mcp',   // omitted: the request's PUBLIC origin + path
    // scopesSupported: [...],                     // omitted: Object.keys(scopes)
  },
});

The authorization server (/.well-known/oauth-authorization-server, /oauth/authorize, /oauth/token) is the app's: consent is a page, and the endpoints whose wire format RFC 6749/8414 fixes are plain routes from apps/<app>/runtime.ts → runtime.routes. Without oauth, the 401 is Bearer realm="ultimate-mcp" as before. Bad block: X_MCP_OAUTH_INVALID at definition.

Role, scope and policy refuse in three distinguishable ways. The difference is the security property, not an implementation detail.

Hidden means hidden: Forbidden on a hidden tool is an enumeration oracle — an agent, or an attacker driving one, walks a name list and reads the org's feature set, entity names and internal operations off the difference between "not found" and "forbidden". A scope refusal is the opposite case: a well-behaved client can legitimately fix it, so hiding it would only strand the caller.

Where the first two outcomes are declared:

Rationale for each: docs/architecture/11-ai-surface.md.

LLM-generated context files measurably reduce task success. A model writing "here is what this codebase does" produces confident, plausible, partly-wrong prose, and the next agent treats it as ground truth — errors compound and cannot be distinguished from facts. So: facts come from code (structured, verifiable, regenerated every build), conventions come from a human (short, opinionated, stable). Ultimate never generates prose documentation at runtime, and x new scaffolds AGENTS.md as a terse human-editable stub, not an essay.

One typed entry point for model calls — provider-agnostic, observable, cached, evaluated.

export const summarize = llm({
  model: 'claude-sonnet-5',
  input:  t.object({ postId: t.uuid }),
  output: t.object({ summary: t.string, tags: t.string.array() }),
  prompt: summarizePrompt,                       // versioned artifact
  cache:  { semantic: { threshold: 0.97, ttl: '7d' } },
  budget: { tokensIn: 8000, costPerCall: { minor: 5, currency: 'USD' } },
  policy: can('post:read'),
});

A stream is the same action over a different transport, with one difference that is forced rather than chosen: there is no repair turn. The non-streaming call retries once on a parse failure; a stream cannot, because the tokens are already on the reader's screen and a second answer is two answers to one question. So a stream yields unvalidated text increments plus one final done carrying the value that did satisfy output, and a schema disagreement is X_LLM_STREAM_INVALID naming the non-streaming call as the fix. A structured schema wants the non-streaming call.

Long or multi-call chains are jobs with steps, so a model call that fails on step 4 retries step 4 only. See Jobs and workflows.

llm() is one model call. A tool-using loop is agent(), and it is the same kind of thing — an action factory, not a ninth primitive. Everything the loop needs is a factory over a primitive already in the vocabulary:

A tool is one of two things. A real action() carrying mcp: { expose: true } — the same predicate an external MCP client is filtered by, so an in-app agent and an external one are offered exactly the same catalogue of actions and authorize identically. Or an inProcessTool({ name, description, input, execute }): a tool that is this process's alone, with no mcp flag, in no MCP catalogue, route or openapi.json, running as ctx.actor under the agent's own policy → In-process tools. An agent() returns an action, so an agent is a tool of another agent with no supervisor primitive anywhere.

Full reference, including the at-least-once trap that makes every mutating tool's idempotency your obligation: Agents.

apps/web/app/posts/prompts/summarize.v3.md      # the prompt, plain markdown + typed slots
apps/web/app/posts/prompts/summarize.evals.ts   # evals attached to it

pgvector in the same Postgres. No second datastore.

eval is one of the six test types in Testing.

The shipped surface is x db branch, with three verbs. x branch (no db) is planned and exits X_NOT_IMPLEMENTED; the build-id and MCP-socket rows below are what it will add.

x db branch create feat-new-billing --json
x db branch list --json
x db branch delete feat-new-billing --json

Every command and every error has a machine-readable form. Same content, different encoding.

$ x verify --json
{"ok":false,"checks":[{"name":"budgets","ok":false,"failures":[
  {"route":"site/pricing","metric":"js","actual":"61kb","limit":"40kb",
   "cause":"chart.js via shared/ui/button.tsx",
   "fix":"x fix boundary site/pricing/page.tsx"}]}]}

Full list: Error codes. CLI surface: CLI reference.

• One authz system. An MCP call and an HTTP call reach the same policy with the same actor resolution.
• One name. A projected tool is called the primitive's export name, verbatim, in tools/list, in scopes:, in the LLM tool list, in openapi.json and in describe(). There is no second spelling to derive.
• Exposure is opt-in per action; the projection carries no scope of its own — defineAppMcp's scopes: map may still attach one, from outside the primitive.
• Visibility is fail-closed and computed per connection. A hidden tool answers ToolNotFound, never Forbidden.
• Gate order is visibility → scope → arguments → policy, and every outcome is audited. There is no trusted-tool mode.
• Write tools are branch-scoped. The dev server is never reachable in ROLE=web.
• Facts are generated every build; conventions are hand-written and short.
• Never generate prose documentation at runtime.
• Every command and every error has a --json form; budgets throw before spending, in Money.
• Every prompt is a versioned file with an evals file.

Source: packages/mcp/src