MCP and AI

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.

Built-in MCP dev server

x mcp serve is the dev-tool server, over stdio or HTTP; x dev does not start it. Point any MCP client at it and the agent stops guessing. A new app's .mcp.json already names it — Client config.

The whole catalog, spelled exactly as each tool must be called; bunx x mcp tools --json reads it off the server rather than a count here. 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.

Client config

x new writes one client config, .mcp.json at the app root — the format several MCP clients read — and no per-vendor directory: a second copy is a second thing to drift.

{
  "mcpServers": {
    "myapp": {
      "command": "bunx",
      "args": ["@ultimat3/cli", "mcp", "serve", "--transport", "stdio"]
    }
  }
}

bunx @ultimat3/cli, never bunx x, in a client config. A client may spawn the command outside the installed app, and there bunx x fetches an unrelated npm package named x. Inside an app's shell, bunx x resolves the app's own CLI. scaffold-mcp-json.test.ts pins the spelling, and CI's scaffold-smoke spawns the file's own command and asks it initialize and tools/list on every push.

Rate limits on the HTTP transport

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.

Protocol revisions: modern and legacy, one endpoint

As of 2026-11, read from the spec on 2026-11-02. Every server is dual-era: the era is decided per request, never per connection.

MCP_PROTOCOL_VERSION is gone (As of 2026-11): name the era — MCP_MODERN_VERSIONS[0], or MCP_LEGACY_VERSIONS. resources/templates/list is { resourceTemplates: [] } on both eras. A resource not found, hidden or absent, is one answer: -32601 legacy, -32602 modern. Not served and not advertised: subscriptions/listen, multi-round-trip input, the tasks extension, x-mcp-header, SSE responses; every listChanged is false.

Over HTTP:

Every action is an MCP tool

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.

What a client is told beyond the schema

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.

Split by effect (surface: 'meta-split', As of 2026-10-18): read_resource (queries, readOnlyHint: true), write_resource (mcp: { effect: 'write' }) and delete_resource (mcp: { effect: 'delete' }, destructiveHint: true; { resource, action, params, live, confirmed_by_user } — without live: true it answers a preview (the framework's runs nothing; an action declaring live answers its own), with it it runs only on confirmed_by_user: true) replace manage_resource, for clients and directories that refuse a dispatcher which both reads and writes. A grouped write without an effect fails boot (X_MCP_EFFECT_UNDECLARED); an action called on the wrong dispatcher is X_MCP_WRONG_TOOL naming the right one; an unconfirmed commit is X_MCP_USER_CONFIRMATION_REQUIRED. Full contract: packages/mcp/README.md.

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

A catalog too big for that: catalogDetail: 'compact', once, in defineAppMcp (As of 2026-11). Each resource line stays; its actions become ONE line of names, grouped by kind tag, with confirms and an unhoisted scope still on the action. Descriptions and parameter hints move to describe_resource, which the header tells the model to read before a resource's first call. Measured on a 46-resource, 322-action catalog: 95,318 characters full, 13,085 compact. Refused on a server no caller reads list_resources from (X_MCP_SURFACE_INVALID).

posts (query scope app:use; action scope posts:write) — Blog posts
  listPosts; action: publishPost (confirms), archivePost

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 — declared once with defineError:

import { defineError } from '@ultimat3/core';

export const RefundWindowClosed = defineError<{ readonly ageDays: number }>({
  code: 'X_REFUND_WINDOW_CLOSED',
  title: 'the refund window has closed',
  status: 403,
  cause: (p) => `the payment is ${p.ageDays} 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.

The app's own endpoint is mounted by the web role

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 per app directory:

A token from an external issuer (As of 2026-11-05): an app whose agents present an IdP's JWT rather than an API key hands defineAppMcp jwtBearerResolver from @ultimat3/auth — the twin of apiKeyResolver. The signature, issuer, audience and time checks are verifyWorkloadToken's; the app keeps only its claim check and its actor:

// apps/web/app/auth/agent-token.ts
import { actorFromService, jwksClient, jwtBearerResolver } from '@ultimat3/auth';

const ISSUER = 'https://login.example.com/tenant-a/v2.0';
const TENANT = 'tenant-a';
const ORG_ID = '00000000-0000-4000-8000-000000000001';
const keys = jwksClient({ provider: ISSUER, jwksUri: `${ISSUER}/discovery/v2.0/keys` });

export const resolveAgentToken = jwtBearerResolver({
  keys: () => keys,                       // read per token: no network at import
  issuers: [ISSUER],
  audience: 'api://ledger',
  requiredScope: 'ledger.agent',          // optional; the scope name is the app's
  accept: (raw) => raw['tid'] === TENANT, // the app's own claim, after the signature held
  actorOf: (token) => actorFromService({ ...token.identity, orgId: ORG_ID }),
});

Every refusal is null — the mount's 401 — and one auth.jwt_bearer.refused line naming the check (signature, issuer, audience, expiry, not-before, scope, accept, key-set), never a claim's value. A key set that cannot be read and an unknown kid both fail closed.

Several endpoints, one per population

As of 22.14.0. 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: 'acme', include: 'exposed', scopes: CUSTOMER_SCOPES, resolveToken: customerToken, oauth }),
  defineAppMcp({ name: 'acme-admin', path: '/mcp/admin', tools: staffTools, surface: 'meta', groups, scopes: STAFF_SCOPES, resolveToken: staffToken, oauth }),
  defineAppMcp({ name: 'acme-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.

OAuth discovery for remote connectors

defineAppMcp({ oauth }) makes the endpoint an OAuth 2.1 protected resource per the MCP authorization spec (As of 2026-11, served at modern 2026-07-28 and the legacy handshake revisions 2025-11-25 / 2025-06-18 / 2025-03-26) and RFC 9728 (As of 22.6.0). Discovery is not the same in each: RFC 9728 protected-resource metadata is required from 2025-06-18 on; 2025-11-25 made the 401's WWW-Authenticate optional with a .well-known fallback (SEP-985) where 2025-06-18 required it; 2025-03-26 defines none, its discovery being RFC 8414 authorization-server metadata at the origin:

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 is mcpAuthorizationServer (As of 2026-11): @ultimat3/auth's authorizationServer (Auth) bound to this endpoint. One call, one consent page:

// apps/web/mcp-oauth.ts
import { postgresAuthServerStore } from '@ultimat3/auth';
import type { Actor, PgExecutor } from '@ultimat3/core';
import type { McpScopes } from '@ultimat3/mcp';
import { defineAppMcp, mcpAuthorizationServer } from '@ultimat3/mcp';

declare const executor: PgExecutor;
declare const MCP_SCOPES: McpScopes;             // the scope → tool names map, as above
declare function agentFor(subject: string): Promise<Actor | null>;

export const as = mcpAuthorizationServer({
  issuer: 'https://www.example.com',
  resource: 'https://www.example.com/mcp',
  store: postgresAuthServerStore({ executor }),
  consentPath: '/oauth/consent',
  lifetimes: { accessSeconds: 600, refreshIdleDays: 30 },
  scopes: Object.keys(MCP_SCOPES),
  registration: 'dynamic',                    // omitted: metadata-document client ids only
  actor: (grant) => agentFor(grant.subject),  // per call: a removed member is refused at once
});
export const mcp = defineAppMcp({ include: 'exposed', scopes: MCP_SCOPES, oauth: as.oauth, resolveToken: as.resolveToken });
// apps/web/runtime.ts: routes: [...as.routes]

Without oauth, the 401 is Bearer realm="ultimate-mcp" as before. Bad block: X_MCP_OAUTH_INVALID at definition.

Per-caller tools and one token across tenants

As of 2026-11. Two defineAppMcp options, both resolved per request and both behind the same gates as every other tool:

A tenant the person is not in (resolve answers null) gets exactly the answer a hidden tool gets. Another caller's runtime tool is an absent tool. The audit line carries tenant.

tools/list is person-scoped, and not a promise. MCP's tools/list names no tenant, so visibleTo (function form), can() and catalog run there as the person; tools/call runs them as the tenant actor and is authoritative. A tool visible to the person but not the tenant actor is listed and answers as a hidden tool; one visible only through a tenant role or a tenant's catalog row is unlisted and still runs when called by name.

import { agentActor } from '@ultimat3/core';
import { defineAppMcp, runtimeTool } from '@ultimat3/mcp';

declare function roleIn(personId: string, org: string): Promise<string | undefined>;

defineAppMcp({
  include: 'exposed',
  tenant: {
    arg: 'org',
    resolve: async ({ person, value }) => {
      const role = await roleIn(person.id, value);
      return role === undefined ? null : agentActor({ id: person.id, orgId: value, roles: [role] });
    },
    list: () => [],
  },
  catalog: (caller) => ({
    tools: caller.actor.orgId === undefined ? [] : [
      runtimeTool({
        name: 'org_ping',
        description: 'Ping the acting org. Read-only.',
        inputSchema: { type: 'object', properties: {} },
        permission: 'org:read',
        destructive: false,
        run: ({ ctx }) => ({ org: ctx.actor.orgId }),
      }),
    ],
  }),
});

Worked example: Postly's quote_<plan> tools and its multi-org token — examples/dummy/packages/mcp/src/{quotes,tenants}.ts, proven over its own endpoint by tenant.contract.test.ts. Full rules: packages/mcp/README.md.

Long tools: jobTool() and job_status

A tool whose work outlives a client's timeout. tools: { reindex: jobTool({ job, policy, description, result, input?, jobInput?, inlineMs? }) }.

The reference app's draftReview (examples/dummy/apps/web/mcp-tools.ts) queues reviewDraftLater for the caller's own member and reads postReview back; mcp-tools.contract.test.ts drives it over the wire.

Recipes: docs://recipes/<name> and the docs tool

defineAppMcp({ recipes: [{ name, title, description, steps: [{ tool, why, example? }], notes? }] }).

From a markdown folder. recipes: await markdownRecipes({ dir: join(import.meta.dir, 'docs') }) reads one *.md per recipe and serves its body verbatim. The file name is the recipe name. title: and description: come from --- frontmatter, else from the first # heading and the paragraph under it. A fence tagged call holds one step, tool {"arg": "value"}, and is checked at boot like any step.example. A whole "<postId>" value is a placeholder, so any value passes at boot. A docs://recipes/<name> link in the text that names no recipe is X_MCP_RECIPE_LINK_DANGLING.

Searching. docs({}) lists what this caller can follow. docs({ name }) and docs({ uri }) read one recipe. docs({ q }) inlines the best match, scoring 3 for each word in the name or title, 2 in the description and 1 in the body. On a miss it names the nearest recipes, so a caller with any visible recipe never gets an empty answer.

Per caller. extraRecipes: (caller) => recipes adds the caller's own recipes, such as a tenant's runbooks. They are listed as source: 'caller' on docs, and on resources/list and resources/read to that caller only. They are not checked at boot. A recipe that names a tool the caller cannot call is not shown.

Replayed. In a contract test, await replayRecipes(server, recipes, { caller, placeholders }) calls every step's example through the real server as caller and reads every link. Three answers fail it with X_MCP_RECIPE_EXAMPLE_INVALID: no such tool, refused arguments, and a policy that refuses that caller. A dangling link fails it with X_MCP_RECIPE_LINK_DANGLING. A tool's own refusal (X_NOT_FOUND for a sample id) counts as the tool working. The reference app replays its recipes as an org owner: examples/dummy/packages/mcp/src/recipes-replay.contract.test.ts.

Consuming another server: mcpTools()

Remote MCP tools as this app's actions — the app's policy, rate limit, confirmation gate and manifest row; one tool list for an agent.

Five outcomes of a call. meta.failure tells them apart without reading a cause:

Streaming. A server may answer any POST as JSON or as text/event-stream. The client reads the answer with its own id out of the stream, and acts on any notifications/tools/list_changed riding with it. A legacy (2025-era) session also gets one long-lived GET stream for the server's own messages. It is opened after initialize, detached from the request that opened it, and lives listenMs (default 5 minutes) before the next call opens another. A 405 means the server offers no such stream, and the client never asks again. client.close() ends it. A modern server is stateless, so its changes ride response streams only. Either way, a change makes the next call re-list and hold the list to the lock again.

OAuth to the upstream. mcpOAuthClient({ clientId, clientName, redirectUri, scopes? }) is the client half of the MCP authorization spec:

1. begin(serverUrl) reads the server's RFC 9728 protected-resource document, then its authorization server's RFC 8414 metadata. It answers { authorizeUrl, handshake }, with PKCE S256 from @ultimat3/auth and resource per RFC 8707.
2. Redirect the person to authorizeUrl. Keep handshake server-side, in the person's session.
3. On the callback, exchange(handshake, { code, state }) answers { accessToken, refreshToken, expiresIn }. refresh(handshake, refreshToken) answers the same shape.
4. Store the tokens per connection. Return the access token from mcpTools({ auth }), which is read on every call, so a rotated token is never cached.

clientId is the HTTPS URL at which this app serves metadata() (a client ID metadata document), or an id the authorization server issued when the app was registered by hand. A 401 mid-session is X_MCP_REMOTE_AUTH_REQUIRED: run the handshake again.

Proved on itself. examples/dummy/packages/mcp/src/remote-self.contract.test.ts points mcpTools() at the reference app's own MCP route. It locks the live list, calls seatReport, and meets three refusals: the remote policy's X_FORBIDDEN as a result, a stolen token as X_MCP_REMOTE_AUTH_REQUIRED, and a schema moved since the lock as X_MCP_REMOTE_TOOL_CHANGED.

Three outcomes, deliberately different

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.

Generated facts, hand-written conventions

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.

LLM gateway

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

export const summarize = llm({
  model: 'claude-sonnet-5-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.

Showing what a model wrote is Markdown from @ultimat3/ui, never innerHTML: the text is parsed to a tree and rendered as elements, so a <script> or a javascript: link in an answer is text, and a streaming answer re-parses per token while finished blocks keep their nodes. Tool calls and usage records are JsonView; a model's proposed edit against the original is DiffView → UI components.

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.

Agents, hives and agent jobs → Agents

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.

A tool in mcpConfirmations({ tools }) waits for a person on both surfaces: X_MCP_CONFIRMATION_PENDING over tools/call, on a server handed confirmations or not, and as an agent's tool_result. A name no tool answers to is X_MCP_CONFIRMATION_TOOL_UNKNOWN at the manifest step. One list, no second option → A tool that waits for a person.

Quorum and signed decisions (As of 2026-11) are two more options on the same factory, never a second gate:

verifyConfirmationEvidence(row, { evidence, quorum, from, arguments }) is exported so a separate process that executes the action re-checks the stored evidence with public keys alone. ttlMs expires a partly approved row like any other; one rejection rejects. The full table: @ultimat3/mcp README.

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

Prompts as versioned artifacts

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

Vectors and hybrid search

pgvector in the same Postgres. No second datastore.

Evals as a test type

eval is one of the six test types in Testing.

Branch environments

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

--json everywhere

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"}]}]}

Errors

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

Rules

• 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