askell-mcp 0.2.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 [MCP](https://modelcontextprotocol.io) server for the [Askell](https://askell.is) payment and subscription API.
 
-Connect it to Cursor, Claude Desktop, or any MCP client to discover Askell endpoints, inspect customers/contracts/billing, and call the API — with confirmation before mutating requests.
+Connect it to Cursor, Claude Desktop, or any MCP client to discover Askell endpoints, inspect customers/contracts/billing, and call the API. Reads and writes are separate tools so clients can show their own approval UI on mutations.
 
 ## Requirements
 
@@ -62,17 +62,26 @@ Restart the client after saving.
 | `ASKELL_PUBLIC_API_KEY`            | no       | —                       | Public key for a few checkout/payment endpoints |
 | `ASKELL_API_URL`                   | no       | `https://askell.is/api` | API base URL (_or_ `ASKELL_API_BASE_URL`)       |
 | `ASKELL_RESPONSE_MAX_BYTES`        | no       | `64000`                 | Max response size returned to the model         |
-| `ASKELL_REQUIRE_MUTATION_APPROVAL` | no       | `true`                  | Confirm before POST/PUT/PATCH/DELETE            |
+| `ASKELL_MUTATION_GATE`             | no       | `auto`                  | `auto` / `elicit` / `off` — see below           |
+| `ASKELL_REQUIRE_MUTATION_APPROVAL` | no       | —                       | Deprecated alias: `true`→`elicit`, `false`→`off` |
 
 Askell has **no separate sandbox host** — production and test traffic use the same URL. Use the **Áskell Test Gateway** acquirer in your dashboard for safe payment testing. See [Askell getting started](https://docs.askell.is/en/getting_started/index.html).
 
+`ASKELL_MUTATION_GATE`:
+
+- **`auto` (default)** — confirmation form only if *this request's* `_meta` envelope declared form elicitation (MCP 2026-07-28). 2025-era clients (Cursor, most hosts) do not send that envelope, so the mutation runs and their own “allow this tool” UI is the gate.
+- **`elicit`** — always return an elicitation form. The SDK refuses the call if the client cannot fulfil it (2026 envelope / 2025 initialize via the legacy shim).
+- **`off`** — never ask (eval / trusted automation).
+
+If both `ASKELL_MUTATION_GATE` and `ASKELL_REQUIRE_MUTATION_APPROVAL` are set, `ASKELL_MUTATION_GATE` wins.
+
 ## What you can do
 
 Typical agent workflow:
 
 1. **Discover** — `askell_list_operations` / `askell_describe_operation` (from bundled OpenAPI v1 + v2)
 2. **Support tasks** — customer/contract/billing helpers below
-3. **Anything else** — `askell_call` for a raw endpoint (mutations ask for approval when enabled)
+3. **Anything else** — `askell_call` for GET/HEAD, `askell_mutate` for POST/PUT/PATCH/DELETE
 
 ### Tools
 
@@ -80,7 +89,8 @@ Typical agent workflow:
 | --------------------------- | ---------------------------------------- |
 | `askell_list_operations`    | Search bundled OpenAPI operations        |
 | `askell_describe_operation` | Params and body schema for one operation |
-| `askell_call`               | Call any v1/v2 endpoint                  |
+| `askell_call`               | GET/HEAD any v1/v2 endpoint              |
+| `askell_mutate`             | POST/PUT/PATCH/DELETE any v1/v2 endpoint |
 | `askell_paginate_all`       | Follow paginated list endpoints          |
 | `askell_customer_overview`  | v1 customer + subscriptions              |
 | `askell_contract_overview`  | v2 subscription contract + billing runs  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",

package/src/config.ts

@@ -1,9 +1,31 @@
 import * as z from 'zod';
 
+export const MUTATION_GATES = ['auto', 'elicit', 'off'] as const;
+export type MutationGate = (typeof MUTATION_GATES)[number];
+
 const httpUrl = z
   .url({ protocol: /^https?$/ })
   .describe('Askell API base URL (default production host)');
 
+const mutationGateAliases = z
+  .enum(['true', 'false', 'on', 'yes', 'no', '1', '0'])
+  .transform((value): MutationGate => {
+    return value === 'true' || value === 'on' || value === 'yes' || value === '1'
+      ? 'elicit'
+      : 'off';
+  });
+
+export const MutationGateSchema = z
+  .union([
+    z.enum(MUTATION_GATES),
+    z.boolean().transform((value): MutationGate => (value ? 'elicit' : 'off')),
+    mutationGateAliases,
+  ])
+  .default('auto')
+  .describe(
+    'Mutation confirmation: auto (elicit if client declared it), elicit (require form), off (never)',
+  );
+
 export const ConfigSchema = z.object({
   apiBaseUrl: httpUrl.default('https://askell.is/api'),
   secretApiKey: z.string().min(1).describe('Secret (private) API key'),
@@ -18,10 +40,7 @@ export const ConfigSchema = z.object({
     .positive()
     .default(64_000)
     .describe('Max response body size returned to the model'),
-  requireMutationApproval: z
-    .union([z.boolean(), z.stringbool()])
-    .default(true)
-    .describe('Require operator confirmation before mutating requests'),
+  mutationGate: MutationGateSchema,
 });
 
 export type AppConfig = z.infer<typeof ConfigSchema>;
@@ -58,7 +77,9 @@ function loadConfigFromEnv(): unknown {
 
   const apiBaseUrl = env.ASKELL_API_URL ?? env.ASKELL_API_BASE_URL;
   const responseMaxBytes = env.ASKELL_RESPONSE_MAX_BYTES;
-  const requireMutationApproval = env.ASKELL_REQUIRE_MUTATION_APPROVAL;
+  const mutationGateRaw =
+    env.ASKELL_MUTATION_GATE ?? env.ASKELL_REQUIRE_MUTATION_APPROVAL;
+  const mutationGate = mutationGateRaw?.trim().toLowerCase() || undefined;
 
   return {
     ...(apiBaseUrl ? { apiBaseUrl } : {}),
@@ -67,9 +88,7 @@ function loadConfigFromEnv(): unknown {
       ? { publicApiKey: env.ASKELL_PUBLIC_API_KEY }
       : {}),
     ...(responseMaxBytes ? { responseMaxBytes } : {}),
-    ...(requireMutationApproval !== undefined
-      ? { requireMutationApproval }
-      : {}),
+    ...(mutationGate !== undefined ? { mutationGate } : {}),
   };
 }
 

package/src/resources/register.ts

@@ -4,34 +4,60 @@ import { getBundledSpec } from '../openapi/registry.ts';
 
 const WEBHOOK_EVENTS_DOC = `# Askell webhook events (reference)
 
-Askell sends signed webhook calls to your configured endpoints.
+Askell POSTs signed JSON to each URL you register. Verify \`Hook-HMAC\` before parsing.
 
 Headers:
-- Hook-HMAC: base64 HMAC-SHA512 of the raw body
-- Hook-Event: event type identifier
-- Hook-API-Version: v1 for legacy plan/subscription webhooks, v2 for subscription contract webhooks
-
-Event families:
-- subscription.* (legacy v1): subscription.created, subscription.changed, subscription.renewed
-- subscription_contract.* (v2): subscription_contract.created, subscription_contract.changed,
-  subscription_contract.renewed, subscription_contract.migrated (legacy subscription migrated to a
-  V2 contract; payload includes legacy_subscription_ids and migration_effective_at)
-- billing_run.* (v2): billing_run.created, billing_run.changed, billing_run.succeeded,
-  billing_run.failed, billing_run.retry
-- customer.*: customer.created, customer.changed
-- payment.*: payment.created, payment.changed, payment.retry
-- checkout.*: checkout.created, checkout.changed
-
-Notes:
-- During migration to V2, legacy subscription.* aliases are NOT sent for the new contract (event data
-  is based on SubscriptionContract, not Subscription), and subscription.canceled is not sent solely
-  because billing moved to a V2 contract.
-
-Webhook management is available via v1 API:
-- GET/POST /webhooks/
-- GET/PATCH/DELETE /webhooks/{id}/
-
-This MCP server exposes webhook management through askell_call and askell_list_webhooks.
+- Hook-HMAC: base64 HMAC-SHA512 of the **raw body** (secret = \`hmac_secret\` from webhook create)
+- Hook-Event: event type (\`subscription.renewed\`, \`payment.changed\`, or a family wildcard \`subscription.*\`)
+- Hook-API-Version: \`v1\` for plan/subscription/customer/payment/checkout, \`v2\` for subscription_contract / billing_run
+
+## Body shape (OpenAPI is wrong here)
+
+JSON body **is the event object**. It is **not** \`{ event, data }\`.
+
+Ignore \`POST /your-webhook-url/\` in the bundled v1 spec — its requestBody (\`SubscriptionMultiLite\`: \`{ customer, subscriptions[] }\`) does not match live webhooks.
+
+Rare historical payloads used \`{ event, data, ref?, sender? }\`. If both \`event\` and \`data\` are objects, use \`data\`.
+
+## Registering endpoints (v1 management API)
+
+- GET/POST \`/webhooks/\` · GET/PUT/PATCH/DELETE \`/webhooks/{id}/\` (secret key)
+- Create body: \`{ url, event }\` (\`event\` may be a specific type or a family wildcard like \`payment.*\`)
+- Create/get response includes \`hmac_secret\` (store it; Askell will not show it again in a useful way if you lose it) and \`hmac_digest\` (typically \`SHA512\`)
+
+Tools: \`askell_list_webhooks\`, \`askell_call\` (GET), \`askell_mutate\` (POST/PUT/PATCH/DELETE).
+
+## Event families and payload fields
+
+Live REST \`Subscription\` objects have extra fields the OpenAPI schema omits. Webhook bodies differ slightly from GET \`/subscriptions/\` (notably \`last_billing_log\` vs \`billing_logs[]\`).
+
+### subscription.* (v1)
+\`subscription.created\`, \`subscription.changed\`, \`subscription.renewed\`
+
+\`id\`, \`plan\` (no \`payment_processor\` / membership-card / wallet-pass fields), \`customer\` (numeric id), \`customer_reference\`, \`trial_end\`, \`start_date\`, \`ended_at\`, \`reference\`, \`active\`, \`meta\` (JSON **string**, often \`"{}"\`), \`description\`, \`active_until\`, \`is_on_trial\`, \`token\`, \`is_failing\`, \`last_billing_log\` (single object or null — not \`billing_logs[]\`), \`delivery_address\`, \`amount\`. Live cancel/change events also send \`cancelled\`, \`cancel_date\`, \`has_payment_plan\`, \`payment_plan_info\`.
+
+V2 migration: \`subscription.*\` is **not** aliased onto the new contract (payload is \`SubscriptionContract\`). \`subscription.canceled\` is not sent merely because billing moved to a V2 contract.
+
+### subscription_contract.* (v2)
+\`created\`, \`changed\`, \`renewed\`, \`migrated\`
+
+\`id\`, \`customer\`, \`state\`, \`billing_anchor_at\`, \`next_billing_at\`, \`cancel_at\`, \`cancel_at_period_end\`, \`canceled_at\`, \`ended_at\`, \`currency\`, \`recurring\`, \`legacy_subscription\`, \`legacy_subscription_ids\`, \`migration_effective_at\`, \`billing_managed_by\`, \`created_at\`, \`updated_at\`.
+
+### billing_run.* (v2)
+\`created\`, \`changed\`, \`succeeded\`, \`failed\`, \`retry\`
+
+\`id\`, \`contract\`, \`period_start_at\`, \`period_end_at\`, \`state\`, \`currency\`, \`subtotal_amount\`, \`tax_amount\`, \`total_amount\`, \`attempt_count\`, \`max_attempts\`, \`next_retry_at\`, \`last_attempt_at\`, \`transaction\`, \`created_at\`, \`updated_at\`.
+
+### customer.* (v1)
+\`created\`, \`changed\` — same shape as GET \`/customers/{ref}/\` (\`id\`, names, \`email\`, \`phone\`, \`customer_reference\`, address fields, \`payment_method[]\`).
+
+### payment.* (v1)
+\`created\`, \`changed\`, \`retry\`
+
+\`uuid\`, \`amount\`, \`currency\`, \`description\`, \`reference\`, \`state\` (\`pending\` | \`settled\` | \`failed\` | \`retrying\`), \`created_at\`, \`updated_at\`, \`transactions[]\`.
+
+### checkout.* (v1)
+\`created\`, \`changed\` — \`token\`, \`checkout_url\`, \`status\`.
 `;
 
 export function registerResources(server: McpServer): void {
@@ -79,7 +105,7 @@ export function registerResources(server: McpServer): void {
     'askell://docs/webhook-events',
     {
       title: 'Askell webhook events',
-      description: 'Webhook event types and management overview',
+      description: 'Inbound webhook events, payload shapes, HMAC, and /webhooks/ management',
       mimeType: 'text/markdown',
     },
     async () => ({

package/src/server.ts

@@ -4,7 +4,7 @@ import { AskellClient } from './client/askell-client.ts';
 import type { AppConfig } from './config.ts';
 import { registerResources } from './resources/register.ts';
 import { registerAnalysisTools } from './tools/analysis.ts';
-import { registerCallTool } from './tools/call.ts';
+import { registerCallTools } from './tools/call.ts';
 import { registerDiscoveryTools } from './tools/discovery.ts';
 
 const SERVER_INSTRUCTIONS = `Askell MCP server for payment and subscription operations.
@@ -12,7 +12,7 @@ const SERVER_INSTRUCTIONS = `Askell MCP server for payment and subscription oper
 Workflow:
 1. Use askell_list_operations and askell_describe_operation to discover endpoints, parameters, and auth requirements.
 2. Prefer analysis tools (askell_customer_overview, askell_contract_overview, askell_billing_run_triage, askell_paginate_all, askell_list_webhooks) for common support tasks.
-3. Use askell_call only when no dedicated tool covers the request.
+3. Use askell_call (GET/HEAD) or askell_mutate (POST/PUT/PATCH/DELETE) when no dedicated tool covers the request.
 
 API models:
 - v1 (legacy): PlanVariant + Subscription at paths like /subscriptions/, /customers/. Still supported for existing integrations.
@@ -40,18 +40,19 @@ Auth:
 - Only temporary payment method and checkout status endpoints use the public key.
 
 Safety:
-- Mutating askell_call requests require operator approval when requireMutationApproval is enabled.
+- Writes go through askell_mutate (destructiveHint). Reads go through askell_call (readOnlyHint).
+- mutationGate=auto (default): confirmation form only if this request's envelope declared form elicitation; otherwise the client's own tool-allow UI is the gate. elicit always returns a form (SDK refuses if the client cannot fulfil it). off never asks.
 - Large list responses are compacted (index of id/dates/plan/customer) to fit responseMaxBytes before dropping rows; check meta.truncatedByMaxBytes, meta.compacted, and meta.compactedMode.
 
 Resources:
 - askell://spec/v1 and askell://spec/v2 — bundled OpenAPI
-- askell://docs/webhook-events — webhook event types including V2 subscription_contract.* and billing_run.*`;
+- askell://docs/webhook-events — inbound webhook payloads (ignore OpenAPI /your-webhook-url/), HMAC-SHA512, /webhooks/ hmac_secret`;
 
 export function createServer(config: AppConfig): McpServer {
   const server = new McpServer(
     {
       name: 'askell-mcp',
-      version: '0.1.0',
+      version: '0.3.0',
     },
     {
       instructions: SERVER_INSTRUCTIONS,
@@ -61,7 +62,7 @@ export function createServer(config: AppConfig): McpServer {
   const client = new AskellClient(config);
 
   registerDiscoveryTools(server);
-  registerCallTool(server, client, config);
+  registerCallTools(server, client, config);
   registerAnalysisTools(server, client);
   registerResources(server);
 

package/src/tools/call.ts

@@ -1,6 +1,7 @@
 import {
   acceptedContent,
   inputRequired,
+  inputResponse,
   type CallToolResult,
   type InputRequiredResult,
   type McpServer,
@@ -9,18 +10,19 @@ import * as z from 'zod';
 
 import { AskellClient, type AskellRequest } from '../client/askell-client.ts';
 import { normalizeApiPath } from '../client/paths.ts';
-import { isMutatingMethod } from '../client/response-formatter.ts';
 import type { AppConfig } from '../config.ts';
 import { operationRegistry } from '../openapi/registry.ts';
+import {
+  clientSupportsFormElicitation,
+  decideMutationGate,
+  readClientCapabilities,
+} from './mutation-gate.ts';
 
 const confirmationSchema = z.object({
   confirm: z.boolean().meta({ title: 'Confirm mutating Askell API request' }),
 });
 
-const callInputSchema = z.object({
-  method: z
-    .enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'])
-    .describe('HTTP method'),
+const sharedCallFields = {
   path: z
     .string()
     .describe('API path relative to apiBaseUrl, e.g. /v2/subscription-contracts/'),
@@ -33,11 +35,34 @@ const callInputSchema = z.object({
     .enum(['secret', 'public'])
     .default('secret')
     .describe('Which configured API key to use'),
+};
+
+const callInputSchema = z.object({
+  method: z.enum(['GET', 'HEAD']).describe('HTTP method (read-only)'),
+  ...sharedCallFields,
 });
 
-function buildApprovalMessage(input: z.infer<typeof callInputSchema>): string {
+const mutateInputSchema = z.object({
+  method: z
+    .enum(['POST', 'PUT', 'PATCH', 'DELETE'])
+    .describe('HTTP method (mutating)'),
+  ...sharedCallFields,
+});
+
+type CallInput = z.infer<typeof callInputSchema>;
+type MutateInput = z.infer<typeof mutateInputSchema>;
+
+type ToolCtx = {
+  mcpReq: {
+    signal: AbortSignal;
+    envelope?: unknown;
+    inputResponses?: Record<string, unknown>;
+  };
+};
+
+function buildApprovalMessage(input: MutateInput): string {
   const lines = [
-    `Approve this Askell API request?`,
+    'Approve this Askell API request?',
     '',
     `${input.method} ${input.path}`,
     `apiKeyKind: ${input.apiKeyKind}`,
@@ -54,7 +79,89 @@ function buildApprovalMessage(input: z.infer<typeof callInputSchema>): string {
   return lines.join('\n');
 }
 
-export function registerCallTool(
+async function executeAskellRequest(
+  client: AskellClient,
+  input: CallInput | MutateInput,
+  signal: AbortSignal,
+): Promise<CallToolResult> {
+  const path = normalizeApiPath(input.path);
+  const known = operationRegistry
+    .find({
+      method: input.method,
+      pathPrefix: path,
+    })
+    .find((operation) => operation.path === path);
+
+  const request: AskellRequest = {
+    method: input.method,
+    path,
+    query: input.query,
+    body: input.body,
+    apiKeyKind: input.apiKeyKind ?? known?.apiKeyKind ?? 'secret',
+    signal,
+  };
+
+  try {
+    const response = await client.request(request);
+    return {
+      content: [{ type: 'text', text: response.text }],
+      isError: !response.ok,
+    };
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message : 'Unknown Askell API error';
+    return {
+      content: [{ type: 'text', text: message }],
+      isError: true,
+    };
+  }
+}
+
+function mutationConfirmation(
+  config: AppConfig,
+  input: MutateInput,
+  ctx: ToolCtx,
+): CallToolResult | InputRequiredResult | undefined {
+  const declined = inputResponse(ctx.mcpReq.inputResponses, 'confirm');
+  if (
+    declined.kind === 'elicit' &&
+    (declined.action === 'decline' || declined.action === 'cancel')
+  ) {
+    return {
+      content: [{ type: 'text', text: 'Mutation cancelled by operator.' }],
+      isError: true,
+    };
+  }
+
+  const confirmed = acceptedContent(
+    ctx.mcpReq.inputResponses,
+    'confirm',
+    confirmationSchema,
+  );
+
+  const decision = decideMutationGate({
+    gate: config.mutationGate,
+    alreadyConfirmed: confirmed?.confirm === true,
+    supportsFormElicitation: clientSupportsFormElicitation(
+      readClientCapabilities(ctx.mcpReq.envelope),
+    ),
+  });
+
+  if (decision.action === 'execute') {
+    return undefined;
+  }
+
+  return inputRequired({
+    inputRequests: {
+      confirm: inputRequired.elicit({
+        message: buildApprovalMessage(input),
+        requestedSchema: confirmationSchema,
+      }),
+    },
+  });
+}
+
+export function registerCallTools(
   server: McpServer,
   client: AskellClient,
   config: AppConfig,
@@ -62,10 +169,29 @@ export function registerCallTool(
   server.registerTool(
     'askell_call',
     {
-      title: 'Call Askell API',
+      title: 'Call Askell API (read)',
       description:
-        'Execute any Askell API endpoint (v1 or v2). Mutating requests require operator approval when requireMutationApproval is enabled. Use askell_list_operations and askell_describe_operation first to discover paths and parameters.',
+        'Read-only Askell API call (GET, HEAD) for any v1/v2 path. For POST/PUT/PATCH/DELETE use askell_mutate. Discover paths with askell_list_operations and askell_describe_operation first.',
       inputSchema: callInputSchema,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+      },
+    },
+    async (input, ctx): Promise<CallToolResult> => {
+      return executeAskellRequest(client, input, ctx.mcpReq.signal);
+    },
+  );
+
+  server.registerTool(
+    'askell_mutate',
+    {
+      title: 'Mutate Askell API',
+      description:
+        'Mutating Askell API call (POST, PUT, PATCH, DELETE). Clients that declared form elicitation get a confirmation form; others rely on the client tool-approval UI. Use askell_call for GET. Discover paths with askell_list_operations and askell_describe_operation first.',
+      inputSchema: mutateInputSchema,
       annotations: {
         readOnlyHint: false,
         destructiveHint: true,
@@ -74,56 +200,11 @@ export function registerCallTool(
       },
     },
     async (input, ctx): Promise<CallToolResult | InputRequiredResult> => {
-      const mutating = isMutatingMethod(input.method);
-
-      if (config.requireMutationApproval && mutating) {
-        const confirmed = acceptedContent(
-          ctx.mcpReq.inputResponses,
-          'confirm',
-          confirmationSchema,
-        );
-
-        if (confirmed?.confirm !== true) {
-          return inputRequired({
-            inputRequests: {
-              confirm: inputRequired.elicit({
-                message: buildApprovalMessage(input),
-                requestedSchema: confirmationSchema,
-              }),
-            },
-          });
-        }
-      }
-
-      const path = normalizeApiPath(input.path);
-      const known = operationRegistry.find({
-        method: input.method,
-        pathPrefix: path,
-      }).find((operation) => operation.path === path);
-
-      const request: AskellRequest = {
-        method: input.method,
-        path,
-        query: input.query,
-        body: input.body,
-        apiKeyKind: input.apiKeyKind ?? known?.apiKeyKind ?? 'secret',
-        signal: ctx.mcpReq.signal,
-      };
-
-      try {
-        const response = await client.request(request);
-        return {
-          content: [{ type: 'text', text: response.text }],
-          isError: !response.ok,
-        };
-      } catch (error) {
-        const message =
-          error instanceof Error ? error.message : 'Unknown Askell API error';
-        return {
-          content: [{ type: 'text', text: message }],
-          isError: true,
-        };
+      const gated = mutationConfirmation(config, input, ctx);
+      if (gated) {
+        return gated;
       }
+      return executeAskellRequest(client, input, ctx.mcpReq.signal);
     },
   );
 }

package/src/tools/mutation-gate.ts

@@ -0,0 +1,74 @@
+import {
+  CLIENT_CAPABILITIES_META_KEY,
+  type ClientCapabilities,
+} from '@modelcontextprotocol/server';
+
+import type { MutationGate } from '../config.ts';
+
+export type MutationGateDecision = { action: 'execute' } | { action: 'elicit' };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Per-request client capabilities (protocol 2026-07-28).
+ *
+ * Source of truth is `ctx.mcpReq.envelope[CLIENT_CAPABILITIES_META_KEY]` —
+ * reserved `io.modelcontextprotocol/*` keys are lifted out of `_meta` before
+ * the handler runs. Do not use deprecated `Server.getClientCapabilities()`:
+ * on 2026 stdio (`serveStdio` factory) it is always undefined (no `initialize`).
+ *
+ * 2025-era clients do not send this envelope; `undefined` here means "this
+ * request did not declare elicitation", so `auto` falls through to the
+ * client's own tool-allow UI.
+ *
+ * @see https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28.md
+ */
+export function readClientCapabilities(
+  envelope: unknown,
+): ClientCapabilities | undefined {
+  if (!isRecord(envelope)) {
+    return undefined;
+  }
+  const value = envelope[CLIENT_CAPABILITIES_META_KEY];
+  return isRecord(value) ? (value as ClientCapabilities) : undefined;
+}
+
+/** Form-mode elicitation: `elicitation: {}` (pre-mode) or `elicitation.form`. URL-only is not form. */
+export function clientSupportsFormElicitation(
+  capabilities: ClientCapabilities | undefined,
+): boolean {
+  const elicitation = capabilities?.elicitation;
+  if (elicitation == null) {
+    return false;
+  }
+  if (elicitation.form != null) {
+    return true;
+  }
+  const keys = Object.keys(elicitation);
+  if (elicitation.url != null && keys.every((key) => key === 'url')) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * auto  — elicit only if this request's envelope declared form elicitation.
+ * elicit — always return inputRequired; the SDK era-gates the wire
+ *          (2026 envelope / 2025 initialize via the legacy shim).
+ * off   — never elicit.
+ */
+export function decideMutationGate(options: {
+  gate: MutationGate;
+  alreadyConfirmed: boolean;
+  supportsFormElicitation: boolean;
+}): MutationGateDecision {
+  if (options.alreadyConfirmed || options.gate === 'off') {
+    return { action: 'execute' };
+  }
+  if (options.gate === 'elicit' || options.supportsFormElicitation) {
+    return { action: 'elicit' };
+  }
+  return { action: 'execute' };
+}