@payments-ai/mcp 2.5.0 → 2.6.0

package/dist/main.http.js

@@ -249,8 +249,10 @@ var SUPPORTED_OAUTH_SCOPES = [
   "checkout:write",
   "transaction:read",
   "customer:read",
-  "invoice:read"
+  "invoice:read",
+  "webhook:listen"
 ];
+var CLI_EMAIL_CREDENTIAL_SCOPES = [...SUPPORTED_OAUTH_SCOPES];
 var OAUTH_CONSENT_READ_SCOPES = [
   "merchant:read",
   "product:read",
@@ -263,7 +265,8 @@ var OAUTH_CONSENT_READ_SCOPES = [
 var EXPLICIT_GRANT_OAUTH_SCOPES = [
   "transaction:read",
   "customer:read",
-  "invoice:read"
+  "invoice:read",
+  "webhook:listen"
 ];
 var EXPLICIT_GRANT_SCOPE_SET = new Set(EXPLICIT_GRANT_OAUTH_SCOPES);
 function isExplicitGrantScope(scope) {
@@ -11258,8 +11261,8 @@ var error43 = () => {
       case "not_multiple_of":
         return `N\xFAmero inv\xE1lido: deve ser m\xFAltiplo de ${issue2.divisor}`;
       case "unrecognized_keys": {
-        const plural2 = issue2.keys.length > 1 ? "s" : "";
-        return `Chave${plural2} inv\xE1lida${plural2}: ${joinValues(issue2.keys, ", ")}`;
+        const plural3 = issue2.keys.length > 1 ? "s" : "";
+        return `Chave${plural3} inv\xE1lida${plural3}: ${joinValues(issue2.keys, ", ")}`;
       }
       case "invalid_key":
         return `Entrada inv\xE1lida n${translateOriginWithArticle(issue2.origin, "definite")}`;
@@ -11403,8 +11406,8 @@ var error44 = () => {
       case "not_multiple_of":
         return `N\xFAmero inv\xE1lido: deve ser m\xFAltiplo de ${issue2.divisor}`;
       case "unrecognized_keys": {
-        const plural2 = issue2.keys.length > 1 ? "s" : "";
-        return `Chave${plural2} inv\xE1lida${plural2}: ${joinValues(issue2.keys, ", ")}`;
+        const plural3 = issue2.keys.length > 1 ? "s" : "";
+        return `Chave${plural3} inv\xE1lida${plural3}: ${joinValues(issue2.keys, ", ")}`;
       }
       case "invalid_key":
         return `Entrada inv\xE1lida n${translateOriginWithArticle(issue2.origin, "definite")}`;
@@ -20280,6 +20283,9 @@ var mcpPlanSummarySchema = external_exports.object({
 // ../../packages/mcp-contracts/dist/create-order.js
 var MAX_ORDER_ITEMS = 20;
 var MAX_IDEMPOTENCY_KEY_LENGTH = 255;
+var MAX_ORDER_METADATA_KEYS = 50;
+var MAX_ORDER_METADATA_KEY_LENGTH = 40;
+var MAX_ORDER_METADATA_VALUE_LENGTH = 500;
 var ORDER_ITEM_TYPES = ["one_time", "recurring"];
 var ORDER_BILLING_PERIODS = ["day", "week", "month", "year"];
 var orderQuantitySchema = external_exports.number().int().positive().max(MAX_ORDER_ITEM_QUANTITY, ORDER_QUANTITY_TOO_HIGH_MESSAGE);
@@ -20300,11 +20306,18 @@ var createOrderItemSchema = external_exports.union([
   createOrderPlanItemSchema,
   createOrderCustomItemSchema
 ]);
+var orderMetadataSchema = external_exports.record(external_exports.string().min(1, "metadata keys must not be empty.").max(MAX_ORDER_METADATA_KEY_LENGTH, `metadata keys must be at most ${MAX_ORDER_METADATA_KEY_LENGTH} characters. Recovery: send a shorter key.`), external_exports.string().max(MAX_ORDER_METADATA_VALUE_LENGTH, `metadata values must be at most ${MAX_ORDER_METADATA_VALUE_LENGTH} characters. Recovery: send a shorter value.`)).refine((metadata) => Object.keys(metadata).length <= MAX_ORDER_METADATA_KEYS, {
+  message: `metadata must have at most ${MAX_ORDER_METADATA_KEYS} keys. Recovery: send fewer keys.`
+}).meta({
+  maxProperties: MAX_ORDER_METADATA_KEYS,
+  description: 'Your own key/value strings stored on the order and returned exactly as sent, for example { "cf_order_id": "A-1001" }. Not shown to the buyer.'
+});
 var createOrderInputSchema = external_exports.object({
   merchantId: external_exports.uuid(),
   currency: supportedCurrencyCodeSchema,
   items: external_exports.array(createOrderItemSchema).min(1).max(MAX_ORDER_ITEMS),
-  idempotencyKey: external_exports.string().trim().min(1).max(MAX_IDEMPOTENCY_KEY_LENGTH).optional()
+  idempotencyKey: external_exports.string().trim().min(1).max(MAX_IDEMPOTENCY_KEY_LENGTH).optional(),
+  metadata: orderMetadataSchema.optional()
 }).strict().superRefine((input2, ctx) => {
   checkCustomOrderItemAmounts(input2, ctx);
   checkCustomOrderItemsTotal(input2, ctx);
@@ -20327,7 +20340,8 @@ var createOrderOutputSchema = external_exports.object({
   billingPeriod: external_exports.enum(ORDER_BILLING_PERIODS).nullable(),
   periodLength: external_exports.number().int().nullable(),
   trialPeriodDays: external_exports.number().int().nullable(),
-  items: external_exports.array(createOrderItemResponseSchema)
+  items: external_exports.array(createOrderItemResponseSchema),
+  metadata: external_exports.record(external_exports.string(), external_exports.string()).default({})
 });
 
 // ../../packages/mcp-contracts/dist/product-name.js
@@ -20591,7 +20605,7 @@ function canonicalResourceUrl(value) {
 }
 
 // ../../packages/mcp-contracts/dist/mcp-session-expired.js
-var MCP_SESSION_EXPIRED_MESSAGE = "MCP Session Expired. Please generate a new token in Developer Tools \u2192 MCP Tokens.";
+var MCP_SESSION_EXPIRED_MESSAGE = "MCP Session Expired. Re-approve the connection in your AI client, or generate a new token in Developer Tools \u2192 MCP Tokens if you connected with a token.";
 
 // ../../packages/mcp-contracts/dist/list-products.js
 var PLAN_TYPES3 = ["free-access", "one-time", "recurring"];
@@ -20698,13 +20712,28 @@ var mcpMerchantSummarySchema = external_exports.object({
   name: external_exports.string()
 });
 
+// ../../packages/mcp-contracts/dist/credential-expiry.js
+var CREDENTIAL_EXPIRY_WARNING_WINDOW_DAYS = 14;
+var CREDENTIAL_EXPIRY_WARNING_WINDOW_SECONDS = CREDENTIAL_EXPIRY_WARNING_WINDOW_DAYS * 24 * 60 * 60;
+var CREDENTIAL_EXPIRY_WARNING_META_KEY = "ai.payments/credentialExpiryWarning";
+var credentialExpiryWarningSchema = external_exports.object({
+  credentialExpiresAt: external_exports.iso.datetime().describe("When the MCP credential stops working (ISO 8601, UTC)."),
+  credentialExpiresInSeconds: external_exports.number().int().nonnegative().describe("Seconds of validity left on the MCP credential; 0 once it has expired."),
+  reapproveUrl: external_exports.url().describe("Page that walks the user through re-approving this MCP connection."),
+  message: external_exports.string().describe("One sentence to relay to the user, with the re-approve link.")
+});
+
 // ../../packages/mcp-contracts/dist/whoami.js
 var mcpConnectionHostSchema = external_exports.enum(["sandbox", "live"]);
 var mcpConnectionProofSchema = external_exports.object({
   userId: external_exports.uuid(),
   scopes: external_exports.array(external_exports.string()).nullable(),
   host: mcpConnectionHostSchema.describe(`The class of MCP URL this client is connected to: "live" for the main MCP URL, "sandbox" for the sandbox-only MCP URL. Not the environment (dev, stage or prod) and not a merchant's deployment.`),
-  endpoint: external_exports.url()
+  endpoint: external_exports.url(),
+  merchantIds: external_exports.array(external_exports.uuid()).describe("Ids of the merchants this credential is a member of, as returned when the credential was validated. Call get_my_merchant for names and per-deployment state; on the main MCP URL a merchant that exists on sandbox only is listed there, not here."),
+  credentialExpiresAt: external_exports.iso.datetime().nullable().describe("When this MCP credential stops working (ISO 8601, UTC); null when unknown."),
+  credentialExpiresInSeconds: external_exports.number().int().nonnegative().nullable().describe("Seconds of validity left on this MCP credential; null when the expiry is unknown."),
+  credentialExpiryWarning: credentialExpiryWarningSchema.optional().describe("Present only when the credential expires within the warning window: tell the user and share the re-approve link.")
 });
 var whoamiOutputSchema = mcpConnectionProofSchema;
 
@@ -23018,6 +23047,12 @@ function parsePhoneNumber2(text, options2, metadata) {
   }
 }
 
+// ../../node_modules/.pnpm/libphonenumber-js@1.13.14/node_modules/libphonenumber-js/es6/parsePhoneNumber.js
+function parsePhoneNumber3() {
+  var _normalizeArguments = normalizeArguments(arguments), text = _normalizeArguments.text, options2 = _normalizeArguments.options, metadata = _normalizeArguments.metadata;
+  return parsePhoneNumber2(text, options2, metadata);
+}
+
 // ../../node_modules/.pnpm/libphonenumber-js@1.13.14/node_modules/libphonenumber-js/es6/isValidPhoneNumber.js
 function _typeof7(o) {
   "@babel/helpers - typeof";
@@ -23074,6 +23109,11 @@ function isValidPhoneNumber() {
   return phoneNumber && phoneNumber.isValid() || false;
 }
 
+// ../../node_modules/.pnpm/libphonenumber-js@1.13.14/node_modules/libphonenumber-js/min/exports/parsePhoneNumber.js
+function parsePhoneNumber4() {
+  return withMetadataArgument(parsePhoneNumber3, arguments);
+}
+
 // ../../node_modules/.pnpm/libphonenumber-js@1.13.14/node_modules/libphonenumber-js/min/exports/isValidPhoneNumber.js
 function isValidPhoneNumber2() {
   return withMetadataArgument(isValidPhoneNumber, arguments);
@@ -23082,11 +23122,21 @@ function isValidPhoneNumber2() {
 // ../../packages/mcp-contracts/dist/merchant-phone.js
 var E164_PATTERN = /^\+[1-9]\d{1,14}$/;
 var NANP_FICTIONAL_BLOCK = /^\+1\d{3}55501\d{2}$/;
+function isDialableWithPlusPrefix(phone) {
+  return /^\d+$/.test(phone) && isDialablePhoneNumber(`+${phone}`);
+}
+function countryOfPlusPrefixedDigits(phone) {
+  if (!isDialableWithPlusPrefix(phone))
+    return void 0;
+  return parsePhoneNumber4(`+${phone}`)?.country;
+}
 function isDialablePhoneNumber(phone) {
   return E164_PATTERN.test(phone) && isValidPhoneNumber2(phone) && !NANP_FICTIONAL_BLOCK.test(phone);
 }
 
 // ../../packages/mcp-contracts/dist/create-merchant-account.js
+var PHONE_INVALID_MESSAGE = "Provide the user's own mobile number, dialable and in E.164 format with country code (format only: +14155552671). Recovery: ask the user for their real mobile number and never invent a placeholder or a reserved fictional number (a +1 555 area code or a 555-01XX number) \u2014 the identity-verification link is sent to it by SMS after go_live. If the user does not want to share one, omit phone.";
+var phoneMissingPlusMessage = (phone, country) => `The phone is missing the leading + of E.164 format. With a + it would read +${phone}${country ? ` (${country})` : ""}, which is only right if the number already starts with the user's country code. Recovery: prefix + (for example +14155552671) and re-send only if the number already starts with the user's country code; otherwise ask the user for their number with its country code.`;
 var createMerchantAccountInputSchema = external_exports.object({
   name: external_exports.string().trim().min(1, {
     message: "Provide a non-empty business or display name. Recovery: pass a non-empty string in the name field and re-send the tool call. Merchants are identified downstream by merchantId, not by name, so disambiguate look-alike names by merchantId instead of by picking a distinct name here."
@@ -23099,8 +23149,13 @@ var createMerchantAccountInputSchema = external_exports.object({
    * it by SMS, so shape alone is not enough: an invented placeholder passes E.164 and the
    * SMS silently goes nowhere.
    */
-  phone: external_exports.string().trim().refine(isDialablePhoneNumber, {
-    message: "Provide the user's own mobile number, dialable and in E.164 format with country code (format only: +14155552671). Recovery: ask the user for their real mobile number and never invent a placeholder or a reserved fictional number (a +1 555 area code or a 555-01XX number) \u2014 the identity-verification link is sent to it by SMS after go_live. If the user does not want to share one, omit phone."
+  phone: external_exports.string().trim().superRefine((phone, ctx) => {
+    if (isDialablePhoneNumber(phone))
+      return;
+    ctx.addIssue({
+      code: "custom",
+      message: isDialableWithPlusPrefix(phone) ? phoneMissingPlusMessage(phone, countryOfPlusPrefixedDigits(phone)) : PHONE_INVALID_MESSAGE
+    });
   }).optional(),
   /**
    * Optional retry correlation id from a prior partial failure.
@@ -25438,6 +25493,7 @@ function formatPeriodCaps(caps) {
 var PRICE_UNITS = `a decimal dollar amount in the plan currency (major units, e.g. 9.99 for $9.99 \u2014 NOT cents, so 1999 means $1,999.00; a currency with no minor unit takes whole numbers, so 500 means \xA5500 and 500.5 is rejected; currency is one of ${SUPPORTED_CURRENCIES.join(", ")})`;
 var CREATE_PRODUCT_STORED_PLANS = "`plans` repeats what was stored for each plan, in `planIds` order: amount, currency, `price` formatted as the checkout shows it, and for recurring plans billingPeriod, periodLength and freeTrial \u2014 check `price` against what the user asked for. `warnings`, when present, flags an amount that looks like cents; relay it and, if the user meant the smaller price, fix it with update_plan before sharing the link.";
 var CREATE_ORDER_BOUNDS = `currency is one of ${SUPPORTED_CURRENCIES.join(", ")}. unitPrice is at most ${formatAmountCeilings()} in the order currency, and so is each line (unitPrice x quantity) and the order total; quantity is at most ${MAX_ORDER_ITEM_QUANTITY}; periodLength is at most one year of the billingPeriod (${formatPeriodCaps(MAX_ORDER_PERIOD_LENGTH_BY_BILLING_PERIOD)}). When billingPeriod is "day", periodLength must be at least ${MIN_WHOP_BILLING_PERIOD_DAYS} (the payment provider rejects true daily subscriptions). trialPeriodDays is at most ${MAX_FREE_TRIAL_DAYS}, only on recurring custom lines, and must match the trial length of every other recurring line in the order (catalogue plan or custom).`;
+var CREATE_ORDER_METADATA = ` Optional metadata: your own flat map of string keys to string values (for example { "cf_order_id": "A-1001" }), at most ${MAX_ORDER_METADATA_KEYS} keys, each key 1-${MAX_ORDER_METADATA_KEY_LENGTH} characters, each value at most ${MAX_ORDER_METADATA_VALUE_LENGTH} characters. It is stored on the order and returned in metadata exactly as sent (keys are not case-converted), including on the payment and subscription webhooks for the order; the buyer does not see it. Repeating an idempotencyKey returns the original order, including its original metadata; metadata on the repeat is ignored.`;
 var CREATE_PRODUCT_STATUS_NOTE = "Optional `status` ('draft' | 'active' | 'archived') defaults to 'active' \u2014 the product is created live and purchasable immediately via its checkout link, regardless of status. Pass `status: 'draft'` only when the end user explicitly asks for a draft or temporary/not-yet-ready product.";
 var CREATE_PRODUCT_COPY_CAPS = `Product \`name\` (<=${PRODUCT_NAME_MAX} chars), product \`description\` (<=${PRODUCT_DESCRIPTION_MAX} chars) and plan \`description\` (<=${PLAN_DESCRIPTION_MAX} chars) are all short one-line copy \u2014 if yours is longer, shorten it before calling and put the full version in that plan's \`richDescription\` (<=${PLAN_RICH_DESCRIPTION_MAX} chars), which the hosted checkout page renders as plain text beneath the short description (newlines preserved, markup not interpreted). \`richDescription\` is per plan, so product-level copy that overflows must still be edited down.`;
 var TRANSACTION_STATUS_RULE = 'Status: only "succeeded" means paid. "pending" is not yet confirmed by the payment provider, so never report a pending transaction as paid. "partially_refunded" means some but not all of the amount was refunded; "refunded", "failed" and "disputed" mean what they say.';
@@ -25446,14 +25502,14 @@ var TRANSACTION_SCOPE_RULE = 'Requires the "transaction:read" scope, which exist
 var LIST_TRANSACTIONS_SUMMARY = `List a merchant's transactions, newest first, narrowed by the optional filters in the input schema. For the full lookup guide, call search_payments_ai_docs with "transaction lookup".`;
 var GET_TRANSACTION_DETAIL = "Get one transaction by transactionId from list_transactions: the same fields plus the refunded amount and the order's line items. items is empty for a single-plan purchase, where plan names what was bought.";
 var TOOL_DESCRIPTIONS = {
-  [MCP_TOOL_NAMES.WHOAMI]: `Prove which account and which MCP server this connection reaches. Takes no arguments. Returns { userId, scopes, host, endpoint }, read from the validated token and the server that answered. "scopes" null means the token holds every scope except "transaction:read", which must be granted by name. "host" is the class of MCP URL this client is connected to: "live" for the main MCP URL, which serves every merchant at its own deployment, or "sandbox" for the sandbox-only MCP URL. It is not the environment (dev, stage or prod) and not a merchant's deployment: on a "live" host a merchant that has not gone live still reports deployment "sandbox" in get_my_merchant, which is expected. To prove the connection, quote userId, host and endpoint from this result rather than the client's connected label. Needs no scope: any valid token can call it. Call get_my_merchant next to find the merchants this connection owns.`,
+  [MCP_TOOL_NAMES.WHOAMI]: `Prove which account and which MCP server this connection reaches. Takes no arguments. Returns { userId, scopes, host, endpoint, merchantIds, credentialExpiresAt, credentialExpiresInSeconds, credentialExpiryWarning? }, read from the validated token and the server that answered. "scopes" null means the token holds every scope except "transaction:read", which must be granted by name. "host" is the class of MCP URL this client is connected to: "live" for the main MCP URL, which serves every merchant at its own deployment, or "sandbox" for the sandbox-only MCP URL. It is not the environment (dev, stage or prod) and not a merchant's deployment: on a "live" host a merchant that has not gone live still reports deployment "sandbox" in get_my_merchant, which is expected. To prove the connection, quote userId, host and endpoint from this result rather than the client's connected label. "merchantIds" are the merchants this credential is a member of; credentialExpiresAt and credentialExpiresInSeconds say when it stops working (null when unknown). credentialExpiryWarning is present only when the credential expires within ` + CREDENTIAL_EXPIRY_WARNING_WINDOW_DAYS + " days: tell the user and share its reapproveUrl, and expect the same warning appended to every other tool result until they re-approve. Needs no scope: any valid token can call it. Call get_my_merchant next to find the merchants this connection owns.",
   [MCP_TOOL_NAMES.GET_MY_MERCHANT]: 'List the merchant accounts this connection already owns. Call this BEFORE create_merchant_account: a new agent session cannot remember a merchant created in an earlier one, and creating again produces a second merchant with its own products and its own checkout links. Takes no arguments \u2014 the merchants come from the authorization on the connection itself. Returns { merchants: [{ merchantId, name, deployment }] }. "deployment" is "sandbox" before go_live and "live" after it has succeeded, and it matches where create_product and list_products will route for that merchant right now. An empty merchants array is a normal result, not an error: this connection owns no merchant yet, so call create_merchant_account. When more than one merchant comes back, ask which one to use \u2014 do not pick for the user. Requires the "merchant:read" scope.',
   [MCP_TOOL_NAMES.CREATE_MERCHANT_ACCOUNT]: "Create a merchant account on PAI Managed. Call get_my_merchant first: if it returns a merchant, reuse that merchantId instead of creating another, because a duplicate merchant gets its own products and checkout links. " + CREATE_MERCHANT_CONTACT_GUIDANCE + " The business name is a display label and is not globally unique \u2014 every downstream tool (create_product, list_products, checkout) keys on merchantId, so if two merchants happen to share a name, disambiguate them by merchantId (do not pick a distinct name here to work around it). No identity verification (KYC/KYB) is needed to use sandbox \u2014 products, checkout links and test transactions all work without it; verification is required on live. " + IDENTITY_VERIFICATION_RULE + " Dual-provisions live and sandbox with a shared merchantId. On partial dual-provision failure (one backend created it, the other did not), retry without a merchantId to finish it. When both backends fail, the returned error names the appropriate recovery \u2014 follow it as-is rather than repeating the same call in a loop, and treat repeated identical failures as needing escalation to support. Returns that merchant ID. Without a merchantId, a merchant this account already owns is returned with existing: true instead of a new one being created, and whichever of live or sandbox is missing it gets a copy with the details the existing copy holds; a merchantId this account already owns is finished the same way, and the copy that exists is never changed. Next: create_product (and checkout tools) on sandbox, then go_live when ready.",
   [MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS]: 'Get the production activation status of a merchant account on PAI Managed. Returns { status, identityVerification }. status "pending": the merchant has not been promoted to live yet; this is the only status where go_live is the next step, once the user confirms the merchant is ready, and polling this tool will not change it on its own. status "verification_pending": the merchant is promoted to live and identity verification (KYC) is not complete yet; do not call go_live again. status "active": live and identity verified. status "not_provisioned": no live merchant record exists (dual provision never finished on live); recovery: re-run create_merchant_account without a merchantId, which finds this merchant and creates the missing live copy with the details the sandbox copy holds \u2014 go_live cannot fix this and fails while the live twin is missing. ' + IDENTITY_VERIFICATION_RULE + ' identityVerification is the KYC state: "not_started", "pending", "in_review", "verified" or "rejected".',
   [MCP_TOOL_NAMES.GO_LIVE]: 'IRREVERSIBLE. Promote a sandbox merchant to live by setting liveMerchantId (Merchant Go-Live). This is one-way: it assigns merchant-of-record liability and notifies KYC on the live backend, and there is no tool that undoes it. Confirm with the user before calling it. Validates deployment readiness (sandbox merchant exists, not linked to a different live id, live twin reachable), marks the sandbox merchant live with the dual-provision twin id, then best-effort notifies KYC on the live backend. Pass dryRun: true to run exactly those readiness checks and stop before anything is written \u2014 the response then carries dryRun: true, and its absence is your proof that a real promotion happened. Unknown arguments are rejected rather than ignored, so a guessed safety flag fails loudly instead of being silently dropped. Idempotent: a call for a merchant that is already live changes nothing and returns alreadyLive: true, so there is never a reason to call it twice. The response carries activationStatus, the same shape get_merchant_activation_status returns ("verification_pending" right after promotion until identity verification completes; omitted only when the live status cannot be read), and a real call also returns nextSteps to relay to the user. ' + LIVE_CATALOG_RULE + " " + IDENTITY_VERIFICATION_RULE + ' The identity-verification link goes by SMS to the merchant phone, or by email when there is no dialable phone; kycNotify.phoneIssue "invalid" means the phone number cannot be dialled, so tell the user it is invalid. Distinct from get_merchant_activation_status (activation and identity-verification status) and from ApiKeyEnvironment.',
   [MCP_TOOL_NAMES.SEARCH_PAYMENTS_AI_DOCS]: "Search the PAI Managed documentation knowledge base to find guides, API references, UI walkthroughs, and feature explanations. Returns matching sections with titles and direct documentation links. Use this tool to understand how PAI Managed works, find step-by-step instructions for dashboard tasks, or locate specific features such as creating a merchant account (phone / E.164), go-live, creating products, configuring plans, or generating checkout links.",
   [MCP_TOOL_NAMES.CREATE_PRODUCT]: "Create a product with one or more pricing plans for a merchant on the PAI Managed platform. Product and checkout mutations target sandbox until go_live. Products represent digital offerings (software, subscriptions, services) that customers can purchase via a checkout link. Each plan defines the price (" + PRICE_UNITS + "), billing type (one-time, recurring, or free-access), and billing period. " + CREATE_PRODUCT_PLAN_BOUNDS + " " + CREATE_PRODUCT_STATUS_NOTE + " " + CREATE_PRODUCT_COPY_CAPS + " Returns the product ID, the plan IDs, and ready-to-open hosted-checkout URLs: `checkoutUrl` for the first created plan and `planCheckoutUrls` (one `{planId, checkoutUrl}` entry per created plan) \u2014 do not construct them yourself. The URLs already reflect the merchant's go-live status, not your credentials: sandbox (`?isSandbox=true`) before go_live, live (no query param) once go_live has succeeded \u2014 nothing to switch on your side. " + CREATE_PRODUCT_STORED_PLANS + " Product images are not supported on create \u2014 after success, call get_product_image_upload_url with the returned id as productId, POST the file bytes (multipart/form-data) to the returned URL, then call confirm_product_image with the returned key.",
-  [MCP_TOOL_NAMES.CREATE_ORDER]: "Create a payable order for a merchant on PAI Managed. Use create_order when the buyer pays for two or more items, or when you set the price yourself. Use the checkoutUrl from create_product or list_products for a single catalogue plan. Provide merchantId, currency (3 letters, for example usd), and items. A catalogue item is { planId, quantity }. A caller-priced item is { label, unitPrice, quantity, type } where type is one_time or recurring; a recurring caller-priced item also needs billingPeriod (day, week, month, or year) and periodLength. unitPrice is decimal dollars, not cents (10 means $10.00). " + CREATE_ORDER_BOUNDS + ' Optional idempotencyKey: repeating the same key returns the same orderId; omitting it creates a new order. Returns orderId and checkoutUrl \u2014 use the URL verbatim, do not construct it yourself. The URL already reflects the merchant\'s go-live status: sandbox (`?isSandbox=true`) before go_live, live (no query param) once go_live has succeeded. Requires the "checkout:write" scope.',
+  [MCP_TOOL_NAMES.CREATE_ORDER]: "Create a payable order for a merchant on PAI Managed. Use create_order when the buyer pays for two or more items, or when you set the price yourself. Use the checkoutUrl from create_product or list_products for a single catalogue plan. Provide merchantId, currency (3 letters, for example usd), and items. A catalogue item is { planId, quantity }. A caller-priced item is { label, unitPrice, quantity, type } where type is one_time or recurring; a recurring caller-priced item also needs billingPeriod (day, week, month, or year) and periodLength. unitPrice is decimal dollars, not cents (10 means $10.00). " + CREATE_ORDER_BOUNDS + CREATE_ORDER_METADATA + ' Optional idempotencyKey: repeating the same key returns the same orderId; omitting it creates a new order. Returns orderId and checkoutUrl \u2014 use the URL verbatim, do not construct it yourself. The URL already reflects the merchant\'s go-live status: sandbox (`?isSandbox=true`) before go_live, live (no query param) once go_live has succeeded. Requires the "checkout:write" scope.',
   [MCP_TOOL_NAMES.GET_PRODUCT_IMAGE_UPLOAD_URL]: 'Get a presigned POST policy to upload a product image directly to storage \u2014 the image bytes never pass through the tool call, and S3 enforces the 5 MB cap at upload time via `content-length-range` (oversized bodies get a 403 from S3, not the backend). Use this on any surface that can issue an HTTP multipart/form-data POST (CLI, agent, dashboard). The product must already exist (call create_product first). Provide merchantId, productId, fileName, and mimeType (image/png, image/jpeg, image/jpg, or image/webp). Returns { url, fields, key, expiresIn }: issue an HTTP POST to `url` with Content-Type: multipart/form-data. Add every entry from `fields` as a form field FIRST, then add the `file` field last (S3 requires the file field last), e.g. `curl -X POST <all -F fields...> -F "file=@./logo.png" "<url>"`. Then call confirm_product_image with the returned key to validate and attach the image.',
   [MCP_TOOL_NAMES.CONFIRM_PRODUCT_IMAGE]: "Confirm a product image uploaded via a presigned POST policy from get_product_image_upload_url. Call this after the multipart/form-data POST succeeds. Provide merchantId, productId, and the key returned by get_product_image_upload_url. The backend validates the stored object (format, size, magic bytes) and attaches it to the product. Returns { imageUrl } for verification. Replaces any existing product image.",
   [MCP_TOOL_NAMES.LIST_PRODUCTS]: "List products and pricing plans for a merchant on PAI Managed. Returns paginated products; each product carries a ready-to-open hosted-checkout `checkoutUrl`, and each plan summary (planId, name, amount, currency, `price` formatted as the checkout shows it, type, and for recurring plans billingPeriod, periodLength and freeTrial) carries its own `checkoutUrl` \u2014 use those directly, do not construct them yourself. The URLs already reflect the merchant's go-live status, not your credentials: sandbox (`?isSandbox=true`) before go_live, live (no query param) once go_live has succeeded \u2014 nothing to switch on your side. Optional filters: q (name search), status (draft|active|archived), type (one-time|recurring|free-access), dateRangeStart/dateRangeEnd, page, limit. Use before create_product when you need existing productId/planId values, or to share checkout links for plans that already exist. Targets sandbox until go_live, same as other product tools.",
@@ -25471,7 +25527,7 @@ var SOLO_TOOL_DESCRIPTION_OVERRIDES = {
   [MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS]: 'Get the production activation status of a merchant account on this sandbox MCP URL. Live promotion is not available on this URL, so the status you will typically see is "pending". Returns { status }. status "pending": the merchant has not been promoted to live; connect to the live MCP URL to promote it \u2014 polling this tool on the sandbox URL will not change it. status "verification_pending": the merchant is promoted to live and identity verification (KYC) is not confirmed; follow verification on the live MCP URL, which also reports the identity-verification state. status "active": live and identity verified; connect to the live MCP URL for live operations. status "not_provisioned": no merchant record exists on sandbox; recovery: connect to the live MCP URL and re-run create_merchant_account there without a merchantId, which creates the missing sandbox copy with the details the live copy holds.',
   [MCP_TOOL_NAMES.SEARCH_PAYMENTS_AI_DOCS]: "Search the PAI Managed documentation knowledge base to find guides, API references, UI walkthroughs, and feature explanations. Returns matching sections with titles and direct documentation links. Use this tool to understand how PAI Managed works, find step-by-step instructions for dashboard tasks, or locate specific features such as creating a merchant account (phone / E.164), creating products, configuring plans, or generating checkout links. This sandbox MCP URL cannot call go_live; product and checkout writes stay in sandbox.",
   [MCP_TOOL_NAMES.CREATE_PRODUCT]: "Create a product with one or more pricing plans for a merchant on Payments AI sandbox. Product and checkout mutations stay on sandbox on this MCP URL. Products represent digital offerings (software, subscriptions, services) that customers can purchase via a checkout link. Each plan defines the price (" + PRICE_UNITS + "), billing type (one-time, recurring, or free-access), and billing period. " + CREATE_PRODUCT_PLAN_BOUNDS + " " + CREATE_PRODUCT_STATUS_NOTE + " " + CREATE_PRODUCT_COPY_CAPS + " Returns the product ID, the plan IDs, and ready-to-open hosted-checkout URLs: `checkoutUrl` for the first created plan and `planCheckoutUrls` (one `{planId, checkoutUrl}` entry per created plan) \u2014 do not construct them yourself. The URLs are sandbox checkout links (`?isSandbox=true`). " + CREATE_PRODUCT_STORED_PLANS + " " + SANDBOX_TEST_CARD_NOTE + " Product images are not supported on create \u2014 after success, call get_product_image_upload_url with the returned id as productId, POST the file bytes (multipart/form-data) to the returned URL, then call confirm_product_image with the returned key.",
-  [MCP_TOOL_NAMES.CREATE_ORDER]: "Create a payable order for a merchant on Payments AI sandbox. Use create_order when the buyer pays for two or more items, or when you set the price yourself. Use the checkoutUrl from create_product or list_products for a single catalogue plan. Provide merchantId, currency (3 letters, for example usd), and items. A catalogue item is { planId, quantity }. A caller-priced item is { label, unitPrice, quantity, type } where type is one_time or recurring; a recurring caller-priced item also needs billingPeriod (day, week, month, or year) and periodLength. unitPrice is decimal dollars, not cents (10 means $10.00). " + CREATE_ORDER_BOUNDS + ' Optional idempotencyKey: repeating the same key returns the same orderId; omitting it creates a new order. Returns orderId and checkoutUrl \u2014 use the URL verbatim, do not construct it yourself. The URL is a sandbox checkout link (`?isSandbox=true`). Requires the "checkout:write" scope. Stays on sandbox on this MCP URL. ' + SANDBOX_TEST_CARD_NOTE,
+  [MCP_TOOL_NAMES.CREATE_ORDER]: "Create a payable order for a merchant on Payments AI sandbox. Use create_order when the buyer pays for two or more items, or when you set the price yourself. Use the checkoutUrl from create_product or list_products for a single catalogue plan. Provide merchantId, currency (3 letters, for example usd), and items. A catalogue item is { planId, quantity }. A caller-priced item is { label, unitPrice, quantity, type } where type is one_time or recurring; a recurring caller-priced item also needs billingPeriod (day, week, month, or year) and periodLength. unitPrice is decimal dollars, not cents (10 means $10.00). " + CREATE_ORDER_BOUNDS + CREATE_ORDER_METADATA + ' Optional idempotencyKey: repeating the same key returns the same orderId; omitting it creates a new order. Returns orderId and checkoutUrl \u2014 use the URL verbatim, do not construct it yourself. The URL is a sandbox checkout link (`?isSandbox=true`). Requires the "checkout:write" scope. Stays on sandbox on this MCP URL. ' + SANDBOX_TEST_CARD_NOTE,
   [MCP_TOOL_NAMES.LIST_PRODUCTS]: "List products and pricing plans for a merchant on Payments AI sandbox. Returns paginated products; each product carries a ready-to-open hosted-checkout `checkoutUrl`, and each plan summary (planId, name, amount, currency, `price` formatted as the checkout shows it, type, and for recurring plans billingPeriod, periodLength and freeTrial) carries its own `checkoutUrl` \u2014 use those directly, do not construct them yourself. The URLs are sandbox checkout links (`?isSandbox=true`). Optional filters: q (name search), status (draft|active|archived), type (one-time|recurring|free-access), dateRangeStart/dateRangeEnd, page, limit. Use before create_product when you need existing productId/planId values, or to share checkout links for plans that already exist. Stays on sandbox on this MCP URL, same as other product tools.",
   [MCP_TOOL_NAMES.LIST_TRANSACTIONS]: LIST_TRANSACTIONS_SUMMARY + ' This sandbox MCP URL returns sandbox transactions only; deployment "live" is refused. The top-level deployment names where it searched; an empty data list means no transaction matches there, not an error. ' + TRANSACTION_STATUS_RULE + " " + TRANSACTION_REFUND_RULE + " " + TRANSACTION_SCOPE_RULE,
   [MCP_TOOL_NAMES.GET_TRANSACTION]: GET_TRANSACTION_DETAIL + ' This sandbox MCP URL returns sandbox transactions only; deployment "live" is refused. ' + TRANSACTION_STATUS_RULE + " " + TRANSACTION_REFUND_RULE + " " + TRANSACTION_SCOPE_RULE
@@ -25583,7 +25639,7 @@ var QUICKSTART_SKILL_SECTIONS = [
   "`merchants` list means connected with no merchant yet. If the call is denied for",
   "`merchant:read`, name that missing scope; do not say disconnected.",
   "",
-  "Ask for business **name**, **email**, and **phone** in E.164 (`+14155552671`). Call `create_merchant_account`. Show `merchantId`.",
+  "Ask for business **name** and **email**. **Phone** is optional: include it (the user's own mobile, E.164, e.g. `+14155552671`) only if they offer one; never invent a placeholder, and omit it otherwise. Call `create_merchant_account`. Show `merchantId`.",
   "",
   "### A2. Product",
   "",
@@ -25597,15 +25653,9 @@ var QUICKSTART_SKILL_SECTIONS = [
   "",
   "### A3. Checkout URL",
   "",
-  "Sandbox testing:",
-  "",
-  "`{{MANAGED_API_HOST_URL}}/payment/{planId}?isSandbox=true`",
-  "",
-  "Live (only after `go_live` **and** re-running `create_product` there \u2014 `go_live` does not create the plan on live, so this URL 404s until you do):",
+  "Use the link the tool returns verbatim: `planCheckoutUrls[i].checkoutUrl` from `create_product` or `plans[i].checkoutUrl` from `list_products`. The top-level `checkoutUrl` is the first plan's link only. Never build a checkout URL from a `planId`.",
   "",
-  "`{{MANAGED_API_HOST_URL}}/payment/{planId}`",
-  "",
-  "`list_products` also returns `checkoutUrl` per plan. A sandbox checkout link never becomes this URL on its own; it keeps `?isSandbox=true` forever.",
+  "Sandbox and live are separate backends and `go_live` does not copy products or plans: sandbox plans do not exist on live. To get a live link, call `create_product` again after `go_live` and use the `checkoutUrl` it returns. A sandbox checkout link keeps `?isSandbox=true` forever and never becomes a live link.",
   "",
   "Test card (Sandbox): `4242 4242 4242 4242`, any future expiry, any CVC. Refused-payment card (Sandbox): `4000 0000 0000 0002`. Give both to the user with every sandbox checkout link. Test cards never work on Live: live checkout links take real cards only.",
   "",
@@ -25630,24 +25680,26 @@ var QUICKSTART_SKILL_SECTIONS = [
   "",
   "## Tools",
   "",
-  "| Tool                             | Use                                                     |",
-  "| -------------------------------- | ------------------------------------------------------- |",
-  "| `whoami`                         | `userId`, `scopes`, `host`, `endpoint`; any valid token |",
-  "| `search_payments_ai_docs`        | Search developer docs                                   |",
-  "| `get_my_merchant`                | Owned merchants                                         |",
-  "| `create_merchant_account`        | Dual-provision live + sandbox merchant                  |",
-  "| `get_merchant_activation_status` | Activation status (see below)                           |",
-  "| `go_live`                        | Promote to live; a repeat returns current status        |",
-  "| `create_product`                 | Product + plans (sandbox until go-live)                 |",
-  "| `create_order`                   | Multi-item or caller-priced checkout                    |",
-  "| `list_products`                  | List products, plans, checkout URLs                     |",
-  "| `list_transactions`              | Look up transactions (needs `transaction:read`)         |",
-  "| `get_transaction`                | One transaction's details and line items                |",
-  "| `get_product_image_upload_url`   | Presigned POST for product image                        |",
-  "| `confirm_product_image`          | Attach uploaded product image                           |",
-  "| `get_checkout_customization`     | Read hosted checkout branding                           |",
-  "| `update_checkout_customization`  | Merge-update branding                                   |",
-  "| `set_checkout_logo`              | Mint \u2192 PUT \u2192 confirm checkout logo                      |",
+  "| Tool                             | Use                                                                          |",
+  "| -------------------------------- | ---------------------------------------------------------------------------- |",
+  "| `whoami`                         | `userId`, `scopes`, `host`, `endpoint`; any valid token                      |",
+  "| `search_payments_ai_docs`        | Search developer docs                                                        |",
+  "| `get_my_merchant`                | Owned merchants                                                              |",
+  "| `create_merchant_account`        | Dual-provision live + sandbox merchant                                       |",
+  "| `get_merchant_activation_status` | Activation status (see below)                                                |",
+  "| `go_live`                        | Promote to live; a repeat returns current status                             |",
+  "| `create_product`                 | Product + plans (sandbox until go-live)                                      |",
+  "| `create_order`                   | Multi-item or caller-priced checkout                                         |",
+  "| `update_product`                 | Merge-update a product's name, description or status                         |",
+  "| `update_plan`                    | Merge-update a plan's name, description, price, billing period or free trial |",
+  "| `list_products`                  | List products, plans, checkout URLs                                          |",
+  "| `list_transactions`              | Look up transactions (needs `transaction:read`)                              |",
+  "| `get_transaction`                | One transaction's details and line items                                     |",
+  "| `get_product_image_upload_url`   | Presigned POST for product image                                             |",
+  "| `confirm_product_image`          | Attach uploaded product image                                                |",
+  "| `get_checkout_customization`     | Read hosted checkout branding                                                |",
+  "| `update_checkout_customization`  | Merge-update branding                                                        |",
+  "| `set_checkout_logo`              | Mint \u2192 PUT \u2192 confirm checkout logo                                           |",
   "",
   "### Activation status",
   "",
@@ -25715,6 +25767,115 @@ async function resolveTransactionLookupBackend(input2) {
   return { error: NOT_LIVE_YET_ERROR };
 }
 
+// src/auth/mcp-auth-rejection.ts
+var MCP_AUTH_ERROR_DOC_SLUG = {
+  missing_token: "missing-token",
+  invalid_token: "invalid-token",
+  token_expired: "token-expired"
+};
+var DEPLOYMENT_LABEL = {
+  sandbox: "Sandbox",
+  live: "Live"
+};
+var MCP_TOKENS_DASHBOARD_PATH = "Developer Tools \u2192 MCP Tokens";
+var MESSAGE_BY_CODE = {
+  missing_token: () => `No MCP credential was sent. Send an "Authorization: Bearer <token>" header with a pai_mcp_ token from ${MCP_TOKENS_DASHBOARD_PATH}, or connect with OAuth.`,
+  invalid_token: (context) => {
+    const here = DEPLOYMENT_LABEL[context.serverDeployment];
+    return `This MCP token is not valid on this ${here} MCP URL: it is unknown, revoked or malformed. Tokens generated on the ${here} tab of ${MCP_TOKENS_DASHBOARD_PATH} work only with the ${here} MCP URL. Generate a new token there.`;
+  },
+  token_expired: (context) => `${context.expiredMessage ?? MCP_SESSION_EXPIRED_MESSAGE} How to reconnect: ${context.connectPageUrl}`,
+  token_validation_unavailable: () => "The MCP token could not be validated because the backend is unavailable. Retry in a moment; do not generate a new token."
+};
+function resolveDocsBase(docsBaseUrl2) {
+  return (docsBaseUrl2 ?? DEFAULT_DOCS_BASE_URL).replace(/\/+$/, "");
+}
+function buildMcpAuthErrorDocUrl(code, docsBaseUrl2) {
+  const base = resolveDocsBase(docsBaseUrl2);
+  const slug = MCP_AUTH_ERROR_DOC_SLUG[code];
+  return slug === void 0 ? `${base}/errors` : `${base}/errors/${slug}`;
+}
+function buildMcpConnectPageUrl(docsBaseUrl2) {
+  return `${resolveDocsBase(docsBaseUrl2)}/connect`;
+}
+function buildMcpConnectDiagnosticsUrl(mcpPath2, mcpPublicUrl2) {
+  const endpoint = mcpPublicUrl2 === void 0 ? mcpPath2 : mcpPublicUrl2.replace(/\/+$/, "");
+  return `${endpoint}${CONNECT_DIAGNOSTICS_PATH_SUFFIX}`;
+}
+function buildMcpAuthRejectionBody(code, context, links) {
+  const connectPageUrl = buildMcpConnectPageUrl(links.docsBaseUrl);
+  return {
+    statusCode: 401,
+    error: "Unauthorized",
+    code,
+    message: MESSAGE_BY_CODE[code]({ ...context, connectPageUrl }),
+    docUrl: buildMcpAuthErrorDocUrl(code, links.docsBaseUrl),
+    connectDiagnosticsUrl: links.connectDiagnosticsUrl,
+    connectPageUrl
+  };
+}
+function formatMcpAuthRejectionLog(rejection, mode) {
+  return JSON.stringify({
+    event: "mcp.auth_rejected",
+    code: rejection.code,
+    reason: rejection.reason,
+    mode
+  });
+}
+
+// src/auth/credential-expiry.ts
+var SECONDS_PER_HOUR = 60 * 60;
+var SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR;
+var NO_EXPIRY = {
+  credentialExpiresAt: null,
+  credentialExpiresInSeconds: null,
+  warning: void 0
+};
+function plural2(count, unit) {
+  return `${count} ${unit}${count === 1 ? "" : "s"}`;
+}
+function describeRemaining(seconds) {
+  if (seconds >= SECONDS_PER_DAY) {
+    return plural2(Math.floor(seconds / SECONDS_PER_DAY), "day");
+  }
+  if (seconds >= SECONDS_PER_HOUR) {
+    return plural2(Math.floor(seconds / SECONDS_PER_HOUR), "hour");
+  }
+  return "less than an hour";
+}
+function formatWarningMessage(expiresAt, seconds, reapproveUrl) {
+  if (seconds === 0) {
+    return `This MCP credential has expired (${expiresAt}). Tell the user to re-approve this connection so it works again: ${reapproveUrl}`;
+  }
+  return `This MCP credential expires in ${describeRemaining(seconds)} (${expiresAt}). Tell the user to re-approve this connection before then so it keeps working: ${reapproveUrl}`;
+}
+function resolveCredentialExpiry(input2) {
+  const { expiresAt, now, docsBaseUrl: docsBaseUrl2, warnsBeforeExpiry } = input2;
+  if (expiresAt === void 0) {
+    return NO_EXPIRY;
+  }
+  const remainingMs = Date.parse(expiresAt) - now.getTime();
+  const seconds = Math.max(0, Math.floor(remainingMs / 1e3));
+  if (!warnsBeforeExpiry || seconds > CREDENTIAL_EXPIRY_WARNING_WINDOW_SECONDS) {
+    return {
+      credentialExpiresAt: expiresAt,
+      credentialExpiresInSeconds: seconds,
+      warning: void 0
+    };
+  }
+  const reapproveUrl = buildMcpConnectPageUrl(docsBaseUrl2);
+  return {
+    credentialExpiresAt: expiresAt,
+    credentialExpiresInSeconds: seconds,
+    warning: {
+      credentialExpiresAt: expiresAt,
+      credentialExpiresInSeconds: seconds,
+      reapproveUrl,
+      message: formatWarningMessage(expiresAt, seconds, reapproveUrl)
+    }
+  };
+}
+
 // src/tools/tool-required-scopes.ts
 var ANY_VALID_TOKEN = /* @__PURE__ */ Symbol("ANY_VALID_TOKEN");
 var TOOL_REQUIRED_SCOPE = {
@@ -25787,6 +25948,36 @@ function filterToolsByScope(server, tokenPayload) {
   });
 }
 
+// src/tools/credential-expiry-warning.ts
+function hasContentBlocks(result2) {
+  return typeof result2 === "object" && result2 !== null && Array.isArray(result2.content);
+}
+function withCredentialExpiryWarning(result2, warning) {
+  if (!hasContentBlocks(result2)) {
+    return result2;
+  }
+  return {
+    ...result2,
+    content: [...result2.content, { type: "text", text: warning.message }],
+    // eslint-disable-next-line no-underscore-dangle -- MCP names the result metadata field `_meta`
+    _meta: { ...result2._meta, [CREDENTIAL_EXPIRY_WARNING_META_KEY]: warning }
+  };
+}
+function attachCredentialExpiryWarning(server, warning) {
+  if (!warning) {
+    return;
+  }
+  const protocol = server.server;
+  const callTool = protocol._getRequestHandler?.("tools/call");
+  if (!callTool) {
+    throw new Error("The SDK tools/call handler is not available; register tools before wrapping");
+  }
+  server.server.setRequestHandler(
+    "tools/call",
+    async (request, ctx) => withCredentialExpiryWarning(await callTool(request, ctx), warning)
+  );
+}
+
 // src/tools/product/build-plan-checkout-url.ts
 var CHECKOUT_SANDBOX_QUERY_PARAM = "isSandbox";
 function buildPlanCheckoutUrl(params) {
@@ -26479,6 +26670,8 @@ var ORDER_DOC_SECTIONS = [
 
 **create_order** takes \`merchantId\`, \`currency\` (3 letters, for example usd), and \`items\`. A catalogue item is \`{ planId, quantity }\`. A caller-priced item is \`{ label, unitPrice, quantity, type }\` where \`type\` is \`one_time\` or \`recurring\`. A recurring caller-priced item also needs \`billingPeriod\` (\`day\`, \`week\`, \`month\`, or \`year\`) and \`periodLength\`. \`unitPrice\` is decimal dollars, not cents. Optional \`idempotencyKey\`: the same key returns the same \`orderId\`; omitting it creates a new order.
 
+Optional \`metadata\` stores your own references on the order, for example \`{ "cf_order_id": "A-1001" }\`: a flat map of string keys to string values, at most ${MAX_ORDER_METADATA_KEYS} keys, each key 1-${MAX_ORDER_METADATA_KEY_LENGTH} characters, each value at most ${MAX_ORDER_METADATA_VALUE_LENGTH} characters. Keys and values are kept and returned in \`metadata\` exactly as sent (\`cf_order_id\`, \`cfOrderId\` and \`Order-Ref\` stay distinct), and payment and subscription webhooks for the order carry the same \`metadata\`. The buyer does not see them. Repeating an idempotencyKey returns the original order, including its original metadata; metadata on the repeat is ignored. The Public API create-order endpoint takes the same \`metadata\`.
+
 The tool returns \`orderId\` and \`checkoutUrl\`. Use \`checkoutUrl\` verbatim \u2014 do not build one yourself. Sandbox URLs carry \`?isSandbox=true\`. The merchant's go-live status selects sandbox versus live. Requires the \`checkout:write\` scope.`
   }
 ];
@@ -26629,7 +26822,7 @@ function runSearchPaymentsAiDocsHandler(query) {
 // src/tools/connection/connection-proof.ts
 var CONNECTION_PROOF_UNAVAILABLE_ERROR = "Could not prove this MCP connection: the server has no validated token or public MCP URL for this request. Contact Payments AI support.";
 function buildConnectionProof(input2) {
-  const { payload, host: host2, endpoint } = input2;
+  const { payload, host: host2, endpoint, credentialExpiry } = input2;
   if (!payload || !host2 || !endpoint) {
     return void 0;
   }
@@ -26637,7 +26830,11 @@ function buildConnectionProof(input2) {
     userId: payload.userId,
     scopes: payload.scopes,
     host: host2,
-    endpoint
+    endpoint,
+    merchantIds: payload.merchantIds,
+    credentialExpiresAt: credentialExpiry.credentialExpiresAt,
+    credentialExpiresInSeconds: credentialExpiry.credentialExpiresInSeconds,
+    ...credentialExpiry.warning ? { credentialExpiryWarning: credentialExpiry.warning } : {}
   });
   return parsed.success ? parsed.data : void 0;
 }
@@ -27002,7 +27199,7 @@ function toolError(text) {
   };
 }
 function resolveBackendClients(options2) {
-  if (options2?.backendClients) {
+  if (options2.backendClients) {
     return {
       sandbox: options2.backendClients.sandbox,
       live: options2.backendClients.live
@@ -27025,12 +27222,18 @@ async function resolveProductCheckoutRoute(sandbox, live, merchantId) {
 function registerTools(server, options2) {
   const { sandbox: sandboxBackendClient, live: liveBackendClient } = resolveBackendClients(options2);
   const dualBackendClients = sandboxBackendClient ? { sandbox: sandboxBackendClient, live: liveBackendClient } : void 0;
-  const deploymentRouter2 = options2?.deploymentRouter ?? (dualBackendClients && hasLiveBackend(dualBackendClients) ? createDualRouter(dualBackendClients) : void 0);
-  const serverDeployment = options2?.serverDeployment ?? deploymentRouter2?.serverDeployment;
-  const mcpTokenPayload = options2?.mcpTokenPayload;
-  const checkoutBaseUrl2 = options2?.checkoutBaseUrl ?? resolveCheckoutBaseUrl();
-  const dashboardUrl = options2?.dashboardUrl;
+  const deploymentRouter2 = options2.deploymentRouter ?? (dualBackendClients && hasLiveBackend(dualBackendClients) ? createDualRouter(dualBackendClients) : void 0);
+  const serverDeployment = options2.serverDeployment ?? deploymentRouter2?.serverDeployment;
+  const mcpTokenPayload = options2.mcpTokenPayload;
+  const checkoutBaseUrl2 = options2.checkoutBaseUrl ?? resolveCheckoutBaseUrl();
+  const dashboardUrl = options2.dashboardUrl;
   const toolDescriptions = resolveToolDescriptions(deploymentRouter2?.mode ?? "dual");
+  const credentialExpiry = resolveCredentialExpiry({
+    expiresAt: mcpTokenPayload?.expiresAt,
+    now: options2.now(),
+    docsBaseUrl: options2.docsBaseUrl,
+    warnsBeforeExpiry: mcpTokenPayload?.oauthIssued === true
+  });
   const denyForTool = (name) => scopeDenial(TOOL_REQUIRED_SCOPE[name], mcpTokenPayload, dashboardUrl);
   async function resolveCallerMerchantIds(router, payload) {
     const allowlist = await router.resolveMerchantAllowlist(payload);
@@ -27093,7 +27296,8 @@ function registerTools(server, options2) {
       return runWhoamiHandler({
         payload: mcpTokenPayload,
         host: serverDeployment,
-        endpoint: options2?.mcpPublicUrl
+        endpoint: options2.mcpPublicUrl,
+        credentialExpiry
       });
     }
   );
@@ -27703,6 +27907,7 @@ function registerTools(server, options2) {
     }
   );
   filterToolsByScope(server, mcpTokenPayload);
+  attachCredentialExpiryWarning(server, credentialExpiry.warning);
 }
 
 // src/http/connect-diagnostics/connect-diagnostics-intake.ts
@@ -28042,17 +28247,27 @@ function parseMcpTokenPayload(parsed) {
   if (typeof parsed !== "object" || parsed === null) {
     return void 0;
   }
-  const { userId, cognitoSub, merchantIds, scopes } = parsed;
+  const { userId, cognitoSub, merchantIds, scopes, expiresAt, oauthIssued } = parsed;
   if (typeof userId !== "string" || typeof cognitoSub !== "string" || !isStringArray(merchantIds)) {
     return void 0;
   }
+  const expiry = parseExpiresAt(expiresAt);
   return {
     userId,
     cognitoSub,
     merchantIds,
-    scopes: Array.isArray(scopes) ? scopes : null
+    scopes: Array.isArray(scopes) ? scopes : null,
+    oauthIssued: oauthIssued === true,
+    ...expiry === void 0 ? {} : { expiresAt: expiry }
   };
 }
+function parseExpiresAt(value) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const epochMs = Date.parse(value);
+  return Number.isNaN(epochMs) ? void 0 : new Date(epochMs).toISOString();
+}
 
 // src/auth/mcp-token-audience.ts
 function isTokenAudienceAccepted(audience, mcpPublicUrl2) {
@@ -28066,63 +28281,17 @@ function isTokenAudienceAccepted(audience, mcpPublicUrl2) {
   return canonicalAudience !== null && canonicalAudience === canonicalResourceUrl(mcpPublicUrl2);
 }
 
-// src/auth/mcp-auth-rejection.ts
-var MCP_AUTH_ERROR_DOC_SLUG = {
-  missing_token: "missing-token",
-  invalid_token: "invalid-token",
-  token_expired: "token-expired"
-};
-var DEPLOYMENT_LABEL = {
-  sandbox: "Sandbox",
-  live: "Live"
-};
-var MCP_TOKENS_DASHBOARD_PATH = "Developer Tools \u2192 MCP Tokens";
-var MESSAGE_BY_CODE = {
-  missing_token: () => `No MCP credential was sent. Send an "Authorization: Bearer <token>" header with a pai_mcp_ token from ${MCP_TOKENS_DASHBOARD_PATH}, or connect with OAuth.`,
-  invalid_token: (context) => {
-    const here = DEPLOYMENT_LABEL[context.serverDeployment];
-    return `This MCP token is not valid on this ${here} MCP URL: it is unknown, revoked or malformed. Tokens generated on the ${here} tab of ${MCP_TOKENS_DASHBOARD_PATH} work only with the ${here} MCP URL. Generate a new token there.`;
-  },
-  token_expired: (context) => context.expiredMessage ?? MCP_SESSION_EXPIRED_MESSAGE,
-  token_validation_unavailable: () => "The MCP token could not be validated because the backend is unavailable. Retry in a moment; do not generate a new token."
-};
-function resolveDocsBase(docsBaseUrl2) {
-  return (docsBaseUrl2 ?? DEFAULT_DOCS_BASE_URL).replace(/\/+$/, "");
-}
-function buildMcpAuthErrorDocUrl(code, docsBaseUrl2) {
-  const base = resolveDocsBase(docsBaseUrl2);
-  const slug = MCP_AUTH_ERROR_DOC_SLUG[code];
-  return slug === void 0 ? `${base}/errors` : `${base}/errors/${slug}`;
-}
-function buildMcpConnectPageUrl(docsBaseUrl2) {
-  return `${resolveDocsBase(docsBaseUrl2)}/connect`;
-}
-function buildMcpConnectDiagnosticsUrl(mcpPath2, mcpPublicUrl2) {
-  const endpoint = mcpPublicUrl2 === void 0 ? mcpPath2 : mcpPublicUrl2.replace(/\/+$/, "");
-  return `${endpoint}${CONNECT_DIAGNOSTICS_PATH_SUFFIX}`;
-}
-function buildMcpAuthRejectionBody(code, context, links) {
-  return {
-    statusCode: 401,
-    error: "Unauthorized",
-    code,
-    message: MESSAGE_BY_CODE[code](context),
-    docUrl: buildMcpAuthErrorDocUrl(code, links.docsBaseUrl),
-    connectDiagnosticsUrl: links.connectDiagnosticsUrl,
-    connectPageUrl: buildMcpConnectPageUrl(links.docsBaseUrl)
-  };
-}
-function formatMcpAuthRejectionLog(code, mode) {
-  return JSON.stringify({ event: "mcp.auth_rejected", code, mode });
-}
-
 // src/http/app.ts
 var LOCALHOST_BINDS = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
 var LOCALHOST_ALLOWED_HOSTS = ["127.0.0.1", "localhost", "::1", "[::1]"];
 var BEARER_PREFIX = "Bearer ";
 var MCP_TOKEN_FORMAT = /^pai_mcp_[0-9a-f]{64}$/;
-function reject(code, expiredMessage) {
-  return { ok: false, code, expiredMessage };
+function reject(code, options2 = {}) {
+  return {
+    ok: false,
+    rejection: { code, reason: options2.reason ?? code },
+    expiredMessage: options2.expiredMessage
+  };
 }
 function decideFromOutcome(token, outcome, mcpPublicUrl2) {
   if (outcome.ok) {
@@ -28130,7 +28299,7 @@ function decideFromOutcome(token, outcome, mcpPublicUrl2) {
   }
   switch (outcome.reason) {
     case "expired":
-      return reject("token_expired", outcome.expiredMessage);
+      return reject("token_expired", { expiredMessage: outcome.expiredMessage });
     case "unavailable":
       return reject("token_validation_unavailable");
     case "not_found":
@@ -28152,7 +28321,7 @@ async function authenticateMcpRequest(authHeader, validationClient, mcpPublicUrl
   }
   const token = authHeader.slice(BEARER_PREFIX.length);
   if (!MCP_TOKEN_FORMAT.test(token)) {
-    return reject("invalid_token");
+    return reject("invalid_token", { reason: "malformed_credential" });
   }
   const outcome = await validateMcpToken(token, validationClient);
   return decideFromOutcome(token, outcome, mcpPublicUrl2);
@@ -28182,7 +28351,8 @@ function createExpressApp(options2) {
     websiteUrl,
     checkoutBaseUrl: checkoutBaseUrl2,
     allowedMcpOriginHostnames = DEFAULT_ALLOWED_MCP_ORIGIN_HOSTNAMES,
-    deploymentRouter: deploymentRouterOption
+    deploymentRouter: deploymentRouterOption,
+    now = () => /* @__PURE__ */ new Date()
   } = options2;
   const deploymentRouter2 = deploymentRouterOption ?? (backendClients2 && hasLiveBackend(backendClients2) ? createDualRouter(backendClients2) : void 0);
   const tokenValidationClient = deploymentRouter2?.tokenValidationClient ?? backendClients2?.live ?? backendClients2?.sandbox;
@@ -28259,17 +28429,17 @@ function createExpressApp(options2) {
   const challengeScope = challengeOAuthScopes(deploymentRouter2).join(" ");
   const mcpOriginMiddleware = createMcpOriginMiddleware(allowedMcpOriginHostnames);
   const connectDiagnosticsUrl = buildMcpConnectDiagnosticsUrl(mcpPath2, mcpPublicUrl2);
-  const sendUnauthorized = (res, code, expiredMessage) => {
+  const sendUnauthorized = (res, rejection, expiredMessage) => {
     if (resourceMetadataUrl) {
       res.set(
         "WWW-Authenticate",
         `Bearer realm="PAI Managed MCP", resource_metadata="${resourceMetadataUrl}", scope="${challengeScope}"`
       );
     }
-    console.error(formatMcpAuthRejectionLog(code, routerMode));
+    console.error(formatMcpAuthRejectionLog(rejection, routerMode));
     res.status(401).json(
       buildMcpAuthRejectionBody(
-        code,
+        rejection.code,
         { serverDeployment, expiredMessage },
         { docsBaseUrl: docsBaseUrl2, connectDiagnosticsUrl }
       )
@@ -28289,7 +28459,7 @@ function createExpressApp(options2) {
       return;
     }
     if (!decision.ok) {
-      sendUnauthorized(res, decision.code, decision.expiredMessage);
+      sendUnauthorized(res, decision.rejection, decision.expiredMessage);
       return;
     }
     req.mcpTokenPayload = decision.payload;
@@ -28327,7 +28497,9 @@ function createExpressApp(options2) {
         checkoutBaseUrl: checkoutBaseUrl2,
         dashboardUrl: websiteUrl,
         mcpPublicUrl: mcpPublicUrl2,
-        serverDeployment
+        serverDeployment,
+        docsBaseUrl: docsBaseUrl2,
+        now
       });
       registerPrompts(server, {
         servesGoLive: servesGoLive(deploymentRouter2),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payments-ai/mcp",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "private": false,
   "description": "MCP for Payments AI",
   "repository": {