askell-mcp 0.2.0 → 0.3.1

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.1",
   "description": "MCP server for the Askell payment and subscription API (Bun + stdio)",
   "author": "Neschadin Oleksandr",
   "license": "MIT",
@@ -65,6 +65,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "zod": "4.4.3"
+    "zod": "4.5.4"
   }
 }

package/spec/openapi-v1.json

@@ -8,7 +8,8 @@
       "name": "Documentation",
       "url": "https://docs.askell.is"
     },
-    "version": "1.0.0"
+    "version": "1.0.0",
+    "x-askell-mcp-patched": "v1-overlay-1"
   },
   "servers": [
     {
@@ -52,10 +53,6 @@
       "name": "Webhooks",
       "description": "Management of webhooks. Requires secret api key."
     },
-    {
-      "name": "Webhook calls",
-      "description": "Webhook calls from Áskell to your system."
-    },
     {
       "name": "Transaction",
       "description": "Transaction operations, requires secret api key."
@@ -339,7 +336,14 @@
         },
         "responses": {
           "201": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Customer"
+                }
+              }
+            }
           },
           "400": {
             "description": "Invalid status value",
@@ -506,7 +510,14 @@
         ],
         "responses": {
           "200": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Customer"
+                }
+              }
+            }
           },
           "404": {
             "description": "Not found"
@@ -572,7 +583,14 @@
         ],
         "responses": {
           "200": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Customer"
+                }
+              }
+            }
           },
           "404": {
             "description": "Not found"
@@ -1367,23 +1385,6 @@
         ]
       }
     },
-    "/your-webhook-url/": {
-      "post": {
-        "tags": [
-          "Webhook calls"
-        ],
-        "summary": "Called when subscription changed or renewed",
-        "description": "We recommend that you verify all calls from us to your webhook endpoints. We sign each request with the `Hook-HMAC` header. The value is a HMAC digest derived from the body of the request and a secret key only known by the API and you. We also supply the type of event in the `Hook-Event` header.\n\nHere is a sample implementation in Python. This process is very similar to the one Shopify uses so more information can possibly be gleaned from their [documentation](https://shopify.dev/tutorials/manage-webhooks#verify-webhook).\n```\nimport base64\nimport hmac\nimport hashlib\n\nWEBHOOK_SECRET = \"Your webhook secret\".encode()\nWEBHOOK_DIGEST_TYPE = 'sha512'\n\ndef verify(hmac_header, digest_method, secret, message):\n   digestmod = getattr(hashlib, digest_method)\n   signed = base64.b64encode(\n       hmac.new(secret, message, digestmod).digest(),\n   ).strip()\n   return hmac.compare_digest(signed, hmac_header)\n\n# your view function\ndef handle_webhook(request):\n   # The signature\n   digest = request.META.get('HTTP_HOOK_HMAC').encode()\n   # The name of the webhook event\n   event = request.META.get('HTTP_HOOK_EVENT').encode()\n\n   body = request.body\n   if verify(digest, WEBHOOK_DIGEST_TYPE, WEBHOOK_SECRET, body):\n       payload = json.loads(body)\n       # ... the rest of your code here```\n",
-        "requestBody": {
-          "$ref": "#/components/requestBodies/SubscriptionMultiLite"
-        },
-        "responses": {
-          "200": {
-            "description": "Successful operation"
-          }
-        }
-      }
-    },
     "/webhooks/": {
       "get": {
         "tags": [
@@ -1423,7 +1424,14 @@
         },
         "responses": {
           "201": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Webhook"
+                }
+              }
+            }
           },
           "400": {
             "description": "Invalid status value",
@@ -1521,7 +1529,14 @@
         },
         "responses": {
           "200": {
-            "description": "Successful operation"
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Webhook"
+                }
+              }
+            }
           },
           "400": {
             "description": "Invalid status value",
@@ -1964,27 +1979,94 @@
         }
       },
       "Customer": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/CustomerCreate"
+        "type": "object",
+        "required": [
+          "id",
+          "first_name",
+          "last_name",
+          "email",
+          "customer_reference",
+          "phone",
+          "delivery_name",
+          "address_1",
+          "address_2",
+          "address_3",
+          "zip_code",
+          "city",
+          "country",
+          "payment_method",
+          "address"
+        ],
+        "properties": {
+          "id": {
+            "type": "integer",
+            "format": "int64"
           },
-          {
-            "type": "object",
-            "properties": {
-              "id": {
-                "type": "integer",
-                "format": "int64",
-                "example": 1
-              },
-              "payment_method": {
-                "type": "array",
-                "items": {
-                  "$ref": "#/components/schemas/PaymentMethod"
-                }
-              }
+          "first_name": {
+            "type": "string",
+            "maxLength": 128
+          },
+          "last_name": {
+            "type": "string",
+            "maxLength": 128
+          },
+          "email": {
+            "type": "string",
+            "nullable": true,
+            "maxLength": 254
+          },
+          "phone": {
+            "type": "string",
+            "nullable": true,
+            "maxLength": 32
+          },
+          "customer_reference": {
+            "type": "string",
+            "maxLength": 256
+          },
+          "delivery_name": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_1": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_2": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_3": {
+            "type": "string",
+            "nullable": true
+          },
+          "zip_code": {
+            "type": "string",
+            "nullable": true
+          },
+          "city": {
+            "type": "string",
+            "nullable": true
+          },
+          "country": {
+            "type": "string",
+            "nullable": true
+          },
+          "payment_method": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/PaymentMethod"
             }
+          },
+          "address": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/CustomerAddress"
+              }
+            ],
+            "nullable": true
           }
-        ]
+        }
       },
       "CustomerPaginated": {
         "type": "object",
@@ -2593,6 +2675,48 @@
             "example": "tokencreated"
           }
         }
+      },
+      "CustomerAddress": {
+        "type": "object",
+        "required": [
+          "delivery_name",
+          "address_1",
+          "address_2",
+          "address_3",
+          "zip_code",
+          "city",
+          "country"
+        ],
+        "properties": {
+          "delivery_name": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_1": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_2": {
+            "type": "string",
+            "nullable": true
+          },
+          "address_3": {
+            "type": "string",
+            "nullable": true
+          },
+          "zip_code": {
+            "type": "string",
+            "nullable": true
+          },
+          "city": {
+            "type": "string",
+            "nullable": true
+          },
+          "country": {
+            "type": "string",
+            "nullable": true
+          }
+        }
       }
     },
     "requestBodies": {
@@ -2780,4 +2904,4 @@
       }
     }
   }
-}
+}

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/openapi/patch-v1.ts

@@ -0,0 +1,238 @@
+/**
+ * Overlay for Askell OpenAPI v1. Upstream swagger is wrong in a few places;
+ * this is the same transform as askell_client_v1 `patchAskellSpec` (without Orval).
+ *
+ * Idempotent: safe to run on an already-patched document.
+ */
+
+type JsonSchema = Record<string, unknown>;
+type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+
+type OpenApiResponse = {
+  description?: string;
+  content?: Record<string, { schema?: JsonSchema }>;
+  [key: string]: unknown;
+};
+
+type OpenApiOperation = {
+  tags?: string[];
+  responses?: Record<string, OpenApiResponse>;
+  [key: string]: unknown;
+};
+
+type OpenApiPathItem = Partial<Record<HttpMethod, OpenApiOperation>> & {
+  [key: string]: unknown;
+};
+
+type OpenApiDocument = {
+  info?: Record<string, unknown>;
+  tags?: Array<{ name: string; description?: string }>;
+  paths?: Record<string, OpenApiPathItem>;
+  components?: {
+    schemas?: Record<string, JsonSchema>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+
+export const ASKELL_V1_PATCH = 'v1-overlay-1';
+export const WEBHOOK_CALLS_TAG = 'Webhook calls';
+
+/** Success bodies missing from swagger `content` (DELETE 204 stays empty). */
+const RESPONSE_BODIES = [
+  ['/customers/', 'post', '201', 'Customer'],
+  ['/customers/{customerReference}/', 'put', '200', 'Customer'],
+  ['/customers/{customerReference}/', 'patch', '200', 'Customer'],
+  ['/webhooks/', 'post', '201', 'Webhook'],
+  ['/webhooks/{id}/', 'patch', '200', 'Webhook'],
+] as const satisfies ReadonlyArray<
+  readonly [string, HttpMethod, string, string]
+>;
+
+const HTTP_METHODS = [
+  'get',
+  'post',
+  'put',
+  'patch',
+  'delete',
+  'head',
+] as const;
+
+const nullableString = (maxLength?: number): JsonSchema => ({
+  type: 'string',
+  nullable: true,
+  ...(maxLength === undefined ? {} : { maxLength }),
+});
+
+/** Flattened + nested address as returned by GET /customers/ and customer.* webhooks. */
+const CUSTOMER_ADDRESS_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: [
+    'delivery_name',
+    'address_1',
+    'address_2',
+    'address_3',
+    'zip_code',
+    'city',
+    'country',
+  ],
+  properties: {
+    delivery_name: nullableString(),
+    address_1: nullableString(),
+    address_2: nullableString(),
+    address_3: nullableString(),
+    zip_code: nullableString(),
+    city: nullableString(),
+    country: nullableString(),
+  },
+};
+
+/**
+ * Askell swagger reuses CustomerCreate (write) as the GET model via allOf.
+ * Live GET / webhooks return extra address fields, null emails/phones, and a
+ * required numeric id. Keep CustomerCreate as the POST body.
+ */
+const CUSTOMER_READ_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: [
+    'id',
+    'first_name',
+    'last_name',
+    'email',
+    'customer_reference',
+    'phone',
+    'delivery_name',
+    'address_1',
+    'address_2',
+    'address_3',
+    'zip_code',
+    'city',
+    'country',
+    'payment_method',
+    'address',
+  ],
+  properties: {
+    id: { type: 'integer', format: 'int64' },
+    first_name: { type: 'string', maxLength: 128 },
+    last_name: { type: 'string', maxLength: 128 },
+    email: nullableString(254),
+    phone: nullableString(32),
+    customer_reference: { type: 'string', maxLength: 256 },
+    delivery_name: nullableString(),
+    address_1: nullableString(),
+    address_2: nullableString(),
+    address_3: nullableString(),
+    zip_code: nullableString(),
+    city: nullableString(),
+    country: nullableString(),
+    payment_method: {
+      type: 'array',
+      items: { $ref: '#/components/schemas/PaymentMethod' },
+    },
+    address: {
+      allOf: [{ $ref: '#/components/schemas/CustomerAddress' }],
+      nullable: true,
+    },
+  },
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function dropWebhookCallOperations(doc: OpenApiDocument): void {
+  const paths = doc.paths;
+  if (!paths) {
+    return;
+  }
+
+  for (const path of Object.keys(paths)) {
+    const pathItem = paths[path];
+    if (!pathItem) {
+      continue;
+    }
+
+    for (const method of HTTP_METHODS) {
+      const operation = pathItem[method as HttpMethod];
+      if (operation?.tags?.includes(WEBHOOK_CALLS_TAG)) {
+        delete pathItem[method as HttpMethod];
+      }
+    }
+
+    const remaining = HTTP_METHODS.some(
+      (method) => pathItem[method as HttpMethod] != null,
+    );
+    if (!remaining) {
+      delete paths[path];
+    }
+  }
+
+  if (doc.tags) {
+    doc.tags = doc.tags.filter((tag) => tag.name !== WEBHOOK_CALLS_TAG);
+  }
+}
+
+function ensureResponseBody(
+  doc: OpenApiDocument,
+  path: string,
+  method: HttpMethod,
+  status: string,
+  schemaName: string,
+): void {
+  const pathItem = doc.paths?.[path];
+  const operation = pathItem?.[method];
+  const response = operation?.responses?.[status];
+  const label = `${method.toUpperCase()} ${path} ${status}`;
+
+  if (!pathItem || !operation || !response) {
+    throw new Error(`Askell spec missing ${label}`);
+  }
+
+  if (response.content?.['application/json']?.schema) {
+    return;
+  }
+
+  response.content = {
+    ...response.content,
+    'application/json': {
+      schema: { $ref: `#/components/schemas/${schemaName}` },
+    },
+  };
+}
+
+export function patchAskellV1Spec(spec: unknown): OpenApiDocument {
+  if (!isRecord(spec)) {
+    throw new Error('Askell v1 spec is not an object');
+  }
+
+  const doc = structuredClone(spec) as OpenApiDocument;
+  const schemas = doc.components?.schemas;
+  if (!schemas?.Customer) {
+    throw new Error('Askell spec missing components.schemas.Customer');
+  }
+  if (!schemas.Webhook) {
+    throw new Error('Askell spec missing components.schemas.Webhook');
+  }
+
+  dropWebhookCallOperations(doc);
+
+  doc.components = {
+    ...doc.components,
+    schemas: {
+      ...schemas,
+      CustomerAddress: CUSTOMER_ADDRESS_SCHEMA,
+      Customer: CUSTOMER_READ_SCHEMA,
+    },
+  };
+
+  for (const [path, method, status, schemaName] of RESPONSE_BODIES) {
+    ensureResponseBody(doc, path, method, status, schemaName);
+  }
+
+  doc.info = {
+    ...doc.info,
+    'x-askell-mcp-patched': ASKELL_V1_PATCH,
+  };
+
+  return doc;
+}

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 (not in OpenAPI)
+
+JSON body **is the event object**. It is **not** \`{ event, data }\`.
+
+Upstream swagger used to document a dummy \`POST /your-webhook-url/\` with \`SubscriptionMultiLite\` (\`{ customer, subscriptions[] }\`). \`sync-specs\` strips that path. Inbound payloads are still undocumented in OpenAPI — this resource is the overlay.
+
+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 (not in OpenAPI; dummy /your-webhook-url/ is stripped on sync), 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.1',
     },
     {
       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' };
+}