askell-mcp 0.3.0 → 0.4.0

package/README.md

@@ -19,16 +19,27 @@ In the Askell dashboard, copy your **private (secret)** API key. Optionally also
 
 ### 2. Add to your MCP client
 
+Prefer **two server entries** if you have both production and sandbox keys. Tool names are the same on both; the client distinguishes them by the `mcp.json` key (`askell-prod` vs `askell-sandbox`). Set `ASKELL_ENV` — the server picks the host. Each instance's instructions include the environment it is talking to.
+
 **With Bun** (`bunx`):
 
 ```json
 {
   "mcpServers": {
-    "askell": {
+    "askell-prod": {
       "command": "bunx",
       "args": ["-y", "askell-mcp"],
       "env": {
-        "ASKELL_PRIVATE_API_KEY": "your_secret_api_key"
+        "ASKELL_ENV": "production",
+        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key"
+      }
+    },
+    "askell-sandbox": {
+      "command": "bunx",
+      "args": ["-y", "askell-mcp"],
+      "env": {
+        "ASKELL_ENV": "sandbox",
+        "ASKELL_PRIVATE_API_KEY": "your_sandbox_secret_api_key"
       }
     }
   }
@@ -40,10 +51,11 @@ In the Askell dashboard, copy your **private (secret)** API key. Optionally also
 ```json
 {
   "mcpServers": {
-    "askell": {
+    "askell-prod": {
       "command": "/absolute/path/to/askell-mcp-linux-x64",
       "env": {
-        "ASKELL_PRIVATE_API_KEY": "your_secret_api_key"
+        "ASKELL_ENV": "production",
+        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key"
       }
     }
   }
@@ -60,12 +72,18 @@ Restart the client after saving.
 | ---------------------------------- | -------- | ----------------------- | ----------------------------------------------- |
 | `ASKELL_PRIVATE_API_KEY`           | yes\*    | —                       | Secret API key (_or_ `ASKELL_SECRET_API_KEY`)   |
 | `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_ENV`                       | no       | `production`            | `production` \| `sandbox` — selects the official API host |
+| `ASKELL_API_URL`                   | no       | —                       | Custom/local API base only (_or_ `ASKELL_API_BASE_URL`). Do not set together with `ASKELL_ENV` unless it matches |
 | `ASKELL_RESPONSE_MAX_BYTES`        | no       | `64000`                 | Max response size returned to the model         |
 | `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_ENV` picks a stable host (same v1/v2 surface):
+
+- **production** — `https://askell.is/api`
+- **sandbox** — `https://sandbox.askell.is/api` (isolated tenant; keys from that dashboard)
+
+Point a second MCP server entry at sandbox (`ASKELL_ENV=sandbox`) rather than switching env on one process. Keys do not work across hosts. **Áskell Test Gateway** is a payment acquirer (fake cards) on either host — not the same as the sandbox API. Official prose at [docs.askell.is](https://docs.askell.is/en/getting_started/index.html) still documents Test Gateway and may omit the sandbox host.
 
 `ASKELL_MUTATION_GATE`:
 

package/mcp.json.example

@@ -1,11 +1,21 @@
 {
   "mcpServers": {
-    "askell": {
+    "askell-prod": {
       "command": "bunx",
       "args": ["-y", "askell-mcp"],
       "env": {
-        "ASKELL_PRIVATE_API_KEY": "your_secret_api_key",
-        "ASKELL_PUBLIC_API_KEY": "your_public_api_key_optional"
+        "ASKELL_ENV": "production",
+        "ASKELL_PRIVATE_API_KEY": "your_production_secret_api_key",
+        "ASKELL_PUBLIC_API_KEY": "your_production_public_api_key_optional"
+      }
+    },
+    "askell-sandbox": {
+      "command": "bunx",
+      "args": ["-y", "askell-mcp"],
+      "env": {
+        "ASKELL_ENV": "sandbox",
+        "ASKELL_PRIVATE_API_KEY": "your_sandbox_secret_api_key",
+        "ASKELL_PUBLIC_API_KEY": "your_sandbox_public_api_key_optional"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "askell-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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,11 +1,23 @@
 import * as z from 'zod';
 
+export const PRODUCTION_API_BASE_URL = 'https://askell.is/api';
+export const SANDBOX_API_BASE_URL = 'https://sandbox.askell.is/api';
+
+export const ASKELL_ENVS = ['production', 'sandbox'] as const;
+export type AskellOfficialEnv = (typeof ASKELL_ENVS)[number];
+export type AskellEnv = AskellOfficialEnv | 'custom';
+
+export const ASKELL_API_BASE_URLS = {
+  production: PRODUCTION_API_BASE_URL,
+  sandbox: SANDBOX_API_BASE_URL,
+} as const satisfies Record<AskellOfficialEnv, string>;
+
 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)');
+  .describe('Custom Askell API base URL (local/fork override)');
 
 const mutationGateAliases = z
   .enum(['true', 'false', 'on', 'yes', 'no', '1', '0'])
@@ -26,8 +38,55 @@ export const MutationGateSchema = z
     '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'),
+export const AskellEnvSchema = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .transform((value) => (value === 'prod' ? 'production' : value))
+  .pipe(z.enum(ASKELL_ENVS));
+
+export function classifyAskellHost(apiBaseUrl: string): AskellEnv {
+  const normalized = normalizeBaseUrl(apiBaseUrl);
+  if (normalized === PRODUCTION_API_BASE_URL) {
+    return 'production';
+  }
+  if (normalized === SANDBOX_API_BASE_URL) {
+    return 'sandbox';
+  }
+  return 'custom';
+}
+
+export function resolveAskellTarget(input: {
+  askellEnv?: AskellOfficialEnv;
+  apiBaseUrl?: string;
+}): { askellEnv: AskellEnv; apiBaseUrl: string } {
+  if (input.apiBaseUrl) {
+    const apiBaseUrl = normalizeBaseUrl(input.apiBaseUrl);
+    const classified = classifyAskellHost(apiBaseUrl);
+
+    if (input.askellEnv !== undefined) {
+      if (classified === 'custom') {
+        throw new Error(
+          `ASKELL_ENV=${input.askellEnv} selects an official Askell host; omit ASKELL_ENV when ASKELL_API_URL is custom (${apiBaseUrl})`,
+        );
+      }
+      if (classified !== input.askellEnv) {
+        throw new Error(
+          `ASKELL_ENV=${input.askellEnv} does not match ASKELL_API_URL (${apiBaseUrl}). Omit ASKELL_API_URL and let ASKELL_ENV pick the host, or omit ASKELL_ENV.`,
+        );
+      }
+    }
+
+    return { askellEnv: classified, apiBaseUrl };
+  }
+
+  const askellEnv = input.askellEnv ?? 'production';
+  return { askellEnv, apiBaseUrl: ASKELL_API_BASE_URLS[askellEnv] };
+}
+
+const ConfigInputSchema = z.object({
+  askellEnv: AskellEnvSchema.optional(),
+  apiBaseUrl: httpUrl.optional(),
   secretApiKey: z.string().min(1).describe('Secret (private) API key'),
   publicApiKey: z
     .string()
@@ -43,23 +102,60 @@ export const ConfigSchema = z.object({
   mutationGate: MutationGateSchema,
 });
 
-export type AppConfig = z.infer<typeof ConfigSchema>;
+export const ConfigSchema = ConfigInputSchema.superRefine((value, ctx) => {
+  try {
+    resolveAskellTarget({
+      askellEnv: value.askellEnv,
+      apiBaseUrl: value.apiBaseUrl,
+    });
+  } catch (error) {
+    ctx.addIssue({
+      code: 'custom',
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}).transform((value) => {
+  const target = resolveAskellTarget({
+    askellEnv: value.askellEnv,
+    apiBaseUrl: value.apiBaseUrl,
+  });
+  return {
+    ...value,
+    askellEnv: target.askellEnv,
+    apiBaseUrl: target.apiBaseUrl,
+  };
+});
+
+export type AppConfig = z.output<typeof ConfigSchema>;
 
 const CONFIG_HELP = `Askell MCP credentials missing.
 
-Set ASKELL_PRIVATE_API_KEY (or ASKELL_SECRET_API_KEY), optionally ASKELL_PUBLIC_API_KEY and ASKELL_API_URL:
+Set ASKELL_PRIVATE_API_KEY (or ASKELL_SECRET_API_KEY), optionally ASKELL_PUBLIC_API_KEY.
+Set ASKELL_ENV=production|sandbox (default production) — the server picks the host.
+Keys are per host. ASKELL_API_URL is only for a custom/local API.
 
   Local dev — create .env in the project root (Bun loads it automatically):
+    ASKELL_ENV=sandbox
     ASKELL_PRIVATE_API_KEY=...
     ASKELL_PUBLIC_API_KEY=...
 
-  Published package (requires Bun) — Cursor / Claude mcp.json:
+  Published package (requires Bun) — Cursor / Claude mcp.json (two entries if you use sandbox):
     {
       "mcpServers": {
-        "askell": {
+        "askell-prod": {
+          "command": "bunx",
+          "args": ["-y", "askell-mcp"],
+          "env": {
+            "ASKELL_ENV": "production",
+            "ASKELL_PRIVATE_API_KEY": "...",
+            "ASKELL_PUBLIC_API_KEY": "..."
+          }
+        },
+        "askell-sandbox": {
           "command": "bunx",
           "args": ["-y", "askell-mcp"],
           "env": {
+            "ASKELL_ENV": "sandbox",
             "ASKELL_PRIVATE_API_KEY": "...",
             "ASKELL_PUBLIC_API_KEY": "..."
           }
@@ -75,6 +171,7 @@ function loadConfigFromEnv(): unknown {
     return undefined;
   }
 
+  const askellEnv = env.ASKELL_ENV?.trim() || undefined;
   const apiBaseUrl = env.ASKELL_API_URL ?? env.ASKELL_API_BASE_URL;
   const responseMaxBytes = env.ASKELL_RESPONSE_MAX_BYTES;
   const mutationGateRaw =
@@ -82,6 +179,7 @@ function loadConfigFromEnv(): unknown {
   const mutationGate = mutationGateRaw?.trim().toLowerCase() || undefined;
 
   return {
+    ...(askellEnv ? { askellEnv } : {}),
     ...(apiBaseUrl ? { apiBaseUrl } : {}),
     secretApiKey,
     ...(env.ASKELL_PUBLIC_API_KEY

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

@@ -11,11 +11,11 @@ Headers:
 - 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)
+## Body shape (not in OpenAPI)
 
 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.
+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\`.
 

package/src/server.ts

@@ -1,13 +1,34 @@
 import { McpServer } from '@modelcontextprotocol/server';
 
 import { AskellClient } from './client/askell-client.ts';
-import type { AppConfig } from './config.ts';
+import {
+  PRODUCTION_API_BASE_URL,
+  SANDBOX_API_BASE_URL,
+  normalizeBaseUrl,
+  type AppConfig,
+} from './config.ts';
 import { registerResources } from './resources/register.ts';
 import { registerAnalysisTools } from './tools/analysis.ts';
 import { registerCallTools } from './tools/call.ts';
 import { registerDiscoveryTools } from './tools/discovery.ts';
+import { PACKAGE_VERSION } from './version.ts';
 
-const SERVER_INSTRUCTIONS = `Askell MCP server for payment and subscription operations.
+export function buildServerInstructions(config: AppConfig): string {
+  const apiBase = normalizeBaseUrl(config.apiBaseUrl);
+  const envLine =
+    config.askellEnv === 'custom'
+      ? `This instance: custom API base ${apiBase} (ASKELL_API_URL override)`
+      : `This instance: ${config.askellEnv} (${apiBase})`;
+
+  return `Askell MCP server for payment and subscription operations.
+
+${envLine}
+Official hosts (picked by ASKELL_ENV=production|sandbox; do not pass the URL):
+- production: ${PRODUCTION_API_BASE_URL}
+- sandbox (isolated tenant, separate API keys): ${SANDBOX_API_BASE_URL}
+v1 and v2 share that base (v2 paths start with /v2/). Keys belong to one host — do not reuse production keys on sandbox or the reverse.
+Áskell Test Gateway is a payment acquirer on either host, not a separate API host.
+If both askell-prod and askell-sandbox MCP servers are connected, pick the instance whose environment matches the intended tenant.
 
 Workflow:
 1. Use askell_list_operations and askell_describe_operation to discover endpoints, parameters, and auth requirements.
@@ -46,16 +67,17 @@ Safety:
 
 Resources:
 - askell://spec/v1 and askell://spec/v2 — bundled OpenAPI
-- askell://docs/webhook-events — inbound webhook payloads (ignore OpenAPI /your-webhook-url/), HMAC-SHA512, /webhooks/ hmac_secret`;
+- 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.3.0',
+      version: PACKAGE_VERSION,
     },
     {
-      instructions: SERVER_INSTRUCTIONS,
+      instructions: buildServerInstructions(config),
     },
   );
 

package/src/version.ts

@@ -0,0 +1,3 @@
+import packageJson from '../package.json' with { type: 'json' };
+
+export const PACKAGE_VERSION: string = packageJson.version;