@softure-ai/mcp-access 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`mcp-access@x.y.z`).
 
+## 0.3.0
+
+- Long operations as MCP Tasks (#977), in `@softure-ai/mcp-access/jobs`: `startOperation` takes `taskRequest` (the
+  tool handler's request context) and `taskTtlSeconds`; when the client declared the Tasks extension
+  (`io.modelcontextprotocol/tasks`, revision 2026-07-28) on that request, the tool answers a task instead of an
+  operation id. `registerOperationTasks(server, { ctx, identity, readResult?, poll? })` declares the extension and
+  serves `tasks/get` (working, completed with the `get_operation` answer, `isError` for a failed operation, cancelled),
+  `tasks/update` and `tasks/cancel` (write access only), scoped to the account. Task ids are random and live in the
+  new table `mcp.operation_tasks` (migration `0006`), pruned past their expiry by `pruneMcpAccess` (which now also
+  counts `operationTasks`, and `softure-mcp prune` prints it) and deleted with the account. Every other client keeps the
+  polling tools. Migrate: run `softure migrate`; to offer tasks, pass the handler's second argument as `taskRequest`
+  and call `registerOperationTasks` on the same server (README "As MCP Tasks").
+- Long operations as tools (#952), in `@softure-ai/mcp-access/jobs` on top of `@softure-ai/jobs` (with the progress
+  and running-job cancel of jobs #951): `startOperation(ctx, identity, { queue, payload, dedupKey? })` enqueues and
+  answers `{ operationId, status: "queued", pollAfterSeconds, message }` at once; `registerOperationStatusTool`
+  (`get_operation`) answers the status, the handler's progress, a growing `pollAfterSeconds`, the app's `result`
+  (`readResult`) and the `errorCode`; `registerOperationCancelTool` (`cancel_operation`, write access only) cancels a
+  queued operation and asks a running one to stop. Operations are scoped to the caller's account; no migration.
+  Migrate: an app with its own "start returns an id" and "status" tools can replace them with these (README "Long
+  operations").
+- Personal tokens for the app's plain HTTP routes (#961): the option `apiTokens` (`prefix`, default `sftapi_`;
+  `scopes` with `read`/`write` access and a description; `examples` for the one-time reveal) turns on a second token
+  kind. `requireApiToken(ctx, request, { scopes })` checks a route's request: client address counted (bucket `api`),
+  Bearer token verified, token counted (bucket `api-token`), scopes and the write switch checked; refusals are values
+  that `apiTokenErrorResponse` answers (400/401/403/429/503). The new entry `@softure-ai/mcp-access/tokens` exports
+  it with `issueApiToken`, `verifyApiToken`, list, revoke and prune, and loads no MCP SDK. An API token never opens
+  the MCP endpoint and an MCP token never passes the check. The token page lists the app's scopes, adds the form
+  "New token for other apps" (`kind=api`, `scope:<name>` fields), shows the token once with the app's examples
+  (form state `api-ok`, `IssuedApiTokenView`) and names each token's kind. `AccessTokenView` gains `kind` and
+  `scopes`; the gate input `kind` and `scopes`; the privacy export `kind` and `scopes`. Both kinds share
+  `maxTokensPerUser`. Migration `0005_add_api_tokens.sql` adds `kind` and `scopes` (existing rows stay MCP tokens).
+  Migrate: nothing for an app without `apiTokens`, apart from running the migration; an app that compares
+  `listAccessTokens` or the privacy export field by field gains the two fields. To use it, add `apiTokens`, spread
+  `API_TOKEN_RATE_LIMIT_BUCKETS` into `security({ buckets })` and call `requireApiToken` in the routes.
+- Confirmed tool calls (#953): `withConfirmation(handler, { ctx, identity, tool, estimate, ttlSeconds?,
+  runWithoutConfirmationWhen?, secret? })` (`/server`) makes a priced or irreversible tool estimate first and answer
+  `{ needsConfirmation: true, estimate, confirmation, expiresAt, message }`; the second call with the same arguments
+  and the token does the work. The token is an HMAC bound to the tool, the canonical arguments, the account and access
+  token, the estimate's total and the expiry, single use (stored by hash in the new `mcp.used_confirmations`), and a
+  mismatch is refused as `input.confirmation_invalid`, `_other_tool`, `_other_account`, `_expired`,
+  `_arguments_changed`, `_estimate_changed` or `_used`. `confirmationInput` is the schema field. `ToolCallRecord`
+  gains `confirmed: boolean | null` (`null` for other tools), and `pruneMcpAccess` counts `usedConfirmations`.
+  Migrate: run `softure migrate` (file 4). To confirm a tool, set `MCP_CONFIRMATION_SECRET` (32+ characters), add
+  `confirmation: confirmationInput` to its input schema and wrap its callback; drop an app-level `confirm: true`
+  boolean the assistant could set itself. A test that builds a `ToolCallRecord` by hand adds `confirmed: null`.
+- Strict tool input lists a required nullable scalar as required (#919): a `z.number().nullable()` or
+  `z.boolean().nullable()` field that the parse requires is in `required` of the listed schema again, and a scalar
+  field's `default` (or `prefault`) is listed. The parse rules are unchanged. Migrate: an app that copied the inner
+  schema's `optin` onto its own text step, or put a `default` inside it, can drop that wrapper.
+- A tool registered without an input schema on a strict server gets the strict empty object (#919): `tools/call`
+  with any argument is refused with the unknown-fields text, and the handler is still called with the context only.
+  The listing gains `additionalProperties: false`, so the measured tool list version changes once.
+- `renamedFields` also takes a rule `(field) => newName | undefined` (#919), e.g. for a rename by pattern across many
+  fields. `RenamedFields` is exported from `/server`.
+
+## 0.2.9
+
+- A runtime kill switch for writes (#904): the manifest switch `mcp-access.writes_enabled` (`WRITES_ENABLED_SWITCH`)
+  is read through `readSwitch` on every request. Writes need `allowWrites`, the token's write access and the switch;
+  off, write tools are not served, the `WWW-Authenticate` challenge and the default OAuth scope name only `mcp:read`,
+  the consent page offers no write tick and a decision grants read only. `isWritingEnabled(ctx)` (`/server`) answers
+  the app's side, and `AuthorizationRequest.isWriteOffered` the consent page's. Migrate: nothing; an app that does
+  not define the switch behaves as before. To use it, define it in `@softure-ai/feature-switches` (README §7
+  recommends `failMode: "closed"`, `override: "towards-fail-mode"`) and drop an app-level write switch.
+- The consent page shows where the access code goes as a row of its own (#906): `consent.redirectLabel` and the
+  host (or the whole native-scheme URI) in monospace, with the hint `consent.redirectHint` that the app name is
+  self-declared and the address is not. `ConsentForm` gains the `target` slot; `note` now styles the hint.
+  `OAuthConsentPage` takes `classNames` and `unstyled` and passes them to `ConsentForm` and `ConsentError`.
+  Migrate: `consent.returnsTo` is gone; an app that overrides it moves its text to `consent.redirectLabel`, and an
+  app that recomposed the page to show the host can mount `OAuthConsentPage` again.
+
 ## 0.2.8
 
 - The content of 0.2.7, which was never published: its release stopped at the gates (ESLint ran out of memory in

package/README.md

@@ -15,10 +15,11 @@ limit check made race-free.
   `Authorization: Bearer` token, then hands the request to a **fresh server from the app's factory**
   with `{ userId, canWrite, tokenId }`. Unknown, revoked, expired and malformed tokens all get the
   same `401 invalid_token` with a `WWW-Authenticate: Bearer` challenge. The challenge's `scope` is
-  `mcp:read mcp:write` while `allowWrites` is on and `mcp:read` otherwise, so an OAuth client asks
+  `mcp:read mcp:write` while the app allows writes and `mcp:read` otherwise, so an OAuth client asks
   for what it may get.
-- **Writes need two consents:** the app's `allowWrites` option and a token issued with write
-  access. `canWrite` is decided on every request, so turning `allowWrites` off makes every token
+- **Writes need the app and the token:** the app's `allowWrites` option, the runtime switch
+  `mcp-access.writes_enabled` when the app defines it (§7), and a token issued with write access.
+  `canWrite` is decided on every request, so turning `allowWrites` or the switch off makes every token
   read-only at once.
 - A token page for the signed-in user: the app's tool catalog, an issue form, the new token with its
   setup (a prompt for Claude Code and a `claude-cli://` link, the `claude mcp add` command, an
@@ -30,9 +31,10 @@ limit check made race-free.
   - dynamic client registration (RFC 7591, `POST /api/oauth/register`), public or confidential;
     open to anyone, or closed outside a window an ops script opens (`oauth.registration`);
   - `/oauth/authorize`: authorization code with PKCE `S256` only, on a consent page that shows the
-    app, where the code goes, the signed-in account and the access; writes need the `mcp:write`
-    scope, `allowWrites` and the person's tick. A request without `scope` gets the default scope:
-    both scopes while `allowWrites` is on, `mcp:read` otherwise;
+    app's self-declared name, where the code goes (a row of its own, in monospace: the one part a
+    client cannot fake), the signed-in account and the access; writes need the `mcp:write` scope, the
+    app allowing writes (`allowWrites` and the switch) and the person's tick. A request without `scope`
+    gets the default scope: both scopes while the app allows writes, `mcp:read` otherwise;
   - `POST /api/oauth/token`: `authorization_code` and `refresh_token`. Refresh tokens rotate on
     every use; presenting a rotated one again (`previous_refresh_token_hash`) revokes the whole
     grant, and so does reusing a code (RFC 6749 §4.1.2). `resource` (RFC 8707) must name the
@@ -40,6 +42,9 @@ limit check made race-free.
   - one grant per account and client, listed on the token page as "connected apps"; revoking it
     deletes its access tokens at once (`grant_id`, `ON DELETE CASCADE`). OAuth access tokens do not
     count against `maxTokensPerUser` and are not listed with the hand-issued ones.
+- **Tokens for the app's own HTTP routes** (`apiTokens`, off by default): personal tokens with the app's prefix and
+  scopes (`recipes:write`) for a phone Shortcut, an automation tool or a script, checked in a route handler with
+  `requireApiToken` from `@softure-ai/mcp-access/tokens`, an entry that loads no MCP SDK (§4 "Tokens for HTTP routes").
 - Tokens an app issued before adopting the module keep working through `legacyTokenPattern`.
 - Server functions for scripts and other hosts, and a health check for `GET /api/health`.
 - For the app's own server: tool result helpers with a safe error boundary and server actions as write tools
@@ -47,7 +52,9 @@ limit check made race-free.
   (`createMcpServerFactory`, `measureToolList`, `/server`), strict tool input that refuses unknown and renamed
   fields (`withStrictToolInput`, `/server`), an opt-in `get_server_info` tool that tells which build answers
   (`serverInfoTool`, `/server`), a stdio entry for local assistants (`/stdio`), a catalog parity check (`/testing`), a gate before a
-  token is issued (`issueToken`, `/next`) and the `softure-mcp prune` command for a daily cleanup (§4, §5).
+  token is issued (`issueToken`, `/next`), long operations as tools over `@softure-ai/jobs` (`startOperation`,
+  `get_operation`, `cancel_operation`, `/jobs`) or as MCP Tasks for clients that declare them (`registerOperationTasks`)
+  and the `softure-mcp prune` command for a daily cleanup (§4, §5).
 
 ## 2. Installation
 
@@ -191,7 +198,7 @@ input schema registered on the server from then on, or pass `strictToolInput: tr
 
 ```ts
 const server = withStrictToolInput(new McpServer({ name: "acme", version }), {
-  renamedFields: { notes: "note" }, // old name → new name
+  renamedFields: { notes: "note" }, // old name → new name, or a rule: (field) => newName | undefined
   coerceTextScalars: true, // default
   messages: getMcpAccessMessages(config).toolInput, // default: the English dictionary
 });
@@ -204,10 +211,16 @@ const server = withStrictToolInput(new McpServer({ name: "acme", version }), {
   `.catchall(x)`) keeps it; refinements and the object's own error messages stay.
 - **Renamed fields:** a field sent under an old name where the object accepts the new one is refused with the
   stable code `input.field_renamed` and the new name, so a session on an older tool list learns it in one call.
+  `renamedFields` is a map or a rule, e.g. `(field) => field.includes("Pln") ? field.replace("Pln", "Home") :
+  undefined` for a rename across many fields; a name the rule leaves alone is an unknown field.
 - **Text scalars:** a client on an older tool list sends a field it does not know as text, so a boolean field also
   takes the exact text `"true"`/`"false"` and a number field a JSON number written as text, converted before the
   field's own rules (`"-1"` still fails `min(0)`). Any other text is refused. The listed JSON Schema keeps `boolean`
-  and `number` and gains `additionalProperties: false`.
+  and `number`, the fields' `required` and the `default` of a scalar field, and gains `additionalProperties: false`.
+  A required `z.number().nullable()` stays required. (zod lists no `default` on an object or array that holds a
+  scalar field, since its input is transformed.)
+- **No input schema:** a tool registered without one gets the strict empty object, so `tools/call` with any argument
+  is refused; its handler is still called with the request context only.
 - The SDK validates before the handler runs, so a refused call saves nothing. A raw shape is wrapped in
   `z.object` first; a schema that is not zod passes unchanged. `toStrictToolInput(schema, options?)` gives the
   strict schema on its own.
@@ -294,6 +307,128 @@ export async function createServer({ userId, canWrite, tokenId }: McpServerIdent
 }
 ```
 
+### Long operations: start, status, cancel
+
+A tool whose work takes minutes (a render, an import) cannot hold the call open: the endpoint answers in JSON mode
+and drops mid-call notifications, a proxy may cut a long response (Cloudflare at 100 seconds), and assistants time out
+tool calls. `@softure-ai/mcp-access/jobs` turns such work into an operation on top of `@softure-ai/jobs`: the tool
+starts a job and answers an id at once, the assistant asks `get_operation` until it ends, and may stop it with
+`cancel_operation`.
+
+```ts
+import { registerOperationCancelTool, registerOperationStatusTool, startOperation } from "@softure-ai/mcp-access/jobs";
+
+export async function createServer(identity: McpServerIdentity) {
+  server.registerTool("render_video", { inputSchema: z.object({ videoId: z.string() }) }, (args) =>
+    withToolErrors(() => startOperation(ctx, identity, { queue: "video.render", payload: args, dedupKey: `video:${args.videoId}` })),
+  );
+  registerOperationStatusTool(server, { ctx, identity, readResult: (job) => findRenderUrl(db, job.id) });
+  registerOperationCancelTool(server, { ctx, identity }); // registers nothing without identity.canWrite
+}
+```
+
+- `startOperation(ctx, identity, { queue, payload, dedupKey?, statusToolName?, poll? })` enqueues the job and answers
+  `{ operationId, status: "queued", progress: null, pollAfterSeconds, message }`; the message tells the assistant to
+  call the status tool and not to start again. With a `dedupKey` (at most 150 characters), starting again while the
+  account's operation of that queue runs joins it: the answer carries its id and status.
+- `get_operation` (`registerOperationStatusTool`, read only) answers `{ operationId, status, progress,
+  pollAfterSeconds?, cancelRequested?, result?, errorCode?, message }`. `status` is `queued`, `running` (also while a
+  failed attempt waits for its retry), `succeeded`, `failed` or `cancelled`; `progress` is what the handler reports
+  with `context.reportProgress` (codes and counts only); `pollAfterSeconds` is there while the operation runs and
+  grows with its age (a quarter of its seconds, between `poll.minSeconds` 2 and `poll.maxSeconds` 30); `result` is
+  what `readResult(job)` reads from the app's tables once it succeeded (jobs stores no result); `errorCode` is the
+  failure's code (`jobs.cancelled` for a cancelled one).
+- `cancel_operation` (`registerOperationCancelTool`, a write) ends a queued operation at once and asks a running one
+  to stop (`requestJobCancel`: the handler's `signal` aborts on its next heartbeat); the answer says
+  `cancelRequested: true` until it has ended. An ended one answers "already ended" as a tool error.
+- Scoped to the account: an operation's job has origin `mcp` and the dedup key `mcp:<userId>:<key>` (a random key
+  without `dedupKey`). Another account's operation, a job that is not an operation and a malformed id all answer
+  "No operation with this id belongs to this account." No table of its own: an operation lives as long as its job
+  (`retention` of jobs).
+- `getOperation` and `cancelOperation` are the same reads as functions; the texts are under `operations` in the
+  module dictionary, and `name`/`description` rename a tool.
+
+#### As MCP Tasks
+
+A client that speaks the Tasks extension (`io.modelcontextprotocol/tasks`, protocol revision 2026-07-28) can follow an
+operation as a task instead of calling `get_operation`. It is opt-in per tool and needs two things on the same server:
+pass the tool handler's request context as `taskRequest`, and register the task handlers.
+
+```ts
+import { registerOperationTasks, startOperation } from "@softure-ai/mcp-access/jobs";
+
+server.registerTool("render_video", { inputSchema: z.object({ videoId: z.string() }) }, (args, request) =>
+  withToolErrors(() => startOperation(ctx, identity, { queue: "video.render", payload: args, taskRequest: request })),
+);
+registerOperationStatusTool(server, { ctx, identity, readResult }); // still there for every other client
+registerOperationTasks(server, { ctx, identity, readResult });
+```
+
+- Only a request whose client declared the extension in its per-request capabilities gets a task (`resultType:
+  "task"`, `status: "working"`, `ttlMs`, `pollIntervalMs`). A client that did not, including every 2025-era client,
+  gets the operation id exactly as above, so the polling tools stay the default.
+- `registerOperationTasks(server, { ctx, identity, readResult?, poll? })` declares the extension in `server/discover`
+  and answers `tasks/get`, `tasks/update` and `tasks/cancel` for the request's account:
+  - `tasks/get`: `working` while the operation is queued or running (`statusMessage` says which, or that a stop was
+    asked; `pollIntervalMs` is `pollAfterSeconds` in milliseconds); `completed` once it ended with a `result` that is
+    the `get_operation` answer as a tool result (with the app's `readResult`), marked `isError: true` when the
+    operation failed (the spec keeps the `failed` status for protocol errors); `cancelled` when it was cancelled.
+  - `tasks/cancel`: like `cancel_operation`, a write: a read-only token gets `-32600`. An operation that has ended is
+    acknowledged all the same (cancelling is cooperative in the spec).
+  - `tasks/update`: operations never ask for input, so an owned task is acknowledged.
+  - An unknown task, another account's, or one whose job is gone is `-32602` "Task not found"; an expired one `-32602`
+    "Task has expired"; a request without the declared extension `-32021`.
+- A task id is random (32 bytes, base64url) and stored in `mcp.operation_tasks` (§5) with its owner, its job and an
+  expiry: `taskTtlSeconds` on `startOperation`, a minute to thirty days, default a day. The same account starting the
+  same running operation again (same `dedupKey`) gets the same task. Progress counts stay with `get_operation`.
+
+### Confirmed calls
+
+A tool that spends money (a paid provider call) or cannot be undone follows the `--commit` rule over MCP:
+`withConfirmation` (`/server`) makes the first call estimate only, the person agrees in the chat, and only a second
+call with the same input does the work. The assistant cannot agree on its own: the token comes only from an estimate,
+is single use and bound to that exact input.
+
+```ts
+import { confirmationInput, withConfirmation } from "@softure-ai/mcp-access/server";
+
+server.registerTool(
+  "render_film",
+  { inputSchema: { scene: z.string(), seconds: z.number(), confirmation: confirmationInput } },
+  withConfirmation((args) => renderFilm(ctx, userId, args), {
+    ctx, // the module context, as for the app's queries
+    identity, // the factory's McpServerIdentity: the token is bound to its userId and tokenId
+    tool: "render_film",
+    estimate: (args) => estimateFilm(ctx, userId, args), // { total: 12, currency: "credits", ... }
+    runWithoutConfirmationWhen: (estimate) => estimate.total === 0, // everything was cached
+  }),
+);
+```
+
+- **First call** (no `confirmation`): runs `estimate(args)` only and answers
+  `{ needsConfirmation: true, estimate, confirmation, expiresAt, message }`; `message` is the fixed sentence
+  `confirmation.ask` of the dictionary, which tells the assistant to show the estimate and get the person's yes.
+  `estimate` returns an object with a finite numeric `total`; every other field reaches the assistant as it is.
+  When `runWithoutConfirmationWhen(estimate)` is true the handler runs at once instead.
+- **The token** is an HMAC-SHA256 signed with `MCP_CONFIRMATION_SECRET` (§6, or the `secret` option) over the tool
+  name, a digest of the canonical JSON of the arguments without `confirmation` (`toCanonicalJson`: keys sorted,
+  `undefined` left out), a digest of the account and the access token, the estimate's total and the expiry
+  (`ttlSeconds`, default 900).
+- **Second call** (same arguments and `confirmation`): the estimate runs again, then the checks, each refused with its
+  own code and the text of `confirmation.*` in the dictionary (an app's `hints` replace them):
+  `input.confirmation_invalid` (not signed by this secret, malformed), `input.confirmation_other_tool`,
+  `input.confirmation_other_account` (another account or access token), `input.confirmation_expired`,
+  `input.confirmation_arguments_changed`, `input.confirmation_estimate_changed` (the total changed after the yes)
+  and `input.confirmation_used`. Only when all pass is the token stored by its hash and the handler run with the
+  arguments without `confirmation`; two parallel calls with one token run once. A refused call never uses up a valid
+  token; a handler that fails after the check needs a new estimate.
+- **The record**: `onToolCall` records gain `confirmed`: `true` for a call that ran on a valid confirmation, `false`
+  for an estimate, a refusal or a call run through `runWithoutConfirmationWhen`, `null` for tools without
+  confirmation. `argumentNames` leave `confirmation` out.
+- `confirmationInput` is the field for the input schema (an optional string), so a strict server lists and accepts
+  it. Without `MCP_CONFIRMATION_SECRET` the call fails as a bug, with one log line naming the variable: it never runs
+  without asking.
+
 ### Stdio
 
 A local assistant on the machine that holds the database can run the same factory over stdio, without a token:
@@ -489,6 +624,67 @@ An app that composes its own routes from `/server` builds the context with
 resolves origins with `resolveMcpOrigins(config, request)` and passes them to the URL builders,
 whose last argument they are; `OAuthClientRow` is exported from the package root.
 
+### Tokens for HTTP routes
+
+A person who calls the app from outside the browser (an iPhone Shortcut, Make or Zapier, a script) gets a personal
+token for the app's plain HTTP routes. Declare the scopes the routes ask for, and the buckets:
+
+```ts
+// softure.config.ts
+security({ buckets: { ...AUTH_RATE_LIMIT_BUCKETS, ...MCP_RATE_LIMIT_BUCKETS, ...API_TOKEN_RATE_LIMIT_BUCKETS } }),
+mcpAccess({
+  serverName: "acme",
+  allowWrites: true,
+  apiTokens: {
+    prefix: "acme_", // default "sftapi_"; never one of the module's own sftmc* prefixes
+    scopes: [
+      { name: "recipes:read", access: "read", description: { en: "Reads your recipes." } },
+      { name: "recipes:write", access: "write", description: { en: "Adds and changes recipes." } },
+    ],
+    // Shown once with a new token; {token} and {appOrigin} are filled in.
+    examples: [{ title: { en: "curl" }, text: { en: "curl -H 'Authorization: Bearer {token}' {appOrigin}/api/recipes" } }],
+  },
+}),
+```
+
+```ts
+// app/api/recipes/route.ts
+import { getSoftureConfig } from "@softure-ai/core/next";
+import { apiTokenErrorResponse, createMcpAccessContext, requireApiToken } from "@softure-ai/mcp-access/tokens";
+
+export async function POST(request: Request): Promise<Response> {
+  const ctx = await createMcpAccessContext(getSoftureConfig());
+  const caller = await requireApiToken(ctx, request, { scopes: ["recipes:write"] });
+  if (!caller.ok) return apiTokenErrorResponse(caller);
+  // caller.value: { userId, tokenId, scopes }; scope every query to userId.
+  return Response.json(await addRecipe(caller.value.userId, await request.json()));
+}
+```
+
+- **The two kinds stay apart.** An API token (`kind = 'api'`, the app's prefix) never opens `POST /api/mcp`, and an
+  MCP token (`sftmcp_`, `mcp:read`/`mcp:write`) never passes `requireApiToken`. Both share the table, the hashing,
+  `tokenLifetimeDays`, `maxTokensPerUser` (one count for both), the revoke action, privacy and prune.
+- **Order of the check:** the client address is counted in `api` before any lookup, the `Authorization: Bearer`
+  token is verified (expiry in the query, last use recorded), the token is counted in `api-token`, then the scopes.
+- **Refusals are values** for `apiTokenErrorResponse`: `400 client_unidentified`; `401 api_token_missing` and
+  `api_token_invalid` (unknown, revoked, expired, an MCP token) with `WWW-Authenticate: Bearer`; `403
+  api_scope_missing` with `missingScopes` and `error="insufficient_scope"`; `403 api_writes_disabled` when the token
+  holds the write scope but writing is off; `429 rate_limited` with `Retry-After`; `503 api_unavailable` (logged)
+  when the count or the lookup fails. A scope the app does not declare, or missing buckets, throws: a setup bug.
+- **Writes:** a `write` scope is granted at issue only with `allowWrites`, and counts on a request only while
+  writing is enabled (`allowWrites` and the `mcp-access.writes_enabled` switch, §7).
+- **The token page** lists the app's scopes and offers a second form, "New token for other apps", that posts to the
+  same issue action with `kind=api` and a `scope:<name>` checkbox per offered scope. The new token is shown once
+  with its header and the app's `examples`; the action answers `{ status: "api-ok", issued }`
+  (`IssuedApiTokenView`), so an app reading `status === "ok"` for MCP tokens is unchanged. The list names each
+  token's kind ("AI assistant", "Other apps") and an API token's scopes. A `beforeIssue` gate gets `kind` and
+  `scopes`, with `canWrite` true when a write scope is asked.
+- **Without MCP:** an app that has no MCP server enables `mcpAccess` with `apiTokens`, mounts only the token page
+  and its routes, and imports `@softure-ai/mcp-access/tokens` (which loads no `@modelcontextprotocol/*` module). The
+  npm peer list still names the SDK.
+- Server functions: `issueApiToken`, `verifyApiToken`, `requireApiToken`, `apiTokenErrorResponse`,
+  `isApiTokenShape`, plus `listAccessTokens`, `revokeAccessToken`, `pruneAccessTokens` (`/tokens`, also in `/server`).
+
 ### Closed registration
 
 Registration is public by default: claude.ai and ChatGPT register a client before anyone signs in, and a client
@@ -544,9 +740,25 @@ expired (with their access tokens) and clients registered over a day ago that ho
 (`id = 1`) with `opened_at` and `open_until` (`open_until > opened_at`), the window of "Closed registration" (§4). It
 holds no personal data.
 
+`migrations/0004_create_used_confirmations.sql` creates `mcp.used_confirmations`: the sha256 of each confirmation
+token that has been used (`token_hash`, the primary key), `used_at` and the token's `expires_at`, which makes a
+confirmation single use ("Confirmed calls", §4). It holds no personal data; `pruneUsedConfirmations(ctx)` deletes the
+rows past `expires_at`.
+
+`migrations/0005_add_api_tokens.sql` adds `access_tokens.kind` (`mcp` or `api`, default `mcp`) and
+`access_tokens.scopes` (`text[]`, default empty), with one check: an `mcp` row has no scopes, an `api` row has 1 to
+32 scopes and no grant. Existing rows become MCP tokens through the defaults. An API token's `token_hash` is the
+sha256 of its random part after the prefix (the prefix is checked by shape before any lookup). Rollback: in the migration header.
+
+`migrations/0006_create_operation_tasks.sql` creates `mcp.operation_tasks` for long operations as MCP Tasks (§4):
+`task_id` (random, 43 base64url characters, the primary key), `user_id` (`REFERENCES auth.users ON DELETE CASCADE`),
+`job_id` (the operation's job in `@softure-ai/jobs`, no foreign key since jobs is optional), `created_at` and
+`expires_at`, unique per account and job. `pruneOperationTasks(ctx)` (`/server`) deletes the rows past `expires_at`;
+the jobs themselves follow the `retention` of jobs.
+
 ### Scheduled pruning
 
-`pruneMcpAccess(ctx)` (`/server`) runs both prunes and counts what each removed. The `softure-mcp prune` command
+`pruneMcpAccess(ctx)` (`/server`) runs the prunes of tokens, OAuth records, used confirmations and operation tasks and counts what each removed. The `softure-mcp prune` command
 runs it with the app's config (loaded like `softure migrate`, or from an app script through `runMcpAccessCli` from
 `/cli`) and prints one line. Run it daily, e.g. as a `maintain` hook of `@softure-ai/deploy`:
 
@@ -591,16 +803,49 @@ migrations after the baseline.
 
 ## 6. Environment variables
 
-None of its own. The endpoint URL comes from `appOrigin` in `softure.config.ts`.
+The endpoint URL comes from `appOrigin` in `softure.config.ts`.
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `MCP_CONFIRMATION_SECRET` | only for confirmed calls | Signs and verifies the tokens of `withConfirmation` (§4), at least 32 characters, read on every call. Changing it voids the tokens in flight (the person is asked again). |
 
 ## 7. Switches
 
-None. `allowWrites` is configuration, not a runtime switch: changing who may write is a deploy.
+`mcp-access.writes_enabled` (`WRITES_ENABLED_SWITCH`): a kill switch for writes, read through `readSwitch` of
+`@softure-ai/core` on every MCP request, consent page and decision. `allowWrites` stays the configuration (no
+writes at all without it); the switch takes writes away at once, without a deploy, when a token or a connected
+assistant is suspected of misuse. Off, write tools are not served (the factory gets `canWrite: false`), the
+challenge and the default OAuth scope name only `mcp:read`, and the consent page offers no write tick. Stored
+tokens and grants keep their write access, so turning the switch back on restores it without new consent.
+
+The app defines it in `@softure-ai/feature-switches`. Recommended: on by default, `failMode: "closed"` and
+`override: "towards-fail-mode"`, so the environment variable `SOFTURE_SWITCH_MCP_ACCESS_WRITES_ENABLED=false`
+can pull writes off but never push them back on:
+
+```ts
+featureSwitches({
+  switches: [
+    {
+      name: "mcp-access.writes_enabled",
+      label: { en: "Assistant writes" },
+      description: { en: "Lets AI assistants with write access change data. Off, every assistant reads only." },
+      default: true,
+      failMode: "closed",
+      override: "towards-fail-mode",
+    },
+  ],
+});
+```
+
+An app that does not define it (or has no feature-switches) keeps `allowWrites` alone. A switch read that throws
+counts as off and is logged by the switch's name. The stdio entry reads the switch once, when it starts.
 
 ## 8. Appearance
 
 `TokenManager` slots: `root`, `section`, `heading`, `text`, `list`, `item`, `itemHeader`, `badge`,
-`details`, `snippet`, `code`; `unstyled` renders structure only. Styling comes from
+`details`, `snippet`, `code`; `unstyled` renders structure only. `ConsentForm` and `ConsentError` slots: `root`,
+`details`, `term`, `value`, `target` (where the code goes), `note` (the hint under it), `actions`, `text`, `link`;
+`OAuthConsentPage` takes `classNames` and `unstyled` and passes them to both. Styling comes from
 `@softure-ai/ui` classes on the `--sft-*` tokens; the module ships no CSS of its own.
 
 ## 9. Copy
@@ -632,11 +877,12 @@ The MCP server factory passed to `createMcpRoute` (and to `serveMcpStdio`) and t
 The rows hold no personal data beyond the owner's id and the token names. The module contributes
 to `@softure-ai/privacy` (`privacy` flags on):
 
-- **Export** (`exportMcpAccessUserData`): `accessTokens`, each hand-issued token's name, write
-  flag and created, expiry and last-use dates, and `connectedApps`, each grant's client name, write
+- **Export** (`exportMcpAccessUserData`): `accessTokens`, each hand-issued token's name, kind
+  (`mcp` or `api`), scopes, write flag and created, expiry and last-use dates, and `connectedApps`, each grant's client name, write
   flag, created and last-use dates. Never a hash.
-- **Deletion** (`deleteMcpAccessUserData`): the user's authorization codes, grants and tokens,
-  before auth deletes the account (the foreign keys' cascade would remove them too). Registered
+- **Deletion** (`deleteMcpAccessUserData`): the user's authorization codes, grants, tokens and MCP tasks,
+  before auth deletes the account (the foreign keys' cascade would remove them too). Tasks hold a job id and dates
+  only, so the export leaves them out. Registered
   clients hold no personal data and are pruned when unused.
 
 ## 12. Limitations / known gaps
@@ -646,5 +892,10 @@ to `@softure-ai/privacy` (`privacy` flags on):
   app that wants `jwks_uri` adds it through `oauth.metadata` and serves the empty set itself).
 - Only `S256` PKCE and the `authorization_code` and `refresh_token` grants.
 - Write access is per token, not per tool; finer scopes would be a new option.
-- The rate limit is per client address, not per token.
-- `responseMode: "json"` drops mid-call notifications; a streaming tool would need a different mode.
+- The MCP endpoint's rate limit is per client address, not per token (API tokens are counted per token as well).
+- One API token kind per app (one prefix); the `kind` column takes more kinds without a migration of the rows.
+- `responseMode: "json"` drops mid-call notifications; a streaming tool would need a different mode. Long work is an
+  operation instead (start, `get_operation`, `cancel_operation`).
+- MCP Tasks follow the extension of revision 2026-07-28 only; the 2025-11-25 core Tasks (task-augmented requests,
+  `tasks/result`, `tasks/list`) are not served, and those clients use the polling tools. Tasks carry no input
+  requests and no `notifications/tasks`.

package/dist/cli/run.d.ts

@@ -18,7 +18,7 @@ export interface RunMcpAccessCliOptions {
 export declare const EXIT_OK = 0;
 export declare const EXIT_FAILED = 1;
 export declare const EXIT_USAGE = 2;
-export declare const MCP_ACCESS_USAGE = "Usage:\n  softure-mcp prune    deletes expired access tokens, authorization codes, grants and abandoned clients";
+export declare const MCP_ACCESS_USAGE = "Usage:\n  softure-mcp prune    deletes expired access tokens, authorization codes, grants, abandoned clients and used confirmations";
 /** Runs one command and answers its exit code. */
 export declare function runMcpAccessCli(options: RunMcpAccessCliOptions): Promise<number>;
 //# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAQA,OAAO,EAA8B,KAAK,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC1H,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAG3E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACvF;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,eAAO,MAAM,gBAAgB,oHAC2E,CAAC;AAOzG,kDAAkD;AAClD,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAatF"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAQA,OAAO,EAA8B,KAAK,KAAK,EAAE,KAAK,aAAa,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC1H,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAG3E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,sBAAsB;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;CACvF;AAED,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,eAAO,MAAM,gBAAgB,wIAC+F,CAAC;AAO7H,kDAAkD;AAClD,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAatF"}

package/dist/cli/run.js

@@ -13,7 +13,7 @@ export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
 export const EXIT_USAGE = 2;
 export const MCP_ACCESS_USAGE = `Usage:
-  softure-mcp prune    deletes expired access tokens, authorization codes, grants and abandoned clients`;
+  softure-mcp prune    deletes expired access tokens, authorization codes, grants, abandoned clients and used confirmations`;
 const consoleOutput = {
     log: (line) => console.log(line),
     error: (line) => console.error(line),
@@ -43,7 +43,7 @@ async function prune(options, output) {
     try {
         opened = await (options.openDatabase ?? ((settings) => openCommandDatabase(settings, { max: 1 })))(database);
         const removed = await pruneMcpAccess({ db: opened.handle.db, clock: options.clock ?? systemClock, config: options.config });
-        output.log(`softure-mcp prune: removed ${String(removed.accessTokens)} access tokens, ${String(removed.codes)} authorization codes, ${String(removed.grants)} grants, ${String(removed.clients)} clients`);
+        output.log(`softure-mcp prune: removed ${String(removed.accessTokens)} access tokens, ${String(removed.codes)} authorization codes, ${String(removed.grants)} grants, ${String(removed.clients)} clients, ${String(removed.usedConfirmations)} used confirmations, ${String(removed.operationTasks)} operation tasks`);
         return EXIT_OK;
     }
     catch (error) {

package/dist/cli/run.js.map

@@ -1 +1 @@
-{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,mGAAmG;AACnG,2FAA2F;AAC3F,EAAE;AACF,sBAAsB;AACtB,kEAAkE;AAClE,4CAA4C;AAC5C,uFAAuF;AACvF,OAAO,EAAE,aAAa,EAAE,WAAW,EAA8D,MAAM,kBAAkB,CAAC;AAC1H,OAAO,EAAE,mBAAmB,EAAwB,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAmBpD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC;AACzB,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC;AAC7B,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC;AAE5B,MAAM,CAAC,MAAM,gBAAgB,GAAG;4HAC4F,CAAC;AAE7H,MAAM,aAAa,GAAc;IAC/B,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;IAChC,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;CACrC,CAAC;AAEF,kDAAkD;AAClD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAA+B;IACnE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,CAAC;IAC/C,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IACxC,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACxE,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAC7B,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,OAAO,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,2CAA2C,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,iCAAiC,OAAO,GAAG,CAAC,CAAC;QAC9I,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC/B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,KAAK,UAAU,KAAK,CAAC,OAA+B,EAAE,MAAiB;IACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,QAAQ,IAAI,IAAI,CAAC;IAClD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtD,MAAM,CAAC,KAAK,CAAC,mFAAmF,CAAC,CAAC;QAClG,OAAO,WAAW,CAAC;IACrB,CAAC;IACD,IAAI,MAAmC,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,mBAAmB,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC7G,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5H,MAAM,CAAC,GAAG,CACR,8BAA8B,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,mBAAmB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,yBAAyB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,wBAAwB,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,kBAAkB,CAC3S,CAAC;QACF,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,iFAAiF;QACjF,MAAM,CAAC,KAAK,CAAC,8BAA8B,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnE,OAAO,WAAW,CAAC;IACrB,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,EAAE,KAAK,EAAE,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/contract.d.ts

@@ -1,5 +1,24 @@
 import type { CoreErrorCode, Err } from "@softure-ai/core";
-export type McpAccessErrorCode = "mcp-access.name_required" | "mcp-access.name_too_long" | "mcp-access.token_limit_reached" | "mcp-access.token_not_found" | "mcp-access.grant_not_found";
+export type McpAccessErrorCode = "mcp-access.name_required" | "mcp-access.name_too_long" | "mcp-access.token_limit_reached" | "mcp-access.token_not_found" | "mcp-access.grant_not_found" | "mcp-access.api_disabled" | "mcp-access.scope_required" | "mcp-access.scope_unknown";
+/** Which door a token opens: the MCP endpoint, or the app's HTTP routes through `requireApiToken`. */
+export type AccessTokenKind = "mcp" | "api";
+/** Why `requireApiToken` refused a request; `apiTokenErrorResponse` turns each into its HTTP answer. */
+export type ApiTokenErrorCode = "mcp-access.api_token_missing" | "mcp-access.api_token_invalid" | "mcp-access.api_scope_missing" | "mcp-access.api_writes_disabled" | "mcp-access.api_unavailable" | "security.client_unidentified" | "security.rate_limited";
+/** A refusal of `requireApiToken`. */
+export type ApiTokenRefusal = Err<Exclude<ApiTokenErrorCode, "security.rate_limited" | "mcp-access.api_scope_missing" | "mcp-access.api_writes_disabled">> | (Err<"mcp-access.api_scope_missing" | "mcp-access.api_writes_disabled"> & {
+    readonly missingScopes: readonly string[];
+}) | (Err<"security.rate_limited"> & {
+    readonly retryAfterSeconds: number;
+});
+/** Who called a route with a valid API token. */
+export interface ApiTokenIdentity {
+    /** The auth user id of the token's owner: scope every query of the route to it. */
+    readonly userId: string;
+    /** The token's id, for the route's own logs. Never the token. */
+    readonly tokenId: string;
+    /** The token's effective scopes: write scopes only while the app allows writes. */
+    readonly scopes: readonly string[];
+}
 /** What an app's `beforeIssue` gate may answer instead of letting a token be issued. */
 export type McpIssueRefusalCode = "mcp-access.issue_refused" | "mcp-access.write_refused";
 /**
@@ -24,6 +43,9 @@ export interface McpServerIdentity {
 export interface AccessTokenView {
     readonly id: string;
     readonly name: string;
+    readonly kind: AccessTokenKind;
+    /** The app scopes of an API token; empty for an MCP token. */
+    readonly scopes: readonly string[];
     /** Issued with write access (it still writes only while the app allows writes). */
     readonly canWrite: boolean;
     readonly createdAt: Date;
@@ -59,7 +81,7 @@ export interface McpClientSetup {
     /** The `Authorization` header value, for clients with a header field. */
     readonly authorizationHeader: string;
 }
-/** A token right after it was issued: the only moment its plaintext exists outside the client. */
+/** An MCP token right after it was issued: the only moment its plaintext exists outside the client. */
 export interface IssuedToken {
     readonly id: string;
     readonly name: string;
@@ -70,6 +92,25 @@ export interface IssuedToken {
     readonly expiresAt: string;
     readonly setup: McpClientSetup;
 }
+/** A snippet the app gave for API tokens (`apiTokens.examples`), filled in with the new token. */
+export interface ApiTokenExample {
+    readonly title: string;
+    readonly text: string;
+}
+/** An API token right after it was issued, for the one-time reveal. */
+export interface IssuedApiTokenView {
+    readonly id: string;
+    readonly name: string;
+    /** The scopes granted (write scopes only with `allowWrites`). */
+    readonly scopes: readonly string[];
+    readonly expiresText: string;
+    readonly expiresAt: string;
+    /** The plaintext, shown once. */
+    readonly token: string;
+    /** `Bearer <token>`. */
+    readonly authorizationHeader: string;
+    readonly examples: readonly ApiTokenExample[];
+}
 /** What the issue action returns to its form (`useActionState`). */
 export type IssueTokenFormState = {
     readonly status: "idle";
@@ -77,6 +118,11 @@ export type IssueTokenFormState = {
     readonly status: "ok";
     readonly issued: IssuedToken;
 }
+/** An API token was issued (`kind=api` in the form): its one-time reveal. */
+ | {
+    readonly status: "api-ok";
+    readonly issued: IssuedApiTokenView;
+}
 /** `message`: the app's own refusal text from the `beforeIssue` gate, shown instead of the code's copy. */
  | {
     readonly status: "error";

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}