@payments-ai/mcp 1.11.1 → 1.12.3

package/dist/main.http.js

@@ -105,8 +105,23 @@ function normalizeValidatedHttpBaseUrl(trimmed, envName) {
   const pathname = parsed.pathname.replace(/\/+$/, "");
   return `${parsed.origin}${pathname}`;
 }
-function readRequiredDualBackendUrlConfig(env = process.env) {
+var MCP_DEPLOYMENT_MODE_VALUES = ["dual", "solo"];
+function readMcpDeploymentMode(env = process.env) {
+  const raw = env.MCP_DEPLOYMENT_MODE?.trim();
+  if (!raw) {
+    return "dual";
+  }
+  if (!MCP_DEPLOYMENT_MODE_VALUES.includes(raw)) {
+    throw new Error(`MCP_DEPLOYMENT_MODE must be one of: ${MCP_DEPLOYMENT_MODE_VALUES.join(", ")}`);
+  }
+  return raw;
+}
+function readBackendUrlConfig(mode, env = process.env) {
   const sandboxUrl = readRequiredHttpBaseUrlFromEnv("BACKEND_SANDBOX_URL", env);
+  if (mode === "solo") {
+    const liveUrl2 = env.BACKEND_LIVE_URL?.trim();
+    return liveUrl2 ? { sandboxUrl, liveUrl: normalizeValidatedHttpBaseUrl(liveUrl2, "BACKEND_LIVE_URL") } : { sandboxUrl };
+  }
   const liveUrl = readRequiredHttpBaseUrlFromEnv("BACKEND_LIVE_URL", env);
   return { sandboxUrl, liveUrl };
 }
@@ -156,6 +171,9 @@ function readSentryTracesSampleRate(env = process.env) {
     defaultTracesSampleRateForAppEnv(appEnv)
   );
 }
+function isSentryEnabled(env = process.env) {
+  return Boolean(readSentryDsn(env));
+}
 function scrubAuthorizationHeader(headers) {
   if (!headers) {
     return headers;
@@ -204,6 +222,15 @@ function buildSentryInitOptions(env = process.env) {
 var options = buildSentryInitOptions();
 if (options) {
   Sentry.init(options);
+  console.error(
+    JSON.stringify({
+      event: "mcp.sentry_initialized",
+      environment: options.environment,
+      tracesSampleRate: options.tracesSampleRate
+    })
+  );
+} else {
+  console.error(JSON.stringify({ event: "mcp.sentry_disabled" }));
 }
 
 // src/shared/backend-user-error.ts
@@ -240,6 +267,34 @@ function readMcpKeyExpiredMessage(bodyText) {
   }
   return void 0;
 }
+var BUSINESS_NAME_TAKEN_CODE = "business_name_taken";
+var BUSINESS_NAME_TAKEN_RECOVERY = "Recovery: call create_merchant_account with a different unique name. Do not retry with the same name.";
+var DUAL_PROVISION_FINISH_RECOVERY = "Recovery: retry create_merchant_account with the same merchantId, name, and email to finish provisioning without creating a new id.";
+function extractClientErrorCode(bodyText) {
+  const trimmed = bodyText.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  try {
+    const json2 = JSON.parse(trimmed);
+    if (typeof json2.code === "string" && json2.code.trim()) {
+      return json2.code.trim();
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
+function formatCreateMerchantAccountBackendFailure(result, options2) {
+  const base = formatToolBackendFailure("create your merchant account", result);
+  const includeRecovery = options2?.includeRecovery ?? true;
+  const code = result.kind === "http_error" ? extractClientErrorCode(result.bodyText ?? "") : void 0;
+  if (code !== BUSINESS_NAME_TAKEN_CODE || !includeRecovery) {
+    return base;
+  }
+  return `${base}
+${BUSINESS_NAME_TAKEN_RECOVERY}`;
+}
 function extractClientErrorMessage(bodyText) {
   return withoutProviderBrandName(readClientErrorMessage(bodyText));
 }
@@ -301,6 +356,7 @@ ${result.message}`;
 // src/backend/backend-client.ts
 var BACKEND_HTTP_HEALTH_PATH = "/api/v1/health-checks/http";
 var BACKEND_CREATE_MERCHANT_ACCOUNT_PATH = "/api/v1/mcp/provision";
+var BACKEND_MCP_MY_MERCHANTS_PATH = "/api/v1/mcp/my-merchants";
 function backendCreateProductPath(merchantId) {
   return `/api/v1/mcp/merchants/${merchantId}/products`;
 }
@@ -341,6 +397,9 @@ function backendConfirmCheckoutLogoPath(merchantId) {
   return `/api/v1/mcp/merchants/${merchantId}/checkout/logo/confirm`;
 }
 var DEFAULT_TIMEOUT_MS = 1e4;
+function hasLiveBackend(clients) {
+  return clients.live !== void 0;
+}
 function normalizeBackendBaseUrl(baseUrl) {
   return baseUrl.replace(/\/+$/, "");
 }
@@ -494,10 +553,13 @@ function createBackendClient(baseUrl, options2, env = process.env) {
   });
 }
 function createDualBackendClients(config2, options2, env = process.env) {
-  return {
-    sandbox: createBackendClient(config2.sandboxUrl, options2, env),
-    live: createBackendClient(config2.liveUrl, options2, env)
+  const clients = {
+    sandbox: createBackendClient(config2.sandboxUrl, options2, env)
   };
+  if (config2.liveUrl) {
+    return { ...clients, live: createBackendClient(config2.liveUrl, options2, env) };
+  }
+  return clients;
 }
 function createDualBackendClientsFromEnv(explicit, env = process.env) {
   const sandboxUrl = explicit?.sandboxUrl?.trim() || resolveBackendSandboxUrl(env);
@@ -511,19 +573,43 @@ function createDualBackendClientsFromEnv(explicit, env = process.env) {
   return createDualBackendClients({ sandboxUrl, liveUrl }, void 0, env);
 }
 
-// src/http/app.ts
-import cors from "cors";
-import { createMcpHandler } from "@modelcontextprotocol/server";
-import { toNodeHandler } from "@modelcontextprotocol/node";
-import {
-  createMcpExpressApp,
-  getOAuthProtectedResourceMetadataUrl,
-  mcpAuthMetadataRouter
-} from "@modelcontextprotocol/express";
+// src/backend/resolve-product-checkout-backend.ts
+function parseGoLiveStatusBody(bodyText) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyText);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null || !("liveMerchantId" in parsed)) {
+    return void 0;
+  }
+  const liveMerchantId = parsed.liveMerchantId;
+  if (liveMerchantId !== null && typeof liveMerchantId !== "string") {
+    return void 0;
+  }
+  if (typeof liveMerchantId === "string" && liveMerchantId.trim() === "") {
+    return void 0;
+  }
+  return { liveMerchantId };
+}
+async function resolveProductCheckoutBackend(clients, merchantId) {
+  const result = await clients.sandbox.get(backendGoLiveStatusPath(merchantId));
+  if (!result.ok) {
+    return { client: clients.sandbox, merchantId, deployment: "sandbox" };
+  }
+  const status = parseGoLiveStatusBody(result.bodyText);
+  if (!status || status.liveMerchantId === null) {
+    return { client: clients.sandbox, merchantId, deployment: "sandbox" };
+  }
+  return { client: clients.live, merchantId: status.liveMerchantId, deployment: "live" };
+}
+
+// src/tools/merchant/create-merchant-account.tool.ts
+import * as crypto from "node:crypto";
 
 // ../../packages/mcp-contracts/dist/tool-names.js
 var MCP_TOOL_NAMES = {
-  PAYMENTS_AI_HEALTH: "payments_ai_health",
   /** Discovery before creation — see PAIM-973; `create_merchant_account` points at it. */
   GET_MY_MERCHANT: "get_my_merchant",
   CREATE_MERCHANT_ACCOUNT: "create_merchant_account",
@@ -542,7 +628,6 @@ var MCP_TOOL_NAMES = {
 
 // ../../packages/mcp-contracts/dist/oauth-metadata.js
 var SUPPORTED_OAUTH_SCOPES = [
-  "health:read",
   "merchant:create",
   "merchant:read",
   "merchant:go_live",
@@ -552,6 +637,15 @@ var SUPPORTED_OAUTH_SCOPES = [
   "checkout:read",
   "checkout:write"
 ];
+var OAUTH_CONSENT_READ_SCOPES = [
+  "merchant:read",
+  "product:read",
+  "docs:read",
+  "checkout:read"
+];
+var DEFAULT_OAUTH_SCOPES = [
+  ...OAUTH_CONSENT_READ_SCOPES
+];
 var OAUTH_RESPONSE_TYPES_SUPPORTED = ["code"];
 var OAUTH_GRANT_TYPES_SUPPORTED = ["authorization_code"];
 var OAUTH_CODE_CHALLENGE_METHODS_SUPPORTED = ["S256"];
@@ -15290,7 +15384,7 @@ var mcpMerchantSummarySchema = external_exports.object({
 // ../../packages/mcp-contracts/dist/create-merchant-account.js
 var createMerchantAccountInputSchema = external_exports.object({
   name: external_exports.string().trim().min(1, {
-    message: "Provide a non-empty business or display name. Recovery: re-send the tool call with a visible label for the merchant account."
+    message: "Provide a non-empty business or display name that is unique across Payments AI. Recovery: pick a new name (for example add your company or a short suffix) and re-send the tool call."
   }),
   email: external_exports.email({
     error: "Provide a valid email. Recovery: check spelling, domain, and that the value is a single RFC-style address."
@@ -15327,8 +15421,17 @@ var activationStatusOutputSchema = external_exports.object({
 var goLiveInputSchema = external_exports.object({
   merchantId: external_exports.string().trim().min(1, {
     message: "Provide the merchant account identifier returned from create_merchant_account. Recovery: copy the merchantId from a prior successful create_merchant_account response (the same id exists on sandbox and live after dual provision)."
-  })
-});
+  }),
+  /**
+   * Run the readiness checks and stop before anything is written.
+   *
+   * This exists because an agent facing the only irreversible tool in the set
+   * reaches for the obvious hatch. Without it, `{ dryRun: true }` was accepted
+   * and silently dropped, so the caller believed it had simulated a promotion
+   * that had in fact just happened for real.
+   */
+  dryRun: external_exports.boolean().optional()
+}).strict();
 var goLiveKycNotifyChannelSchema = external_exports.enum(["sms", "email"]);
 var goLiveKycNotifyOutcomeSchema = external_exports.discriminatedUnion("status", [
   external_exports.object({ status: external_exports.literal("already_dispatched") }),
@@ -15345,7 +15448,13 @@ var goLiveKycNotifyOutcomeSchema = external_exports.discriminatedUnion("status",
 ]);
 var goLiveOutputSchema = external_exports.object({
   liveMerchantId: external_exports.string().min(1),
-  kycNotify: goLiveKycNotifyOutcomeSchema.optional()
+  kycNotify: goLiveKycNotifyOutcomeSchema.optional(),
+  /**
+   * Present and `true` only when the call was a dry run. Its absence is the
+   * caller's proof that the promotion actually happened, so it is never emitted
+   * as `false`.
+   */
+  dryRun: external_exports.literal(true).optional()
 });
 
 // ../../packages/mcp-contracts/dist/payments-ai-health.js
@@ -15458,83 +15567,6 @@ var setCheckoutLogoOutputSchema = external_exports.union([
   confirmCheckoutLogoOutputSchema
 ]);
 
-// src/load-package-meta.ts
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-var __dirname = dirname(fileURLToPath(import.meta.url));
-function readMcpServerVersion() {
-  const path2 = join(__dirname, "..", "package.json");
-  const raw = readFileSync(path2, "utf8");
-  const pkg = JSON.parse(raw);
-  return pkg.version ?? "0.0.0";
-}
-
-// src/observability/create-instrumented-mcp-server.ts
-import { McpServer } from "@modelcontextprotocol/server";
-var MCP_SERVER_NAME = "pai-managed-mcp-server";
-function createInstrumentedMcpServer(options2) {
-  const server = new McpServer({
-    name: MCP_SERVER_NAME,
-    version: options2.version
-  });
-  return Sentry.wrapMcpServerWithSentry(server, {
-    recordInputs: false,
-    recordOutputs: false
-  });
-}
-
-// src/backend/resolve-product-checkout-backend.ts
-function parseGoLiveStatusBody(bodyText) {
-  let parsed;
-  try {
-    parsed = JSON.parse(bodyText);
-  } catch {
-    return void 0;
-  }
-  if (typeof parsed !== "object" || parsed === null || !("liveMerchantId" in parsed)) {
-    return void 0;
-  }
-  const liveMerchantId = parsed.liveMerchantId;
-  if (liveMerchantId !== null && typeof liveMerchantId !== "string") {
-    return void 0;
-  }
-  if (typeof liveMerchantId === "string" && liveMerchantId.trim() === "") {
-    return void 0;
-  }
-  return { liveMerchantId };
-}
-async function resolveProductCheckoutBackend(clients, merchantId) {
-  const result = await clients.sandbox.get(backendGoLiveStatusPath(merchantId));
-  if (!result.ok) {
-    return { client: clients.sandbox, merchantId, deployment: "sandbox" };
-  }
-  const status = parseGoLiveStatusBody(result.bodyText);
-  if (!status || status.liveMerchantId === null) {
-    return { client: clients.sandbox, merchantId, deployment: "sandbox" };
-  }
-  return { client: clients.live, merchantId: status.liveMerchantId, deployment: "live" };
-}
-
-// src/tools/scope-denial.ts
-var DEVELOPER_TOOLS_PATH = "/developer-tools";
-function isScopeAllowed(required2, payload) {
-  if (!payload) return true;
-  if (payload.scopes === null) return true;
-  return payload.scopes.includes(required2);
-}
-function insufficientScopeMessage(required2, dashboardUrl) {
-  const location = dashboardUrl ? `at ${dashboardUrl.replace(/\/+$/, "")}${DEVELOPER_TOOLS_PATH}` : `under ${DEVELOPER_TOOLS_PATH}`;
-  return `Insufficient scope. This tool requires the '${required2}' scope, which this connection does not have. Recovery: re-authorize the connection requesting '${required2}', or mint a new MCP key that includes it in the Payments AI dashboard ${location}.`;
-}
-function scopeDenial(required2, payload, dashboardUrl) {
-  if (isScopeAllowed(required2, payload)) return void 0;
-  return {
-    isError: true,
-    content: [{ type: "text", text: insufficientScopeMessage(required2, dashboardUrl) }]
-  };
-}
-
 // src/shared/zod-format.ts
 function formatZodIssuesForTool(issues) {
   return issues.map((issue2) => {
@@ -15543,65 +15575,195 @@ function formatZodIssuesForTool(issues) {
   }).join("\n");
 }
 
-// src/tools/merchant/activation-status.tool.ts
-function stubStatusForAccount(merchantId) {
-  return merchantId.toLowerCase().includes("pending") ? "pending" : "not_provisioned";
-}
-function buildActivationStatusStub(input) {
-  return activationStatusOutputSchema.parse({
-    status: stubStatusForAccount(input.merchantId)
-  });
+// src/tools/merchant/create-merchant-account.tool.ts
+var randomUuidV7 = crypto.randomUUIDv7;
+var STUB_MERCHANT = {
+  merchantId: "01930000-0000-7000-8000-000000000001"
+};
+function buildCreateMerchantAccountStub(_input) {
+  return createMerchantAccountOutputSchema.parse(STUB_MERCHANT);
 }
-function runActivationStatusHandler(raw) {
-  const parsed = activationStatusInputSchema.safeParse(raw);
+function runCreateMerchantAccountHandler(raw) {
+  const parsed = createMerchantAccountInputSchema.safeParse(raw);
   if (!parsed.success) {
     return {
       ok: false,
-      errorText: `Invalid arguments for get_merchant_activation_status.
+      errorText: `Invalid arguments for create_merchant_account.
 ${formatZodIssuesForTool(parsed.error.issues)}`
     };
   }
-  return { ok: true, data: buildActivationStatusStub(parsed.data) };
+  return { ok: true, data: buildCreateMerchantAccountStub(parsed.data) };
 }
-async function runActivationStatusHandlerWithBackend(backendClient, input) {
-  const result = await backendClient.get(backendActivationStatusPath(input.merchantId));
+function formatDualProvisionPartialFailure(params) {
+  const livePart = params.live.ok ? "live: ok" : `live: ${params.live.errorText}`;
+  const sandboxPart = params.sandbox.ok ? "sandbox: ok" : `sandbox: ${params.sandbox.errorText}`;
+  return `Could not create your merchant account on both backends (partial failure).
+merchantId: ${params.merchantId}
+${livePart}
+${sandboxPart}
+${formatDualProvisionRecovery(params.live, params.sandbox)}`;
+}
+function sideErrorCode(side) {
+  return side.ok ? void 0 : side.code;
+}
+function formatDualProvisionRecovery(live, sandbox) {
+  if (live.ok || sandbox.ok) {
+    return DUAL_PROVISION_FINISH_RECOVERY;
+  }
+  if (sideErrorCode(live) === BUSINESS_NAME_TAKEN_CODE || sideErrorCode(sandbox) === BUSINESS_NAME_TAKEN_CODE) {
+    return BUSINESS_NAME_TAKEN_RECOVERY;
+  }
+  return DUAL_PROVISION_FINISH_RECOVERY;
+}
+function formatSandboxOnlyProvisionWarning(params) {
+  return `Warning: the sandbox copy of this merchant account was not created.
+sandbox: ${params.sandboxErrorText}
+The live merchant account exists and this merchantId is safe to use.
+Sandbox products and sandbox checkout links stay unavailable until this succeeds.
+` + DUAL_PROVISION_FINISH_RECOVERY;
+}
+function withMatchingId(side, merchantId) {
+  if (!side.ok || side.merchantId === merchantId) {
+    return side;
+  }
+  return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
+}
+function logDualProvisionOutcome(params) {
+  console.error("[create_merchant_account] dual-provision", {
+    merchantId: params.merchantId,
+    outcome: params.outcome,
+    live: params.live.ok ? "ok" : "error",
+    sandbox: params.sandbox.ok ? "ok" : "error",
+    liveError: params.live.ok ? void 0 : params.live.errorText,
+    sandboxError: params.sandbox.ok ? void 0 : params.sandbox.errorText
+  });
+}
+async function provisionOnBackend(backendClient, input, merchantId, identity) {
+  const result = await backendClient.post(BACKEND_CREATE_MERCHANT_ACCOUNT_PATH, {
+    name: input.name,
+    email: input.email,
+    ...input.phone ? { phone: input.phone } : {},
+    merchantId,
+    ...identity?.userId ? { userId: identity.userId } : {},
+    ...identity?.cognitoSub ? { cognitoSub: identity.cognitoSub } : {}
+  });
   if (!result.ok) {
     return {
       ok: false,
-      errorText: formatToolBackendFailure("load merchant activation status", result)
+      errorText: formatCreateMerchantAccountBackendFailure(result, { includeRecovery: false }),
+      code: result.kind === "http_error" ? extractClientErrorCode(result.bodyText ?? "") : void 0
     };
   }
   let parsedJson;
   try {
     parsedJson = JSON.parse(result.bodyText);
   } catch {
-    return {
-      ok: false,
-      errorText: UNEXPECTED_RESPONSE_ERROR
-    };
+    return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
   }
-  const out = activationStatusOutputSchema.safeParse(parsedJson);
+  const out = createMerchantAccountOutputSchema.safeParse(parsedJson);
   if (!out.success) {
-    return {
-      ok: false,
-      errorText: UNEXPECTED_RESPONSE_ERROR
-    };
+    return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
   }
-  return { ok: true, data: out.data };
-}
-
-// src/tools/merchant/go-live.tool.ts
-var goLiveStatusBodySchema = external_exports.object({
-  liveMerchantId: external_exports.string().nullable()
-});
-var CONFLICT_LIVE_ID_ERROR = "This sandbox merchant is already linked to a different live merchant. Recovery: use the existing liveMerchantId from go-live-status, or contact support \u2014 Merchant Go-Live is one-way and cannot overwrite a conflicting link.";
-var LIVE_TWIN_MISSING_ERROR = "The live twin merchant was not found. Recovery: ensure create_merchant_account finished dual provision on both backends (same merchantId on live and sandbox), then retry go_live.";
-var SANDBOX_MISSING_ERROR = "The sandbox merchant was not found. Recovery: create the merchant with create_merchant_account first, then retry go_live.";
-function buildGoLiveStub(input) {
-  return goLiveOutputSchema.parse({
-    liveMerchantId: input.merchantId,
-    kycNotify: { status: "skipped", reason: "stub_backends" }
-  });
+  return { ok: true, merchantId: out.data.merchantId };
+}
+async function runCreateMerchantAccountHandlerWithDualBackend(clients, input, identity) {
+  const merchantId = input.merchantId ?? randomUuidV7();
+  const sharedOrigin = clients.live.getBaseUrl() === clients.sandbox.getBaseUrl();
+  if (sharedOrigin) {
+    const side = await provisionOnBackend(clients.live, input, merchantId, identity);
+    if (!side.ok) {
+      const failure = side;
+      logDualProvisionOutcome({
+        merchantId,
+        live: failure,
+        sandbox: failure,
+        outcome: "total_failure"
+      });
+      return {
+        ok: false,
+        errorText: formatDualProvisionPartialFailure({
+          merchantId,
+          live: failure,
+          sandbox: failure
+        })
+      };
+    }
+    const okSide = { ok: true, merchantId };
+    logDualProvisionOutcome({
+      merchantId,
+      live: okSide,
+      sandbox: okSide,
+      outcome: "success"
+    });
+    return { ok: true, data: { merchantId } };
+  }
+  const [liveSettled, sandboxSettled] = await Promise.allSettled([
+    provisionOnBackend(clients.live, input, merchantId, { userId: identity?.userId }),
+    provisionOnBackend(clients.sandbox, input, merchantId, { cognitoSub: identity?.cognitoSub })
+  ]);
+  const live = liveSettled.status === "fulfilled" ? liveSettled.value : {
+    ok: false,
+    errorText: liveSettled.reason instanceof Error ? liveSettled.reason.message : String(liveSettled.reason)
+  };
+  const sandbox = sandboxSettled.status === "fulfilled" ? sandboxSettled.value : {
+    ok: false,
+    errorText: sandboxSettled.reason instanceof Error ? sandboxSettled.reason.message : String(sandboxSettled.reason)
+  };
+  const liveSide = withMatchingId(live, merchantId);
+  const sandboxSide = withMatchingId(sandbox, merchantId);
+  if (liveSide.ok && sandboxSide.ok) {
+    logDualProvisionOutcome({
+      merchantId,
+      live: liveSide,
+      sandbox: sandboxSide,
+      outcome: "success"
+    });
+    return { ok: true, data: { merchantId } };
+  }
+  const outcome = !liveSide.ok && !sandboxSide.ok ? "total_failure" : "partial_failure";
+  logDualProvisionOutcome({ merchantId, live: liveSide, sandbox: sandboxSide, outcome });
+  if (liveSide.ok && !sandboxSide.ok) {
+    return {
+      ok: true,
+      data: { merchantId },
+      warningText: formatSandboxOnlyProvisionWarning({
+        sandboxErrorText: sandboxSide.errorText
+      })
+    };
+  }
+  return {
+    ok: false,
+    errorText: formatDualProvisionPartialFailure({
+      merchantId,
+      live: liveSide,
+      sandbox: sandboxSide
+    })
+  };
+}
+async function runCreateMerchantAccountHandlerWithBackend(backendClient, input, identity) {
+  const merchantId = input.merchantId ?? randomUuidV7();
+  const side = await provisionOnBackend(backendClient, input, merchantId, identity);
+  if (!side.ok) {
+    const errorText = side.code === BUSINESS_NAME_TAKEN_CODE ? `${side.errorText}
+${BUSINESS_NAME_TAKEN_RECOVERY}` : side.errorText;
+    return { ok: false, errorText };
+  }
+  return { ok: true, data: { merchantId: side.merchantId } };
+}
+
+// src/tools/merchant/go-live.tool.ts
+var goLiveStatusBodySchema = external_exports.object({
+  liveMerchantId: external_exports.string().nullable()
+});
+var CONFLICT_LIVE_ID_ERROR = "This sandbox merchant is already linked to a different live merchant. Recovery: use the existing liveMerchantId from go-live-status, or contact support \u2014 Merchant Go-Live is one-way and cannot overwrite a conflicting link.";
+var LIVE_TWIN_MISSING_ERROR = "The live twin merchant was not found. Recovery: ensure create_merchant_account finished dual provision on both backends (same merchantId on live and sandbox), then retry go_live.";
+var SANDBOX_MISSING_ERROR = "The sandbox merchant was not found. Recovery: create the merchant with create_merchant_account first, then retry go_live.";
+function buildGoLiveStub(input) {
+  return goLiveOutputSchema.parse({
+    liveMerchantId: input.merchantId,
+    kycNotify: { status: "skipped", reason: input.dryRun === true ? "dry_run" : "stub_backends" },
+    ...input.dryRun === true ? { dryRun: true } : {}
+  });
 }
 function runGoLiveHandler(raw) {
   const parsed = goLiveInputSchema.safeParse(raw);
@@ -15688,6 +15850,17 @@ async function runGoLiveHandlerWithDualBackend(clients, input, userId) {
     logGoLiveOutcome({ merchantId: twinId, outcome: "unexpected_response", userId });
     return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
   }
+  if (input.dryRun === true) {
+    logGoLiveOutcome({ merchantId: twinId, outcome: "dry_run", userId });
+    return {
+      ok: true,
+      data: goLiveOutputSchema.parse({
+        liveMerchantId: twinId,
+        kycNotify: { status: "skipped", reason: "dry_run" },
+        dryRun: true
+      })
+    };
+  }
   const markLive = await clients.sandbox.post(backendGoLivePath(twinId), {
     liveMerchantId: twinId
   });
@@ -15710,42 +15883,99 @@ async function runGoLiveHandlerWithDualBackend(clients, input, userId) {
   };
 }
 
-// src/tools/product/build-plan-checkout-url.ts
-var CHECKOUT_SANDBOX_QUERY_PARAM = "isSandbox";
-function buildPlanCheckoutUrl(params) {
-  const normalizedBaseUrl = params.checkoutBaseUrl.replace(/\/+$/, "");
-  const url2 = new URL(`${normalizedBaseUrl}/payment/${params.planId}`);
-  if (params.deployment === "sandbox") {
-    url2.searchParams.set(CHECKOUT_SANDBOX_QUERY_PARAM, "true");
+// src/tools/merchant/get-my-merchant.tool.ts
+var MERCHANT_LOOKUP_ACTION = "list the merchant accounts for this connection";
+async function readMerchantName(live, merchantId) {
+  const result = await live.get(backendMerchantPath(merchantId));
+  if (!result.ok) {
+    return { ok: false, errorText: formatToolBackendFailure(MERCHANT_LOOKUP_ACTION, result) };
   }
-  return url2.toString();
+  let parsedJson;
+  try {
+    parsedJson = JSON.parse(result.bodyText);
+  } catch {
+    return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
+  }
+  const out = mcpMerchantSummarySchema.safeParse(parsedJson);
+  if (!out.success) {
+    return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
+  }
+  return { ok: true, name: out.data.name };
+}
+async function runGetMyMerchantHandlerWithDualBackend(clients, merchantIds) {
+  if (merchantIds.length === 0) {
+    return { ok: true, data: getMyMerchantOutputSchema.parse({ merchants: [] }) };
+  }
+  const resolved = await Promise.all(
+    merchantIds.map(async (merchantId) => {
+      const [name, route] = await Promise.all([
+        readMerchantName(clients.live, merchantId),
+        resolveProductCheckoutBackend(clients, merchantId)
+      ]);
+      if (!name.ok) {
+        return { errorText: name.errorText };
+      }
+      return { merchantId, name: name.name, deployment: route.deployment };
+    })
+  );
+  const failure = resolved.find((entry) => "errorText" in entry);
+  if (failure) {
+    return { ok: false, errorText: failure.errorText };
+  }
+  return {
+    ok: true,
+    data: getMyMerchantOutputSchema.parse({ merchants: resolved })
+  };
+}
+async function runGetMyMerchantHandlerSolo(clients, merchantIds) {
+  if (merchantIds.length === 0) {
+    return { ok: true, data: getMyMerchantOutputSchema.parse({ merchants: [] }) };
+  }
+  const resolved = await Promise.all(
+    merchantIds.map(async (merchantId) => {
+      const name = await readMerchantName(clients.sandbox, merchantId);
+      if (!name.ok) {
+        return { errorText: name.errorText };
+      }
+      return { merchantId, name: name.name, deployment: "sandbox" };
+    })
+  );
+  const failure = resolved.find((entry) => "errorText" in entry);
+  if (failure) {
+    return { ok: false, errorText: failure.errorText };
+  }
+  return {
+    ok: true,
+    data: getMyMerchantOutputSchema.parse({ merchants: resolved })
+  };
 }
 
-// src/tools/product/create-product.tool.ts
-var backendCreatedProductShapeSchema = external_exports.object({
-  id: external_exports.string(),
-  planIds: external_exports.array(external_exports.string())
-});
-var backendCreateProductResponseSchema = backendCreatedProductShapeSchema.extend({
-  planIds: external_exports.array(external_exports.string()).min(1)
-});
-function productCreatedWithoutPlansError(productId) {
-  return `The product was created (id: ${productId}) but the backend returned no plans for it. Do not retry create_product \u2014 retrying would create a duplicate product. Tell the user the product was created without plans and ask them to review it in the dashboard.`;
+// src/tools/merchant/activation-status.tool.ts
+function stubStatusForAccount(merchantId) {
+  return merchantId.toLowerCase().includes("pending") ? "pending" : "not_provisioned";
 }
-function describeCreateProductParseFailure(parsedJson) {
-  const loose = backendCreatedProductShapeSchema.safeParse(parsedJson);
-  if (loose.success && loose.data.planIds.length === 0) {
-    return productCreatedWithoutPlansError(loose.data.id);
+function buildActivationStatusStub(input) {
+  return activationStatusOutputSchema.parse({
+    status: stubStatusForAccount(input.merchantId)
+  });
+}
+function runActivationStatusHandler(raw) {
+  const parsed = activationStatusInputSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      errorText: `Invalid arguments for get_merchant_activation_status.
+${formatZodIssuesForTool(parsed.error.issues)}`
+    };
   }
-  return UNEXPECTED_RESPONSE_ERROR;
+  return { ok: true, data: buildActivationStatusStub(parsed.data) };
 }
-async function runCreateProductHandler(backendClient, input, checkout) {
-  const { merchantId, ...body } = input;
-  const result = await backendClient.post(backendCreateProductPath(merchantId), body);
+async function runActivationStatusHandlerWithBackend(backendClient, input) {
+  const result = await backendClient.get(backendActivationStatusPath(input.merchantId));
   if (!result.ok) {
     return {
       ok: false,
-      errorText: formatToolBackendFailure("create this product", result)
+      errorText: formatToolBackendFailure("load merchant activation status", result)
     };
   }
   let parsedJson;
@@ -15757,54 +15987,295 @@ async function runCreateProductHandler(backendClient, input, checkout) {
       errorText: UNEXPECTED_RESPONSE_ERROR
     };
   }
-  const backendResult = backendCreateProductResponseSchema.safeParse(parsedJson);
-  if (!backendResult.success) {
-    return {
-      ok: false,
-      errorText: describeCreateProductParseFailure(parsedJson)
-    };
-  }
-  const output = enrichWithCheckoutUrls(backendResult.data, checkout);
-  const validated = createMcpProductOutputSchema.safeParse(output);
-  if (!validated.success) {
+  const out = activationStatusOutputSchema.safeParse(parsedJson);
+  if (!out.success) {
     return {
       ok: false,
       errorText: UNEXPECTED_RESPONSE_ERROR
     };
   }
-  return { ok: true, data: validated.data };
+  return { ok: true, data: out.data };
 }
-function enrichWithCheckoutUrls(backendResponse, checkout) {
-  const planCheckoutUrls = backendResponse.planIds.map((planId) => ({
-    planId,
-    checkoutUrl: buildPlanCheckoutUrl({
-      checkoutBaseUrl: checkout.checkoutBaseUrl,
-      planId,
-      deployment: checkout.deployment
-    })
-  }));
-  return {
-    id: backendResponse.id,
-    planIds: backendResponse.planIds,
-    checkoutUrl: planCheckoutUrls[0]?.checkoutUrl ?? "",
-    planCheckoutUrls
-  };
+
+// src/backend/mcp-deployment-router.ts
+function missingClientsError() {
+  return { error: "The PAI Managed backend is not reachable. Contact Payments AI support." };
 }
-function runCreateProductHandlerValidation(raw) {
-  const parsed = createMcpProductInputSchema.safeParse(raw);
-  if (!parsed.success) {
-    return {
-      ok: false,
-      errorText: `Invalid arguments for create_product.
-${formatZodIssuesForTool(parsed.error.issues)}`
-    };
+function missingClientsResult() {
+  return { ok: false, errorText: missingClientsError().error };
+}
+function parseMyMerchantsBody(bodyText) {
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyText);
+  } catch {
+    return void 0;
   }
-  return { ok: true, data: parsed.data };
+  if (typeof parsed !== "object" || parsed === null || !("merchantIds" in parsed)) {
+    return void 0;
+  }
+  const merchantIds = parsed.merchantIds;
+  if (!Array.isArray(merchantIds) || !merchantIds.every((id) => typeof id === "string")) {
+    return void 0;
+  }
+  return merchantIds;
 }
-
-// src/tools/product/get-product-image-upload-url.tool.ts
-function runGetProductImageUploadUrlValidation(raw) {
-  const parsed = productImageUploadUrlInputSchema.safeParse(raw);
+function createDualRouter(clients) {
+  return {
+    mode: "dual",
+    supportsGoLive: true,
+    tokenValidationClient: clients.live,
+    healthProbeClient: clients.live,
+    healthProbeLabel: "live backend",
+    async resolveProductCheckout(c, merchantId) {
+      if (!hasLiveBackend(c)) {
+        return missingClientsError();
+      }
+      return resolveProductCheckoutBackend(c, merchantId);
+    },
+    async createMerchantAccount(c, input, identity) {
+      if (!hasLiveBackend(c)) {
+        return missingClientsResult();
+      }
+      return runCreateMerchantAccountHandlerWithDualBackend(c, input, identity);
+    },
+    async goLive(c, input, userId) {
+      if (!hasLiveBackend(c)) {
+        return missingClientsResult();
+      }
+      return runGoLiveHandlerWithDualBackend(c, input, userId);
+    },
+    async getMyMerchant(c, merchantIds) {
+      if (!hasLiveBackend(c)) {
+        return missingClientsResult();
+      }
+      return runGetMyMerchantHandlerWithDualBackend(c, merchantIds);
+    },
+    async activationStatus(c, input) {
+      if (!hasLiveBackend(c)) {
+        return missingClientsResult();
+      }
+      return runActivationStatusHandlerWithBackend(c.live, input);
+    },
+    checkoutLogoClient(c) {
+      return c.sandbox;
+    },
+    async resolveMerchantAllowlist(payload) {
+      return payload?.merchantIds;
+    }
+  };
+}
+function createSoloRouter(clients) {
+  return {
+    mode: "solo",
+    supportsGoLive: false,
+    tokenValidationClient: clients.sandbox,
+    healthProbeClient: clients.sandbox,
+    healthProbeLabel: "sandbox backend",
+    async resolveProductCheckout(c, merchantId) {
+      if (!c.sandbox) {
+        return missingClientsError();
+      }
+      return { client: c.sandbox, merchantId, deployment: "sandbox" };
+    },
+    async createMerchantAccount(c, input, identity) {
+      return runCreateMerchantAccountHandlerWithBackend(c.sandbox, input, {
+        cognitoSub: identity?.cognitoSub
+      });
+    },
+    async goLive() {
+      return { ok: false, errorText: "go_live is not available on the sandbox MCP URL." };
+    },
+    async getMyMerchant(c, merchantIds) {
+      return runGetMyMerchantHandlerSolo(c, merchantIds);
+    },
+    async activationStatus(c, input) {
+      return runActivationStatusHandlerWithBackend(c.sandbox, input);
+    },
+    checkoutLogoClient(c) {
+      return c.sandbox;
+    },
+    async resolveMerchantAllowlist(payload) {
+      if (!payload) {
+        return void 0;
+      }
+      const path2 = `${BACKEND_MCP_MY_MERCHANTS_PATH}?cognitoSub=${encodeURIComponent(payload.cognitoSub)}`;
+      const result = await clients.sandbox.get(path2);
+      if (!result.ok) {
+        return {
+          error: "Could not load your merchant list from the sandbox backend. Try again or contact Payments AI support."
+        };
+      }
+      const merchantIds = parseMyMerchantsBody(result.bodyText);
+      if (merchantIds === void 0) {
+        return {
+          error: "Received an invalid merchant list from the sandbox backend. Contact Payments AI support."
+        };
+      }
+      return merchantIds;
+    }
+  };
+}
+function createMcpDeploymentRouter(clients, mode) {
+  if (mode === "solo") {
+    return createSoloRouter(clients);
+  }
+  if (!hasLiveBackend(clients)) {
+    throw new Error("BACKEND_LIVE_URL is required for dual MCP deployment");
+  }
+  return createDualRouter(clients);
+}
+
+// src/http/app.ts
+import cors from "cors";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { toNodeHandler } from "@modelcontextprotocol/node";
+import {
+  createMcpExpressApp,
+  getOAuthProtectedResourceMetadataUrl as getOAuthProtectedResourceMetadataUrl2,
+  mcpAuthMetadataRouter
+} from "@modelcontextprotocol/express";
+
+// src/load-package-meta.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function readMcpServerVersion() {
+  const path2 = join(__dirname, "..", "package.json");
+  const raw = readFileSync(path2, "utf8");
+  const pkg = JSON.parse(raw);
+  return pkg.version ?? "0.0.0";
+}
+
+// src/observability/create-instrumented-mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/server";
+var MCP_SERVER_NAME = "pai-managed-mcp-server";
+function createInstrumentedMcpServer(options2) {
+  const server = new McpServer({
+    name: MCP_SERVER_NAME,
+    version: options2.version
+  });
+  return Sentry.wrapMcpServerWithSentry(server, {
+    recordInputs: false,
+    recordOutputs: false
+  });
+}
+
+// src/tools/scope-denial.ts
+var DEVELOPER_TOOLS_PATH = "/developer-tools";
+function isScopeAllowed(required2, payload) {
+  if (!payload) return true;
+  if (payload.scopes === null) return true;
+  return payload.scopes.includes(required2);
+}
+function insufficientScopeMessage(required2, dashboardUrl) {
+  const location = dashboardUrl ? `at ${dashboardUrl.replace(/\/+$/, "")}${DEVELOPER_TOOLS_PATH}` : `under ${DEVELOPER_TOOLS_PATH}`;
+  return `Insufficient scope. This tool requires the '${required2}' scope, which this connection does not have. Recovery: re-authorize the connection requesting '${required2}', or mint a new MCP key that includes it in the Payments AI dashboard ${location}.`;
+}
+function scopeDenial(required2, payload, dashboardUrl) {
+  if (isScopeAllowed(required2, payload)) return void 0;
+  return {
+    isError: true,
+    content: [{ type: "text", text: insufficientScopeMessage(required2, dashboardUrl) }]
+  };
+}
+
+// src/tools/product/build-plan-checkout-url.ts
+var CHECKOUT_SANDBOX_QUERY_PARAM = "isSandbox";
+function buildPlanCheckoutUrl(params) {
+  const normalizedBaseUrl = params.checkoutBaseUrl.replace(/\/+$/, "");
+  const url2 = new URL(`${normalizedBaseUrl}/payment/${params.planId}`);
+  if (params.deployment === "sandbox") {
+    url2.searchParams.set(CHECKOUT_SANDBOX_QUERY_PARAM, "true");
+  }
+  return url2.toString();
+}
+
+// src/tools/product/create-product.tool.ts
+var backendCreatedProductShapeSchema = external_exports.object({
+  id: external_exports.string(),
+  planIds: external_exports.array(external_exports.string())
+});
+var backendCreateProductResponseSchema = backendCreatedProductShapeSchema.extend({
+  planIds: external_exports.array(external_exports.string()).min(1)
+});
+function productCreatedWithoutPlansError(productId) {
+  return `The product was created (id: ${productId}) but the backend returned no plans for it. Do not retry create_product \u2014 retrying would create a duplicate product. Tell the user the product was created without plans and ask them to review it in the dashboard.`;
+}
+function describeCreateProductParseFailure(parsedJson) {
+  const loose = backendCreatedProductShapeSchema.safeParse(parsedJson);
+  if (loose.success && loose.data.planIds.length === 0) {
+    return productCreatedWithoutPlansError(loose.data.id);
+  }
+  return UNEXPECTED_RESPONSE_ERROR;
+}
+async function runCreateProductHandler(backendClient, input, checkout) {
+  const { merchantId, ...body } = input;
+  const result = await backendClient.post(backendCreateProductPath(merchantId), body);
+  if (!result.ok) {
+    return {
+      ok: false,
+      errorText: formatToolBackendFailure("create this product", result)
+    };
+  }
+  let parsedJson;
+  try {
+    parsedJson = JSON.parse(result.bodyText);
+  } catch {
+    return {
+      ok: false,
+      errorText: UNEXPECTED_RESPONSE_ERROR
+    };
+  }
+  const backendResult = backendCreateProductResponseSchema.safeParse(parsedJson);
+  if (!backendResult.success) {
+    return {
+      ok: false,
+      errorText: describeCreateProductParseFailure(parsedJson)
+    };
+  }
+  const output = enrichWithCheckoutUrls(backendResult.data, checkout);
+  const validated = createMcpProductOutputSchema.safeParse(output);
+  if (!validated.success) {
+    return {
+      ok: false,
+      errorText: UNEXPECTED_RESPONSE_ERROR
+    };
+  }
+  return { ok: true, data: validated.data };
+}
+function enrichWithCheckoutUrls(backendResponse, checkout) {
+  const planCheckoutUrls = backendResponse.planIds.map((planId) => ({
+    planId,
+    checkoutUrl: buildPlanCheckoutUrl({
+      checkoutBaseUrl: checkout.checkoutBaseUrl,
+      planId,
+      deployment: checkout.deployment
+    })
+  }));
+  return {
+    id: backendResponse.id,
+    planIds: backendResponse.planIds,
+    checkoutUrl: planCheckoutUrls[0]?.checkoutUrl ?? "",
+    planCheckoutUrls
+  };
+}
+function runCreateProductHandlerValidation(raw) {
+  const parsed = createMcpProductInputSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      errorText: `Invalid arguments for create_product.
+${formatZodIssuesForTool(parsed.error.issues)}`
+    };
+  }
+  return { ok: true, data: parsed.data };
+}
+
+// src/tools/product/get-product-image-upload-url.tool.ts
+function runGetProductImageUploadUrlValidation(raw) {
+  const parsed = productImageUploadUrlInputSchema.safeParse(raw);
   if (!parsed.success) {
     return {
       ok: false,
@@ -15989,422 +16460,177 @@ async function runListProductsHandler(backendClient, input) {
   try {
     parsedJson = JSON.parse(result.bodyText);
   } catch {
-    return {
-      ok: false,
-      errorText: UNEXPECTED_RESPONSE_ERROR
-    };
-  }
-  const mapped = mapBackendListProductsResponse(parsedJson);
-  const out = listProductsOutputSchema.safeParse(mapped);
-  if (!out.success) {
-    return {
-      ok: false,
-      errorText: UNEXPECTED_RESPONSE_ERROR
-    };
-  }
-  return { ok: true, data: out.data };
-}
-
-// src/tools/docs/knowledge/products-plans.ts
-var DOC_SECTIONS = [
-  {
-    title: "Navigation \u2014 Products & Plans",
-    path: "/docs/products-plans#navigation",
-    content: `To access Products & Plans, find **Products** in the left sidebar under the "Product" group (Package icon). Click **Products** to navigate to /products.`
-  },
-  {
-    title: "Create a Product",
-    path: "/docs/products-plans#create-a-product",
-    content: `1. Call **list_products** with merchantId to discover existing products and planIds (optional filters: status, q, page, limit).
-2. Call **create_product** with merchantId, name, and at least one plan when you need a new product.
-3. Optionally attach an image via the presigned upload flow: call **get_product_image_upload_url** with the returned product id, POST the raw bytes (multipart/form-data with the returned fields + file last) to the returned URL, then call **confirm_product_image** with the returned key.
-4. Use the returned **checkoutUrl** (or **planCheckoutUrls[i].checkoutUrl**) directly \u2014 it already targets the right environment (sandbox URLs carry \`?isSandbox=true\`, live URLs have no query param). Do not construct the URL yourself.`
-  },
-  {
-    title: "Upload a Product Image (MCP)",
-    path: "/docs/products-plans#upload-product-image-mcp",
-    content: `After create_product returns an id:
-1. Call **get_product_image_upload_url** with merchantId, productId, fileName, and mimeType. It returns { url, fields, key, expiresIn }.
-2. HTTP POST the raw file bytes to \`url\` as \`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). Example: \`curl -X POST -F "key=<fields.key>" -F "Content-Type=<mimeType>" -F "policy=<fields.policy>" -F "x-amz-signature=<fields['x-amz-signature']>" ... -F "file=@./logo.png" "<url>"\`.
-3. Call **confirm_product_image** with merchantId, productId, and the returned key to validate and attach the image.
-4. Supported formats: PNG, JPEG, WebP. Maximum size: 5 MB (enforced by S3 at upload time via a \`content-length-range\` policy condition \u2014 oversized bodies return a 403 from S3, before the backend ever sees them).
-5. If confirm fails, retry get_product_image_upload_url + POST + confirm_product_image with the same productId \u2014 the product row is kept; the previous rejected upload was cleaned up by the backend.`
-  },
-  {
-    title: "List Products (MCP)",
-    path: "/docs/products-plans#list-products-mcp",
-    content: `Call **list_products** with merchantId to list existing products and plans for a merchant. Returns paginated data with planId, name, amount, type, billing period, and checkoutUrl per plan. Optional filters: q (search by name), status (draft|active|archived), type (one-time|recurring|free-access), dateRangeStart/dateRangeEnd, page, limit. Use returned planId or checkoutUrl to build payment links \u2014 see Checkout URL docs. Targets sandbox until go_live.`
-  },
-  {
-    title: "Plan Fields",
-    path: "/docs/products-plans#plan-fields",
-    content: `Each plan has the following fields:
-- **Name** \u2014 display name for the plan (max 30 characters)
-- **Amount** \u2014 price in USD as a decimal dollar amount (e.g. 9.99 = $9.99)
-- **Type** \u2014 one of: \`one-time\`, \`recurring\`, \`free-access\`
-- **Billing Period** \u2014 one of: \`week\`, \`month\`, \`year\`
-- **Period Length** \u2014 number of billing periods per cycle
-- **Free Trial** \u2014 number of free trial days (optional)`
-  },
-  {
-    title: "Edit a Product",
-    path: "/docs/products-plans#edit-a-product",
-    content: `1. Go to **Products** in the left sidebar.
-2. Click on the product row you want to edit.
-3. Click **Edit** to modify name, description, status, or plans.`
-  },
-  {
-    title: "Checkout URL",
-    path: "/docs/products-plans#checkout-url",
-    content: `Each plan has a hosted checkout URL on the public checkout page at \`{checkout-base-url}/payment/{planId}\`. Sandbox and live are separate environments with separate databases and separate plan IDs \u2014 a sandbox plan does not exist on live, and \`go_live\` does not migrate products or plans (see the \`go_live\` tool description: "Does not copy products or checkout"). A sandbox checkout URL cannot be converted into a live checkout URL by editing the query string; the resulting link would target a plan that does not exist on live and would not take payments.
-
-Get a checkout URL from **create_product** or **list_products** \u2014 both return a ready-to-open \`checkoutUrl\` per plan (\`planCheckoutUrls[i].checkoutUrl\` on create, \`plans[i].checkoutUrl\` on list, or the top-level \`checkoutUrl\`). Use the returned URL verbatim \u2014 do not build one from \`planId\` yourself. These tools pick the environment themselves from the merchant's go-live status: sandbox before \`go_live\`, live once \`go_live\` has succeeded. There is nothing to switch on your side \u2014 same tools, same connection.
-
-- **Sandbox plan:** before go-live, \`checkoutUrl\` carries \`?isSandbox=true\` and points at the sandbox plan on the sandbox backend. Use it for test payments.
-- **Live plan:** after \`go_live\` succeeds, those same tools resolve to the live backend for that merchant. Call **create_product** again with the product and plan details to create the plan on live; the \`checkoutUrl\` in that response has no query param and is the live link. **list_products** then returns live products only \u2014 the pre-go-live sandbox plan and its URL are not the live ones.
-
-Embed the returned URL directly, for example: \`<a href="<checkoutUrl from create_product or list_products>">Pay Now!</a>\`.`
-  }
-];
-
-// src/tools/docs/knowledge/checkout-customization.ts
-var CHECKOUT_CUSTOMIZATION_DOC_SECTIONS = [
-  {
-    title: "Checkout Customization \u2014 Overview",
-    path: "/docs/checkout-customization#overview",
-    content: `Checkout customization controls the branding of a merchant's hosted checkout (the customer-facing payment page at /payment/{planId}). Configurable fields:
-- **themeMode** \u2014 \`light\` or \`dark\`
-- **backgroundColor**, **buttonColor**, **buttonTextColor**, **fontColor** \u2014 6-digit hex like \`#1A2B3C\`
-- **fontFamily** \u2014 \`Inter\` or \`Roboto\`
-- **inputStyle** \u2014 \`rounded\` or \`square\`
-- **logo** \u2014 set with the \`set_checkout_logo\` MCP tool (presigned PUT flow)
-
-Read with the \`get_checkout_customization\` MCP tool; change theme/colors with \`update_checkout_customization\`; set the logo with \`set_checkout_logo\`.`
-  },
-  {
-    title: "Checkout Customization \u2014 Legal terms",
-    path: "/docs/checkout-customization#legal-terms",
-    content: `Checkout customization is **branding only** \u2014 theme, colors, logo, fonts, and input styles. Legal terms and conditions are **not** configurable.
-
-Under the Merchant of Record (MoR) model, the customer's contract of sale is with Payments AI, not the merchant. Merchants cannot upload or configure checkout terms & conditions through the dashboard or MCP tools.
-
-Live hosted checkout does not display merchant-configurable terms. Platform terms apply at merchant sign-up.`
-  },
-  {
-    title: "Checkout Customization \u2014 Updating branding via MCP",
-    path: "/docs/checkout-customization#update",
-    content: `The \`update_checkout_customization\` tool MERGES the fields you send: only the fields in the call are changed, and any field you omit keeps its current value. So you can send just \`{ "buttonColor": "#0A84FF" }\` to recolor the button without touching the rest of the branding.
-
-To remove or reset a field back to default, use the dashboard \u2014 clearing a field is not supported over MCP. Colors must be 6-digit hex (include the leading \`#\`). The tool returns the full customization after the merge, including the current \`logoUrl\` if a logo was set (via \`set_checkout_logo\` or the dashboard). The logo itself is not updated through this tool \u2014 use \`set_checkout_logo\`.`
-  },
-  {
-    title: "Checkout Customization \u2014 Logo",
-    path: "/docs/checkout-customization#logo",
-    content: `Set the checkout logo with the \`set_checkout_logo\` MCP tool (two-step, SSRF-safe \u2014 the tool never accepts an imageUrl to fetch):
-
-1. Call \`set_checkout_logo\` with \`action: "mint"\`, \`merchantId\`, \`fileName\`, and \`contentType\` (\`image/png\`, \`image/jpeg\`, \`image/jpg\`, or \`image/webp\`). Returns \`{ uploadUrl, path, expiresAt }\`.
-2. HTTP **PUT** the image bytes to \`uploadUrl\` with the same \`Content-Type\` (max 5 MB). Bytes never pass through the MCP tool.
-3. Call \`set_checkout_logo\` with \`action: "confirm"\`, \`merchantId\`, and the exact \`path\` from step 1. Returns \`{ logoUrl }\`.
-
-Requires \`checkout:write\` scope. Replaces any existing checkout logo. Read the current logo via \`get_checkout_customization\` (\`logoUrl\`).`
-  }
-];
-
-// src/tools/docs/knowledge/merchant-create.ts
-var MERCHANT_CREATE_DOC_SECTIONS = [
-  {
-    title: "Check for an existing merchant before creating one",
-    path: "/docs/merchant-create#existing-merchant",
-    content: `Call \`get_my_merchant\` before \`create_merchant_account\`. It takes no arguments and returns every merchant the current connection is authorized for as \`{ merchantId, name, deployment }\`. A new agent session cannot remember a merchant created in an earlier one, so calling \`create_merchant_account\` blind produces a second merchant with its own products and its own checkout links \u2014 and \`merchantId\` is the value \`create_product\`, \`list_products\` and the checkout tools all key on, so the two sets never merge. An empty \`merchants\` array is the normal "none yet" answer rather than an error: create one. When more than one comes back, ask which to use instead of picking.`
-  },
-  {
-    title: "Create merchant account",
-    path: "/docs/merchant-create#create-merchant-account",
-    content: `Call \`create_merchant_account\` with the required \`name\` and \`email\`. \`phone\` is optional at create time \u2014 the merchant supplies it later during KYC/enrollment in the dashboard, so agents do not need to ask for a phone number to obtain a \`merchantId\`. If a phone is passed anyway, it must be in E.164 format with country code (example: \`+14155552671\`). Returns a \`merchantId\` shared across live and sandbox (dual provision).`
-  },
-  {
-    title: "Sandbox create journey and go_live",
-    path: "/docs/merchant-create#sandbox-go-live",
-    content: `After \`create_merchant_account\` dual-provisions live + sandbox with a shared merchantId, create products and update checkout on **sandbox** until you call \`go_live\`. \`go_live\` promotes the merchant to live routing; it does **not** copy products or checkout. Distinct from \`get_merchant_activation_status\` (payment-provider onboarding status).`
-  }
-];
-
-// src/tools/docs/search-payments-ai-docs.tool.ts
-var ALL_DOC_SECTIONS = [
-  ...DOC_SECTIONS,
-  ...CHECKOUT_CUSTOMIZATION_DOC_SECTIONS,
-  ...MERCHANT_CREATE_DOC_SECTIONS
-];
-function resolveCheckoutPlaceholder(sections) {
-  const base = resolveCheckoutBaseUrl();
-  if (!base) {
-    return sections;
-  }
-  return sections.map((section) => ({
-    ...section,
-    content: section.content.replaceAll("{checkout-base-url}", base)
-  }));
-}
-function runSearchPaymentsAiDocsHandler(query) {
-  const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 1);
-  if (terms.length === 0) {
-    return { results: resolveCheckoutPlaceholder(ALL_DOC_SECTIONS) };
-  }
-  const scored = ALL_DOC_SECTIONS.map((section) => {
-    const haystack = `${section.title} ${section.content}`.toLowerCase();
-    const hits = terms.filter((t) => haystack.includes(t)).length;
-    return { section, hits };
-  });
-  const matches = scored.filter((s) => s.hits > 0).sort((a, b) => b.hits - a.hits);
-  return {
-    results: resolveCheckoutPlaceholder(
-      matches.length > 0 ? matches.map((s) => s.section) : ALL_DOC_SECTIONS
-    )
-  };
-}
-
-// src/tools/health/payments-ai-health.tool.ts
-async function buildPaymentsAiHealthOutput(backendClient) {
-  const base = {
-    serverName: "pai-managed-mcp-server",
-    version: readMcpServerVersion(),
-    backend: { baseUrlConfigured: false }
-  };
-  if (!backendClient) {
-    return paymentsAiHealthOutputSchema.parse(base);
-  }
-  const result = await backendClient.get(BACKEND_HTTP_HEALTH_PATH);
-  if (!result.ok) {
-    return paymentsAiHealthOutputSchema.parse({
-      ...base,
-      backend: {
-        baseUrlConfigured: true,
-        probe: {
-          path: "live backend",
-          ok: false,
-          message: result.message
-        }
-      }
-    });
-  }
-  let message = "Backend responded successfully.";
-  try {
-    const json2 = JSON.parse(result.bodyText);
-    if (typeof json2.message === "string" && json2.message.length > 0) {
-      message = json2.message;
-    }
-  } catch {
-    message = result.bodyText.slice(0, 500) || message;
-  }
-  return paymentsAiHealthOutputSchema.parse({
-    ...base,
-    backend: {
-      baseUrlConfigured: true,
-      probe: {
-        path: "live backend",
-        ok: true,
-        message
-      }
-    }
-  });
-}
-
-// src/tools/merchant/create-merchant-account.tool.ts
-import * as crypto from "node:crypto";
-var randomUuidV7 = crypto.randomUUIDv7;
-var STUB_MERCHANT = {
-  merchantId: "01930000-0000-7000-8000-000000000001"
-};
-function buildCreateMerchantAccountStub(_input) {
-  return createMerchantAccountOutputSchema.parse(STUB_MERCHANT);
-}
-function runCreateMerchantAccountHandler(raw) {
-  const parsed = createMerchantAccountInputSchema.safeParse(raw);
-  if (!parsed.success) {
-    return {
-      ok: false,
-      errorText: `Invalid arguments for create_merchant_account.
-${formatZodIssuesForTool(parsed.error.issues)}`
-    };
-  }
-  return { ok: true, data: buildCreateMerchantAccountStub(parsed.data) };
-}
-function formatDualProvisionPartialFailure(params) {
-  const livePart = params.live.ok ? "live: ok" : `live: ${params.live.errorText}`;
-  const sandboxPart = params.sandbox.ok ? "sandbox: ok" : `sandbox: ${params.sandbox.errorText}`;
-  return `Could not create your merchant account on both backends (partial failure).
-merchantId: ${params.merchantId}
-${livePart}
-${sandboxPart}
-Recovery: retry create_merchant_account with the same merchantId to finish provisioning without creating a new id.`;
-}
-function formatSandboxOnlyProvisionWarning(params) {
-  return `Warning: the sandbox copy of this merchant account was not created.
-sandbox: ${params.sandboxErrorText}
-The live merchant account exists and this merchantId is safe to use.
-Sandbox products and sandbox checkout links stay unavailable until this succeeds.
-Recovery: retry create_merchant_account with the same merchantId to finish sandbox provisioning without creating a new id.`;
-}
-function withMatchingId(side, merchantId) {
-  if (!side.ok || side.merchantId === merchantId) {
-    return side;
-  }
-  return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
-}
-function logDualProvisionOutcome(params) {
-  console.error("[create_merchant_account] dual-provision", {
-    merchantId: params.merchantId,
-    outcome: params.outcome,
-    live: params.live.ok ? "ok" : "error",
-    sandbox: params.sandbox.ok ? "ok" : "error",
-    liveError: params.live.ok ? void 0 : params.live.errorText,
-    sandboxError: params.sandbox.ok ? void 0 : params.sandbox.errorText
-  });
-}
-async function provisionOnBackend(backendClient, input, merchantId, identity) {
-  const result = await backendClient.post(BACKEND_CREATE_MERCHANT_ACCOUNT_PATH, {
-    name: input.name,
-    email: input.email,
-    ...input.phone ? { phone: input.phone } : {},
-    merchantId,
-    ...identity?.userId ? { userId: identity.userId } : {},
-    ...identity?.cognitoSub ? { cognitoSub: identity.cognitoSub } : {}
-  });
-  if (!result.ok) {
-    return {
-      ok: false,
-      errorText: formatToolBackendFailure("create your merchant account", result)
-    };
-  }
-  let parsedJson;
-  try {
-    parsedJson = JSON.parse(result.bodyText);
-  } catch {
-    return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
-  }
-  const out = createMerchantAccountOutputSchema.safeParse(parsedJson);
-  if (!out.success) {
-    return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
-  }
-  return { ok: true, merchantId: out.data.merchantId };
-}
-async function runCreateMerchantAccountHandlerWithDualBackend(clients, input, identity) {
-  const merchantId = input.merchantId ?? randomUuidV7();
-  const sharedOrigin = clients.live.getBaseUrl() === clients.sandbox.getBaseUrl();
-  if (sharedOrigin) {
-    const side = await provisionOnBackend(clients.live, input, merchantId, identity);
-    if (!side.ok) {
-      const failure = side;
-      logDualProvisionOutcome({
-        merchantId,
-        live: failure,
-        sandbox: failure,
-        outcome: "total_failure"
-      });
-      return {
-        ok: false,
-        errorText: formatDualProvisionPartialFailure({
-          merchantId,
-          live: failure,
-          sandbox: failure
-        })
-      };
-    }
-    const okSide = { ok: true, merchantId };
-    logDualProvisionOutcome({
-      merchantId,
-      live: okSide,
-      sandbox: okSide,
-      outcome: "success"
-    });
-    return { ok: true, data: { merchantId } };
-  }
-  const [liveSettled, sandboxSettled] = await Promise.allSettled([
-    provisionOnBackend(clients.live, input, merchantId, { userId: identity?.userId }),
-    provisionOnBackend(clients.sandbox, input, merchantId, { cognitoSub: identity?.cognitoSub })
-  ]);
-  const live = liveSettled.status === "fulfilled" ? liveSettled.value : {
-    ok: false,
-    errorText: liveSettled.reason instanceof Error ? liveSettled.reason.message : String(liveSettled.reason)
-  };
-  const sandbox = sandboxSettled.status === "fulfilled" ? sandboxSettled.value : {
-    ok: false,
-    errorText: sandboxSettled.reason instanceof Error ? sandboxSettled.reason.message : String(sandboxSettled.reason)
-  };
-  const liveSide = withMatchingId(live, merchantId);
-  const sandboxSide = withMatchingId(sandbox, merchantId);
-  if (liveSide.ok && sandboxSide.ok) {
-    logDualProvisionOutcome({
-      merchantId,
-      live: liveSide,
-      sandbox: sandboxSide,
-      outcome: "success"
-    });
-    return { ok: true, data: { merchantId } };
-  }
-  const outcome = !liveSide.ok && !sandboxSide.ok ? "total_failure" : "partial_failure";
-  logDualProvisionOutcome({ merchantId, live: liveSide, sandbox: sandboxSide, outcome });
-  if (liveSide.ok && !sandboxSide.ok) {
-    return {
-      ok: true,
-      data: { merchantId },
-      warningText: formatSandboxOnlyProvisionWarning({
-        sandboxErrorText: sandboxSide.errorText
-      })
-    };
-  }
-  return {
-    ok: false,
-    errorText: formatDualProvisionPartialFailure({
-      merchantId,
-      live: liveSide,
-      sandbox: sandboxSide
-    })
-  };
-}
-
-// src/tools/merchant/get-my-merchant.tool.ts
-var MERCHANT_LOOKUP_ACTION = "list the merchant accounts for this connection";
-async function readMerchantName(live, merchantId) {
-  const result = await live.get(backendMerchantPath(merchantId));
-  if (!result.ok) {
-    return { ok: false, errorText: formatToolBackendFailure(MERCHANT_LOOKUP_ACTION, result) };
-  }
-  let parsedJson;
-  try {
-    parsedJson = JSON.parse(result.bodyText);
-  } catch {
-    return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
+    return {
+      ok: false,
+      errorText: UNEXPECTED_RESPONSE_ERROR
+    };
   }
-  const out = mcpMerchantSummarySchema.safeParse(parsedJson);
+  const mapped = mapBackendListProductsResponse(parsedJson);
+  const out = listProductsOutputSchema.safeParse(mapped);
   if (!out.success) {
-    return { ok: false, errorText: UNEXPECTED_RESPONSE_ERROR };
+    return {
+      ok: false,
+      errorText: UNEXPECTED_RESPONSE_ERROR
+    };
   }
-  return { ok: true, name: out.data.name };
+  return { ok: true, data: out.data };
 }
-async function runGetMyMerchantHandlerWithDualBackend(clients, merchantIds) {
-  if (merchantIds.length === 0) {
-    return { ok: true, data: getMyMerchantOutputSchema.parse({ merchants: [] }) };
+
+// src/tools/docs/knowledge/products-plans.ts
+var DOC_SECTIONS = [
+  {
+    title: "Navigation \u2014 Products & Plans",
+    path: "/docs/products-plans#navigation",
+    content: `To access Products & Plans, find **Products** in the left sidebar under the "Product" group (Package icon). Click **Products** to navigate to /products.`
+  },
+  {
+    title: "Create a Product",
+    path: "/docs/products-plans#create-a-product",
+    content: `1. Call **list_products** with merchantId to discover existing products and planIds (optional filters: status, q, page, limit).
+2. Call **create_product** with merchantId, name, and at least one plan when you need a new product.
+3. Optionally attach an image via the presigned upload flow: call **get_product_image_upload_url** with the returned product id, POST the raw bytes (multipart/form-data with the returned fields + file last) to the returned URL, then call **confirm_product_image** with the returned key.
+4. Use the returned **checkoutUrl** (or **planCheckoutUrls[i].checkoutUrl**) directly \u2014 it already targets the right environment (sandbox URLs carry \`?isSandbox=true\`, live URLs have no query param). Do not construct the URL yourself.`
+  },
+  {
+    title: "Upload a Product Image (MCP)",
+    path: "/docs/products-plans#upload-product-image-mcp",
+    content: `After create_product returns an id:
+1. Call **get_product_image_upload_url** with merchantId, productId, fileName, and mimeType. It returns { url, fields, key, expiresIn }.
+2. HTTP POST the raw file bytes to \`url\` as \`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). Example: \`curl -X POST -F "key=<fields.key>" -F "Content-Type=<mimeType>" -F "policy=<fields.policy>" -F "x-amz-signature=<fields['x-amz-signature']>" ... -F "file=@./logo.png" "<url>"\`.
+3. Call **confirm_product_image** with merchantId, productId, and the returned key to validate and attach the image.
+4. Supported formats: PNG, JPEG, WebP. Maximum size: 5 MB (enforced by S3 at upload time via a \`content-length-range\` policy condition \u2014 oversized bodies return a 403 from S3, before the backend ever sees them).
+5. If confirm fails, retry get_product_image_upload_url + POST + confirm_product_image with the same productId \u2014 the product row is kept; the previous rejected upload was cleaned up by the backend.`
+  },
+  {
+    title: "List Products (MCP)",
+    path: "/docs/products-plans#list-products-mcp",
+    content: `Call **list_products** with merchantId to list existing products and plans for a merchant. Returns paginated data with planId, name, amount, type, billing period, and checkoutUrl per plan. Optional filters: q (search by name), status (draft|active|archived), type (one-time|recurring|free-access), dateRangeStart/dateRangeEnd, page, limit. Use returned planId or checkoutUrl to build payment links \u2014 see Checkout URL docs. Targets sandbox until go_live.`
+  },
+  {
+    title: "Plan Fields",
+    path: "/docs/products-plans#plan-fields",
+    content: `Each plan has the following fields:
+- **Name** \u2014 display name for the plan (max 30 characters)
+- **Amount** \u2014 price in USD as a decimal dollar amount (e.g. 9.99 = $9.99)
+- **Type** \u2014 one of: \`one-time\`, \`recurring\`, \`free-access\`
+- **Billing Period** \u2014 one of: \`week\`, \`month\`, \`year\`
+- **Period Length** \u2014 number of billing periods per cycle
+- **Free Trial** \u2014 number of free trial days (optional)`
+  },
+  {
+    title: "Edit a Product",
+    path: "/docs/products-plans#edit-a-product",
+    content: `1. Go to **Products** in the left sidebar.
+2. Click on the product row you want to edit.
+3. Click **Edit** to modify name, description, status, or plans.`
+  },
+  {
+    title: "Checkout URL",
+    path: "/docs/products-plans#checkout-url",
+    content: `Each plan has a hosted checkout URL on the public checkout page at \`{checkout-base-url}/payment/{planId}\`. Sandbox and live are separate environments with separate databases and separate plan IDs \u2014 a sandbox plan does not exist on live, and \`go_live\` does not migrate products or plans (see the \`go_live\` tool description: "Does not copy products or checkout"). A sandbox checkout URL cannot be converted into a live checkout URL by editing the query string; the resulting link would target a plan that does not exist on live and would not take payments.
+
+Get a checkout URL from **create_product** or **list_products** \u2014 both return a ready-to-open \`checkoutUrl\` per plan (\`planCheckoutUrls[i].checkoutUrl\` on create, \`plans[i].checkoutUrl\` on list, or the top-level \`checkoutUrl\`). Use the returned URL verbatim \u2014 do not build one from \`planId\` yourself. These tools pick the environment themselves from the merchant's go-live status: sandbox before \`go_live\`, live once \`go_live\` has succeeded. There is nothing to switch on your side \u2014 same tools, same connection.
+
+- **Sandbox plan:** before go-live, \`checkoutUrl\` carries \`?isSandbox=true\` and points at the sandbox plan on the sandbox backend. Use it for test payments.
+- **Live plan:** after \`go_live\` succeeds, those same tools resolve to the live backend for that merchant. Call **create_product** again with the product and plan details to create the plan on live; the \`checkoutUrl\` in that response has no query param and is the live link. **list_products** then returns live products only \u2014 the pre-go-live sandbox plan and its URL are not the live ones.
+
+Embed the returned URL directly, for example: \`<a href="<checkoutUrl from create_product or list_products>">Pay Now!</a>\`.`
   }
-  const resolved = await Promise.all(
-    merchantIds.map(async (merchantId) => {
-      const [name, route] = await Promise.all([
-        readMerchantName(clients.live, merchantId),
-        resolveProductCheckoutBackend(clients, merchantId)
-      ]);
-      if (!name.ok) {
-        return { errorText: name.errorText };
-      }
-      return { merchantId, name: name.name, deployment: route.deployment };
-    })
-  );
-  const failure = resolved.find((entry) => "errorText" in entry);
-  if (failure) {
-    return { ok: false, errorText: failure.errorText };
+];
+
+// src/tools/docs/knowledge/checkout-customization.ts
+var CHECKOUT_CUSTOMIZATION_DOC_SECTIONS = [
+  {
+    title: "Checkout Customization \u2014 Overview",
+    path: "/docs/checkout-customization#overview",
+    content: `Checkout customization controls the branding of a merchant's hosted checkout (the customer-facing payment page at /payment/{planId}). Configurable fields:
+- **themeMode** \u2014 \`light\` or \`dark\`
+- **backgroundColor**, **buttonColor**, **buttonTextColor**, **fontColor** \u2014 6-digit hex like \`#1A2B3C\`
+- **fontFamily** \u2014 \`Inter\` or \`Roboto\`
+- **inputStyle** \u2014 \`rounded\` or \`square\`
+- **logo** \u2014 set with the \`set_checkout_logo\` MCP tool (presigned PUT flow)
+
+Read with the \`get_checkout_customization\` MCP tool; change theme/colors with \`update_checkout_customization\`; set the logo with \`set_checkout_logo\`.`
+  },
+  {
+    title: "Checkout Customization \u2014 Legal terms",
+    path: "/docs/checkout-customization#legal-terms",
+    content: `Checkout customization is **branding only** \u2014 theme, colors, logo, fonts, and input styles. Legal terms and conditions are **not** configurable.
+
+Under the Merchant of Record (MoR) model, the customer's contract of sale is with Payments AI, not the merchant. Merchants cannot upload or configure checkout terms & conditions through the dashboard or MCP tools.
+
+Live hosted checkout does not display merchant-configurable terms. Platform terms apply at merchant sign-up.`
+  },
+  {
+    title: "Checkout Customization \u2014 Updating branding via MCP",
+    path: "/docs/checkout-customization#update",
+    content: `The \`update_checkout_customization\` tool MERGES the fields you send: only the fields in the call are changed, and any field you omit keeps its current value. So you can send just \`{ "buttonColor": "#0A84FF" }\` to recolor the button without touching the rest of the branding.
+
+To remove or reset a field back to default, use the dashboard \u2014 clearing a field is not supported over MCP. Colors must be 6-digit hex (include the leading \`#\`). The tool returns the full customization after the merge, including the current \`logoUrl\` if a logo was set (via \`set_checkout_logo\` or the dashboard). The logo itself is not updated through this tool \u2014 use \`set_checkout_logo\`.`
+  },
+  {
+    title: "Checkout Customization \u2014 Logo",
+    path: "/docs/checkout-customization#logo",
+    content: `Set the checkout logo with the \`set_checkout_logo\` MCP tool (two-step, SSRF-safe \u2014 the tool never accepts an imageUrl to fetch):
+
+1. Call \`set_checkout_logo\` with \`action: "mint"\`, \`merchantId\`, \`fileName\`, and \`contentType\` (\`image/png\`, \`image/jpeg\`, \`image/jpg\`, or \`image/webp\`). Returns \`{ uploadUrl, path, expiresAt }\`.
+2. HTTP **PUT** the image bytes to \`uploadUrl\` with the same \`Content-Type\` (max 5 MB). Bytes never pass through the MCP tool.
+3. Call \`set_checkout_logo\` with \`action: "confirm"\`, \`merchantId\`, and the exact \`path\` from step 1. Returns \`{ logoUrl }\`.
+
+Requires \`checkout:write\` scope. Replaces any existing checkout logo. Read the current logo via \`get_checkout_customization\` (\`logoUrl\`).`
+  }
+];
+
+// src/tools/docs/knowledge/merchant-create.ts
+var MERCHANT_CREATE_DOC_SECTIONS = [
+  {
+    title: "Check for an existing merchant before creating one",
+    path: "/docs/merchant-create#existing-merchant",
+    content: `Call \`get_my_merchant\` before \`create_merchant_account\`. It takes no arguments and returns every merchant the current connection is authorized for as \`{ merchantId, name, deployment }\`. A new agent session cannot remember a merchant created in an earlier one, so calling \`create_merchant_account\` blind produces a second merchant with its own products and its own checkout links \u2014 and \`merchantId\` is the value \`create_product\`, \`list_products\` and the checkout tools all key on, so the two sets never merge. An empty \`merchants\` array is the normal "none yet" answer rather than an error: create one. When more than one comes back, ask which to use instead of picking.`
+  },
+  {
+    title: "Create merchant account",
+    path: "/docs/merchant-create#create-merchant-account",
+    content: `Call \`create_merchant_account\` with the required \`name\` and \`email\`. The \`name\` must be unique across Payments AI \u2014 pick a distinct business name for each new merchant (append a suffix or qualifier rather than reusing "Quickstart Demo"). \`phone\` is optional at create time \u2014 the merchant supplies it later during KYC/enrollment in the dashboard, so agents do not need to ask for a phone number to obtain a \`merchantId\`. If a phone is passed anyway, it must be in E.164 format with country code (example: \`+14155552671\`). Returns a \`merchantId\` shared across live and sandbox (dual provision). If both backends fail with \`business_name_taken\`, retry with a different \`name\` (do not keep retrying the same name). If only one backend failed, retry with the same \`merchantId\`, \`name\`, and \`email\` to finish provisioning.`
+  },
+  {
+    title: "Sandbox create journey and go_live",
+    path: "/docs/merchant-create#sandbox-go-live",
+    content: `After \`create_merchant_account\` dual-provisions live + sandbox with a shared merchantId, create products and update checkout on **sandbox** until you call \`go_live\`. \`go_live\` promotes the merchant to live routing; it does **not** copy products or checkout. Distinct from \`get_merchant_activation_status\` (payment-provider onboarding status).`
+  }
+];
+
+// src/tools/docs/search-payments-ai-docs.tool.ts
+var ALL_DOC_SECTIONS = [
+  ...DOC_SECTIONS,
+  ...CHECKOUT_CUSTOMIZATION_DOC_SECTIONS,
+  ...MERCHANT_CREATE_DOC_SECTIONS
+];
+function resolveCheckoutPlaceholder(sections) {
+  const base = resolveCheckoutBaseUrl();
+  if (!base) {
+    return sections;
+  }
+  return sections.map((section) => ({
+    ...section,
+    content: section.content.replaceAll("{checkout-base-url}", base)
+  }));
+}
+function runSearchPaymentsAiDocsHandler(query) {
+  const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 1);
+  if (terms.length === 0) {
+    return { results: resolveCheckoutPlaceholder(ALL_DOC_SECTIONS) };
   }
+  const scored = ALL_DOC_SECTIONS.map((section) => {
+    const haystack = `${section.title} ${section.content}`.toLowerCase();
+    const hits = terms.filter((t) => haystack.includes(t)).length;
+    return { section, hits };
+  });
+  const matches = scored.filter((s) => s.hits > 0).sort((a, b) => b.hits - a.hits);
   return {
-    ok: true,
-    data: getMyMerchantOutputSchema.parse({ merchants: resolved })
+    results: resolveCheckoutPlaceholder(
+      matches.length > 0 ? matches.map((s) => s.section) : ALL_DOC_SECTIONS
+    )
   };
 }
 
@@ -16585,13 +16811,6 @@ async function runSetCheckoutLogoHandler(backendClient, input) {
 
 // src/tools/tool-annotations.ts
 var TOOL_ANNOTATIONS = {
-  [MCP_TOOL_NAMES.PAYMENTS_AI_HEALTH]: {
-    title: "Payments AI Health",
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: false
-  },
   [MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS]: {
     title: "Get Merchant Activation Status",
     readOnlyHint: true,
@@ -16681,11 +16900,10 @@ var TOOL_ANNOTATIONS = {
 // src/tools/tool-descriptions.ts
 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; there is no long-copy field that reaches buyers today, so overflow must be edited down rather than moved.`;
 var TOOL_DESCRIPTIONS = {
-  [MCP_TOOL_NAMES.PAYMENTS_AI_HEALTH]: "Check whether the PAI Managed MCP server is healthy. Returns server version and connectivity status.",
   [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. Requires only name and email. Phone is optional and, if provided, must be in E.164 format with country code (e.g. +14155552671); otherwise it is collected later during KYC/enrollment in the dashboard. Dual-provisions live and sandbox with a shared merchantId. Returns that merchant ID. Next: create_product (and checkout tools) on sandbox, then go_live when ready.",
+  [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. Requires only name and email. The business name must be unique across Payments AI \u2014 do not reuse a name from another merchant (add a suffix or qualifier if needed). Phone is optional and, if provided, must be in E.164 format with country code (e.g. +14155552671); otherwise it is collected later during KYC/enrollment in the dashboard. Dual-provisions live and sandbox with a shared merchantId. On partial dual-provision failure, retry with the same merchantId, name, and email. If both backends fail with business_name_taken, change the name before retrying. Returns that merchant ID. 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 one of "active" (the live merchant is linked to a payment-provider account \u2014 proceed with live-key operations), "not_provisioned" (no live merchant record exists \u2014 dual provision never finished on live; recovery: re-run create_merchant_account with the same merchantId, which reuses that id idempotently \u2014 go_live cannot fix this and fails while the live twin is missing), or "pending" (a live merchant record exists but has no payment-provider link \u2014 it does not clear on its own, and re-running create_merchant_account with the same merchantId returns the existing record without provisioning, so escalate to support instead of polling).',
-  [MCP_TOOL_NAMES.GO_LIVE]: "Promote a sandbox merchant to live by setting liveMerchantId (Merchant Go-Live). 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. Does not copy products or checkout. Distinct from get_merchant_activation_status (payment-provider onboarding status) and from ApiKeyEnvironment.",
+  [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. Does not copy products or checkout. Distinct from get_merchant_activation_status (payment-provider onboarding 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 (in USD as a decimal dollar amount, e.g. 9.99 for $9.99 \u2014 NOT cents), billing type (one-time, recurring, or free-access), and billing period. " + 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. 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.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.',
@@ -16695,6 +16913,20 @@ var TOOL_DESCRIPTIONS = {
   [MCP_TOOL_NAMES.UPDATE_CHECKOUT_CUSTOMIZATION]: "Update a merchant's checkout customization on PAI Managed. Fields are MERGED: send only the fields you want to change \u2014 any field you omit is left unchanged. To remove/reset a field, use the dashboard (clearing is not supported over MCP). Colors are 6-digit hex like '#1A2B3C'; fontFamily is 'Inter' or 'Roboto'; themeMode is 'light' or 'dark'; inputStyle is 'rounded' or 'square'. The logo is set with set_checkout_logo (mint \u2192 PUT \u2192 confirm), not this tool. Returns the full customization after the merge.",
   [MCP_TOOL_NAMES.SET_CHECKOUT_LOGO]: 'Set a merchant checkout logo via a two-step presigned PUT flow (image bytes never pass through the tool). Step 1 \u2014 action "mint" with merchantId, fileName, and contentType (image/png, image/jpeg, image/jpg, or image/webp): returns { uploadUrl, path, expiresAt }. HTTP PUT the file bytes to uploadUrl with the same Content-Type (\u2264 5 MB). Step 2 \u2014 action "confirm" with merchantId and the exact path from mint: returns { logoUrl }. Does not accept an imageUrl to fetch server-side (SSRF-safe). Replaces any existing checkout logo.'
 };
+var SOLO_TOOL_DESCRIPTION_OVERRIDES = {
+  [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 }] }. On this sandbox MCP URL, "deployment" is always "sandbox". 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 Payments AI sandbox. 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. Requires only name and email. The business name must be unique across Payments AI \u2014 do not reuse a name from another merchant (add a suffix or qualifier if needed). Phone is optional and, if provided, must be in E.164 format with country code (e.g. +14155552671); otherwise it is collected later during KYC/enrollment in the dashboard. Creates the merchant on sandbox only. On failure, retry with the same merchantId, name, and email. If create fails with business_name_taken, change the name before retrying. Returns that merchant ID. Next: create_product (and checkout tools) on this sandbox MCP URL. Promoting a merchant to live is not available here \u2014 connect to the live MCP URL when you are ready.",
+  [MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS]: 'Get the payment-provider activation status of a merchant account on this sandbox MCP URL. Returns one of "active" (the merchant is linked to a payment-provider account), "not_provisioned" (no merchant record exists on sandbox; recovery: re-run create_merchant_account with the same merchantId, which reuses that id idempotently), or "pending" (a merchant record exists but has no payment-provider link \u2014 it does not clear on its own, and re-running create_merchant_account with the same merchantId returns the existing record without provisioning, so escalate to support instead of polling).',
+  [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 (in USD as a decimal dollar amount, e.g. 9.99 for $9.99 \u2014 NOT cents), billing type (one-time, recurring, or free-access), and billing period. " + 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`). 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.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, type, billing period) 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."
+};
+function resolveToolDescriptions(mode = "dual") {
+  if (mode !== "solo") {
+    return TOOL_DESCRIPTIONS;
+  }
+  return { ...TOOL_DESCRIPTIONS, ...SOLO_TOOL_DESCRIPTION_OVERRIDES };
+}
 
 // src/observability/log-mcp-tool-call.ts
 import { createHash } from "node:crypto";
@@ -16740,17 +16972,17 @@ function toolError(text) {
 }
 function resolveBackendClients(options2) {
   if (options2?.backendClients) {
-    return options2.backendClients;
+    return {
+      sandbox: options2.backendClients.sandbox,
+      live: options2.backendClients.live
+    };
   }
   const fromEnv = createDualBackendClientsFromEnv();
   if (fromEnv) {
-    return fromEnv;
+    return { sandbox: fromEnv.sandbox, live: fromEnv.live };
   }
   return { sandbox: void 0, live: void 0 };
 }
-function isMerchantAllowed(merchantId, payload) {
-  return !payload || payload.merchantIds.includes(merchantId);
-}
 var BACKEND_UNREACHABLE_ERROR = "The PAI Managed backend is not reachable. Contact Payments AI support.";
 var CHECKOUT_URL_NOT_CONFIGURED_ERROR = "The hosted checkout URL is not configured on the PAI Managed MCP server (set CHECKOUT_URL). Contact Payments AI support.";
 async function resolveProductCheckoutRoute(sandbox, live, merchantId) {
@@ -16761,32 +16993,39 @@ 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 mcpTokenPayload = options2?.mcpTokenPayload;
   const checkoutBaseUrl2 = options2?.checkoutBaseUrl ?? resolveCheckoutBaseUrl();
   const dashboardUrl = options2?.dashboardUrl;
+  const toolDescriptions = resolveToolDescriptions(deploymentRouter2?.mode ?? "dual");
   const denyForScope = (scope) => scopeDenial(scope, mcpTokenPayload, dashboardUrl);
-  server.registerTool(
-    MCP_TOOL_NAMES.PAYMENTS_AI_HEALTH,
-    {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.PAYMENTS_AI_HEALTH],
-      annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.PAYMENTS_AI_HEALTH],
-      outputSchema: paymentsAiHealthOutputSchema
-    },
-    async () => {
-      const denial = denyForScope("health:read");
-      if (denial) return denial;
-      logMcpToolCallAfterAuth(MCP_TOOL_NAMES.PAYMENTS_AI_HEALTH, {}, mcpTokenPayload?.userId);
-      const structuredContent = await buildPaymentsAiHealthOutput(liveBackendClient);
-      return {
-        content: [{ type: "text", text: JSON.stringify(structuredContent) }],
-        structuredContent
-      };
+  async function merchantAuthorizationDenial(merchantId) {
+    if (!mcpTokenPayload) {
+      return void 0;
     }
-  );
+    if (!deploymentRouter2) {
+      return mcpTokenPayload.merchantIds.includes(merchantId) ? void 0 : toolError("Merchant not authorized for this MCP key.");
+    }
+    const allowlist = await deploymentRouter2.resolveMerchantAllowlist(mcpTokenPayload);
+    if (allowlist && typeof allowlist === "object" && "error" in allowlist) {
+      return toolError(allowlist.error);
+    }
+    if (allowlist?.includes(merchantId)) {
+      return void 0;
+    }
+    return toolError("Merchant not authorized for this MCP key.");
+  }
+  async function resolveProductCheckoutRouteForTool(merchantId) {
+    if (deploymentRouter2 && dualBackendClients) {
+      return deploymentRouter2.resolveProductCheckout(dualBackendClients, merchantId);
+    }
+    return resolveProductCheckoutRoute(sandboxBackendClient, liveBackendClient, merchantId);
+  }
   server.registerTool(
     MCP_TOOL_NAMES.GET_MY_MERCHANT,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.GET_MY_MERCHANT],
+      description: toolDescriptions[MCP_TOOL_NAMES.GET_MY_MERCHANT],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.GET_MY_MERCHANT],
       outputSchema: getMyMerchantOutputSchema
     },
@@ -16794,13 +17033,18 @@ function registerTools(server, options2) {
       const denial = denyForScope("merchant:read");
       if (denial) return denial;
       logMcpToolCallAfterAuth(MCP_TOOL_NAMES.GET_MY_MERCHANT, {}, mcpTokenPayload?.userId);
-      if (!sandboxBackendClient || !liveBackendClient) {
+      if (!dualBackendClients || !deploymentRouter2) {
         return toolError(BACKEND_UNREACHABLE_ERROR);
       }
-      const result = await runGetMyMerchantHandlerWithDualBackend(
-        { sandbox: sandboxBackendClient, live: liveBackendClient },
-        mcpTokenPayload?.merchantIds ?? []
-      );
+      let merchantIds = [];
+      if (mcpTokenPayload !== void 0) {
+        const allowlist = await deploymentRouter2.resolveMerchantAllowlist(mcpTokenPayload);
+        if (allowlist && typeof allowlist === "object" && "error" in allowlist) {
+          return toolError(allowlist.error);
+        }
+        merchantIds = allowlist ?? [];
+      }
+      const result = await deploymentRouter2.getMyMerchant(dualBackendClients, merchantIds);
       if (!result.ok) {
         return toolError(result.errorText);
       }
@@ -16813,7 +17057,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.CREATE_MERCHANT_ACCOUNT,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.CREATE_MERCHANT_ACCOUNT],
+      description: toolDescriptions[MCP_TOOL_NAMES.CREATE_MERCHANT_ACCOUNT],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.CREATE_MERCHANT_ACCOUNT],
       inputSchema: createMerchantAccountInputSchema,
       outputSchema: createMerchantAccountOutputSchema
@@ -16826,14 +17070,10 @@ function registerTools(server, options2) {
         args,
         mcpTokenPayload?.userId
       );
-      const result = liveBackendClient && sandboxBackendClient ? await runCreateMerchantAccountHandlerWithDualBackend(
-        { live: liveBackendClient, sandbox: sandboxBackendClient },
-        args,
-        {
-          userId: mcpTokenPayload?.userId,
-          cognitoSub: mcpTokenPayload?.cognitoSub
-        }
-      ) : runCreateMerchantAccountHandler(args);
+      const result = deploymentRouter2 && dualBackendClients ? await deploymentRouter2.createMerchantAccount(dualBackendClients, args, {
+        userId: mcpTokenPayload?.userId,
+        cognitoSub: mcpTokenPayload?.cognitoSub
+      }) : runCreateMerchantAccountHandler(args);
       if (!result.ok) {
         return toolError(result.errorText);
       }
@@ -16849,7 +17089,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS],
+      description: toolDescriptions[MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS],
       inputSchema: activationStatusInputSchema,
       outputSchema: activationStatusOutputSchema
@@ -16857,15 +17097,16 @@ function registerTools(server, options2) {
     async (args) => {
       const denial = denyForScope("merchant:read");
       if (denial) return denial;
-      if (!isMerchantAllowed(args.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
+      const activationDenial = await merchantAuthorizationDenial(args.merchantId);
+      if (activationDenial) {
+        return activationDenial;
       }
       logMcpToolCallAfterAuth(
         MCP_TOOL_NAMES.GET_MERCHANT_ACTIVATION_STATUS,
         args,
         mcpTokenPayload?.userId
       );
-      const result = liveBackendClient ? await runActivationStatusHandlerWithBackend(liveBackendClient, args) : runActivationStatusHandler(args);
+      const result = deploymentRouter2 && dualBackendClients ? await deploymentRouter2.activationStatus(dualBackendClients, args) : liveBackendClient ? await runActivationStatusHandlerWithBackend(liveBackendClient, args) : runActivationStatusHandler(args);
       if (!result.ok) {
         return toolError(result.errorText);
       }
@@ -16875,39 +17116,38 @@ function registerTools(server, options2) {
       };
     }
   );
-  server.registerTool(
-    MCP_TOOL_NAMES.GO_LIVE,
-    {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.GO_LIVE],
-      annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.GO_LIVE],
-      inputSchema: goLiveInputSchema,
-      outputSchema: goLiveOutputSchema
-    },
-    async (args) => {
-      const denial = denyForScope("merchant:go_live");
-      if (denial) return denial;
-      if (!isMerchantAllowed(args.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
-      }
-      logMcpToolCallAfterAuth(MCP_TOOL_NAMES.GO_LIVE, args, mcpTokenPayload?.userId);
-      const result = liveBackendClient && sandboxBackendClient ? await runGoLiveHandlerWithDualBackend(
-        { live: liveBackendClient, sandbox: sandboxBackendClient },
-        args,
-        mcpTokenPayload?.userId
-      ) : runGoLiveHandler(args);
-      if (!result.ok) {
-        return toolError(result.errorText);
+  if (deploymentRouter2 === void 0 || deploymentRouter2.supportsGoLive) {
+    server.registerTool(
+      MCP_TOOL_NAMES.GO_LIVE,
+      {
+        description: toolDescriptions[MCP_TOOL_NAMES.GO_LIVE],
+        annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.GO_LIVE],
+        inputSchema: goLiveInputSchema,
+        outputSchema: goLiveOutputSchema
+      },
+      async (args) => {
+        const denial = denyForScope("merchant:go_live");
+        if (denial) return denial;
+        const goLiveMerchantDenial = await merchantAuthorizationDenial(args.merchantId);
+        if (goLiveMerchantDenial) {
+          return goLiveMerchantDenial;
+        }
+        logMcpToolCallAfterAuth(MCP_TOOL_NAMES.GO_LIVE, args, mcpTokenPayload?.userId);
+        const result = deploymentRouter2 && dualBackendClients ? await deploymentRouter2.goLive(dualBackendClients, args, mcpTokenPayload?.userId) : runGoLiveHandler(args);
+        if (!result.ok) {
+          return toolError(result.errorText);
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data) }],
+          structuredContent: result.data
+        };
       }
-      return {
-        content: [{ type: "text", text: JSON.stringify(result.data) }],
-        structuredContent: result.data
-      };
-    }
-  );
+    );
+  }
   server.registerTool(
     MCP_TOOL_NAMES.SEARCH_PAYMENTS_AI_DOCS,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.SEARCH_PAYMENTS_AI_DOCS],
+      description: toolDescriptions[MCP_TOOL_NAMES.SEARCH_PAYMENTS_AI_DOCS],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.SEARCH_PAYMENTS_AI_DOCS],
       inputSchema: searchPaymentsAiDocsInputSchema,
       outputSchema: searchPaymentsAiDocsOutputSchema
@@ -16930,7 +17170,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.CREATE_PRODUCT,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.CREATE_PRODUCT],
+      description: toolDescriptions[MCP_TOOL_NAMES.CREATE_PRODUCT],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.CREATE_PRODUCT],
       inputSchema: createMcpProductInputSchema,
       outputSchema: createMcpProductOutputSchema
@@ -16942,19 +17182,16 @@ function registerTools(server, options2) {
       if (!validation.ok) {
         return toolError(validation.errorText);
       }
-      if (!isMerchantAllowed(validation.data.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
+      const createProductDenial = await merchantAuthorizationDenial(validation.data.merchantId);
+      if (createProductDenial) {
+        return createProductDenial;
       }
       logMcpToolCallAfterAuth(
         MCP_TOOL_NAMES.CREATE_PRODUCT,
         validation.data,
         mcpTokenPayload?.userId
       );
-      const route = await resolveProductCheckoutRoute(
-        sandboxBackendClient,
-        liveBackendClient,
-        validation.data.merchantId
-      );
+      const route = await resolveProductCheckoutRouteForTool(validation.data.merchantId);
       if ("error" in route) {
         return toolError(route.error);
       }
@@ -16978,7 +17215,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.GET_PRODUCT_IMAGE_UPLOAD_URL,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.GET_PRODUCT_IMAGE_UPLOAD_URL],
+      description: toolDescriptions[MCP_TOOL_NAMES.GET_PRODUCT_IMAGE_UPLOAD_URL],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.GET_PRODUCT_IMAGE_UPLOAD_URL],
       inputSchema: productImageUploadUrlInputSchema,
       outputSchema: productImageUploadUrlOutputSchema
@@ -16990,19 +17227,16 @@ function registerTools(server, options2) {
       if (!validation.ok) {
         return toolError(validation.errorText);
       }
-      if (!isMerchantAllowed(validation.data.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
+      const uploadUrlDenial = await merchantAuthorizationDenial(validation.data.merchantId);
+      if (uploadUrlDenial) {
+        return uploadUrlDenial;
       }
       logMcpToolCallAfterAuth(
         MCP_TOOL_NAMES.GET_PRODUCT_IMAGE_UPLOAD_URL,
         validation.data,
         mcpTokenPayload?.userId
       );
-      const route = await resolveProductCheckoutRoute(
-        sandboxBackendClient,
-        liveBackendClient,
-        validation.data.merchantId
-      );
+      const route = await resolveProductCheckoutRouteForTool(validation.data.merchantId);
       if ("error" in route) {
         return toolError(route.error);
       }
@@ -17022,7 +17256,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.CONFIRM_PRODUCT_IMAGE,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.CONFIRM_PRODUCT_IMAGE],
+      description: toolDescriptions[MCP_TOOL_NAMES.CONFIRM_PRODUCT_IMAGE],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.CONFIRM_PRODUCT_IMAGE],
       inputSchema: confirmProductImageInputSchema,
       outputSchema: confirmProductImageOutputSchema
@@ -17034,19 +17268,16 @@ function registerTools(server, options2) {
       if (!validation.ok) {
         return toolError(validation.errorText);
       }
-      if (!isMerchantAllowed(validation.data.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
+      const confirmImageDenial = await merchantAuthorizationDenial(validation.data.merchantId);
+      if (confirmImageDenial) {
+        return confirmImageDenial;
       }
       logMcpToolCallAfterAuth(
         MCP_TOOL_NAMES.CONFIRM_PRODUCT_IMAGE,
         validation.data,
         mcpTokenPayload?.userId
       );
-      const route = await resolveProductCheckoutRoute(
-        sandboxBackendClient,
-        liveBackendClient,
-        validation.data.merchantId
-      );
+      const route = await resolveProductCheckoutRouteForTool(validation.data.merchantId);
       if ("error" in route) {
         return toolError(route.error);
       }
@@ -17066,7 +17297,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.LIST_PRODUCTS,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.LIST_PRODUCTS],
+      description: toolDescriptions[MCP_TOOL_NAMES.LIST_PRODUCTS],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.LIST_PRODUCTS],
       inputSchema: listProductsInputSchema,
       outputSchema: listProductsOutputSchema
@@ -17078,19 +17309,16 @@ function registerTools(server, options2) {
       if (!validation.ok) {
         return toolError(validation.errorText);
       }
-      if (!isMerchantAllowed(validation.data.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
+      const listProductsDenial = await merchantAuthorizationDenial(validation.data.merchantId);
+      if (listProductsDenial) {
+        return listProductsDenial;
       }
       logMcpToolCallAfterAuth(
         MCP_TOOL_NAMES.LIST_PRODUCTS,
         validation.data,
         mcpTokenPayload?.userId
       );
-      const route = await resolveProductCheckoutRoute(
-        sandboxBackendClient,
-        liveBackendClient,
-        validation.data.merchantId
-      );
+      const route = await resolveProductCheckoutRouteForTool(validation.data.merchantId);
       if ("error" in route) {
         return toolError(route.error);
       }
@@ -17110,7 +17338,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.GET_CHECKOUT_CUSTOMIZATION,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.GET_CHECKOUT_CUSTOMIZATION],
+      description: toolDescriptions[MCP_TOOL_NAMES.GET_CHECKOUT_CUSTOMIZATION],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.GET_CHECKOUT_CUSTOMIZATION],
       inputSchema: getCheckoutCustomizationInputSchema,
       outputSchema: checkoutCustomizationOutputSchema
@@ -17122,19 +17350,16 @@ function registerTools(server, options2) {
       if (!validation.ok) {
         return toolError(validation.errorText);
       }
-      if (!isMerchantAllowed(validation.data.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
+      const getCheckoutDenial = await merchantAuthorizationDenial(validation.data.merchantId);
+      if (getCheckoutDenial) {
+        return getCheckoutDenial;
       }
       logMcpToolCallAfterAuth(
         MCP_TOOL_NAMES.GET_CHECKOUT_CUSTOMIZATION,
         validation.data,
         mcpTokenPayload?.userId
       );
-      const route = await resolveProductCheckoutRoute(
-        sandboxBackendClient,
-        liveBackendClient,
-        validation.data.merchantId
-      );
+      const route = await resolveProductCheckoutRouteForTool(validation.data.merchantId);
       if ("error" in route) {
         return toolError(route.error);
       }
@@ -17154,7 +17379,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.UPDATE_CHECKOUT_CUSTOMIZATION,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.UPDATE_CHECKOUT_CUSTOMIZATION],
+      description: toolDescriptions[MCP_TOOL_NAMES.UPDATE_CHECKOUT_CUSTOMIZATION],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.UPDATE_CHECKOUT_CUSTOMIZATION],
       inputSchema: updateCheckoutCustomizationInputSchema,
       outputSchema: checkoutCustomizationOutputSchema
@@ -17166,19 +17391,16 @@ function registerTools(server, options2) {
       if (!validation.ok) {
         return toolError(validation.errorText);
       }
-      if (!isMerchantAllowed(validation.data.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
+      const updateCheckoutDenial = await merchantAuthorizationDenial(validation.data.merchantId);
+      if (updateCheckoutDenial) {
+        return updateCheckoutDenial;
       }
       logMcpToolCallAfterAuth(
         MCP_TOOL_NAMES.UPDATE_CHECKOUT_CUSTOMIZATION,
         validation.data,
         mcpTokenPayload?.userId
       );
-      const route = await resolveProductCheckoutRoute(
-        sandboxBackendClient,
-        liveBackendClient,
-        validation.data.merchantId
-      );
+      const route = await resolveProductCheckoutRouteForTool(validation.data.merchantId);
       if ("error" in route) {
         return toolError(route.error);
       }
@@ -17198,7 +17420,7 @@ function registerTools(server, options2) {
   server.registerTool(
     MCP_TOOL_NAMES.SET_CHECKOUT_LOGO,
     {
-      description: TOOL_DESCRIPTIONS[MCP_TOOL_NAMES.SET_CHECKOUT_LOGO],
+      description: toolDescriptions[MCP_TOOL_NAMES.SET_CHECKOUT_LOGO],
       annotations: TOOL_ANNOTATIONS[MCP_TOOL_NAMES.SET_CHECKOUT_LOGO],
       inputSchema: setCheckoutLogoInputSchema,
       outputSchema: setCheckoutLogoOutputSchema
@@ -17210,20 +17432,22 @@ function registerTools(server, options2) {
       if (!validation.ok) {
         return toolError(validation.errorText);
       }
-      if (!isMerchantAllowed(validation.data.merchantId, mcpTokenPayload)) {
-        return toolError("Merchant not authorized for this MCP key.");
+      const setLogoDenial = await merchantAuthorizationDenial(validation.data.merchantId);
+      if (setLogoDenial) {
+        return setLogoDenial;
       }
       logMcpToolCallAfterAuth(
         MCP_TOOL_NAMES.SET_CHECKOUT_LOGO,
         validation.data,
         mcpTokenPayload?.userId
       );
-      if (!sandboxBackendClient) {
+      const logoClient = deploymentRouter2 && dualBackendClients ? deploymentRouter2.checkoutLogoClient(dualBackendClients) : sandboxBackendClient;
+      if (!logoClient) {
         return toolError(
           "The PAI Managed backend is not reachable. Contact your platform administrator to configure backend connectivity."
         );
       }
-      const result = await runSetCheckoutLogoHandler(sandboxBackendClient, validation.data);
+      const result = await runSetCheckoutLogoHandler(logoClient, validation.data);
       if (!result.ok) {
         return toolError(result.errorText);
       }
@@ -17277,6 +17501,7 @@ function mcpHttpRequestLogger(req, res, next) {
 }
 
 // src/http/mcp-server-card.ts
+import { getOAuthProtectedResourceMetadataUrl } from "@modelcontextprotocol/express";
 var DEFAULT_DOCS_BASE_URL = "https://doc.managed.payments.ai";
 var DEFAULT_WEBSITE_URL = "https://managed.payments.ai";
 var MCP_PROTOCOL_VERSION = "2025-06-18";
@@ -17285,9 +17510,17 @@ function buildMcpServerCard(opts) {
   const websiteUrl2 = (opts.websiteUrl ?? DEFAULT_WEBSITE_URL).replace(/\/$/, "");
   const issuer = opts.oauthIssuerUrl.replace(/\/$/, "");
   const mcpEndpoint = opts.mcpPublicUrl ?? `${issuer}/api/mcp`;
-  const tools = Object.values(MCP_TOOL_NAMES).map((toolName) => ({
+  const resourceMetadataUrl = opts.mcpPublicUrl ? getOAuthProtectedResourceMetadataUrl(new URL(opts.mcpPublicUrl)) : `${issuer}/.well-known/oauth-protected-resource/api/mcp`;
+  const toolDescriptions = resolveToolDescriptions(opts.deploymentRouter?.mode ?? "dual");
+  const toolNames = Object.values(MCP_TOOL_NAMES).filter((toolName) => {
+    if (toolName === MCP_TOOL_NAMES.GO_LIVE && opts.deploymentRouter && !opts.deploymentRouter.supportsGoLive) {
+      return false;
+    }
+    return true;
+  });
+  const tools = toolNames.map((toolName) => ({
     name: toolName,
-    description: TOOL_DESCRIPTIONS[toolName] ?? toolName
+    description: toolDescriptions[toolName] ?? toolName
   }));
   return {
     serverInfo: {
@@ -17310,7 +17543,7 @@ function buildMcpServerCard(opts) {
       types: ["oauth2", "api_key"],
       oauth2: {
         authorization_server: `${issuer}/.well-known/oauth-authorization-server`,
-        resource_metadata: `${issuer}/.well-known/oauth-protected-resource/api/mcp`,
+        resource_metadata: resourceMetadataUrl,
         required_scopes: [...SUPPORTED_OAUTH_SCOPES]
       },
       api_key: {
@@ -17440,9 +17673,12 @@ function createExpressApp(options2) {
     docsBaseUrl: docsBaseUrl2,
     websiteUrl: websiteUrl2,
     checkoutBaseUrl: checkoutBaseUrl2,
-    allowedMcpOriginHostnames = DEFAULT_ALLOWED_MCP_ORIGIN_HOSTNAMES
+    allowedMcpOriginHostnames = DEFAULT_ALLOWED_MCP_ORIGIN_HOSTNAMES,
+    deploymentRouter: deploymentRouterOption
   } = options2;
-  const liveBackendClient = backendClients2?.live;
+  const deploymentRouter2 = deploymentRouterOption ?? (backendClients2 && hasLiveBackend(backendClients2) ? createDualRouter(backendClients2) : void 0);
+  const tokenValidationClient = deploymentRouter2?.tokenValidationClient ?? backendClients2?.live ?? backendClients2?.sandbox;
+  const healthProbeClient = deploymentRouter2?.healthProbeClient ?? backendClients2?.live;
   const app2 = createMcpExpressApp(resolveCreateMcpExpressAppOptions(host2, allowedHosts2));
   app2.use(
     cors({
@@ -17488,7 +17724,8 @@ function createExpressApp(options2) {
             oauthIssuerUrl: oauthIssuerUrl2,
             mcpPublicUrl: mcpPublicUrl2,
             docsBaseUrl: docsBaseUrl2,
-            websiteUrl: websiteUrl2
+            websiteUrl: websiteUrl2,
+            deploymentRouter: deploymentRouter2
           })
         )
       );
@@ -17497,11 +17734,11 @@ function createExpressApp(options2) {
     app2.get("/.well-known/mcp.json", sendMcpServerCard);
   }
   app2.get("/health", async (_req, res) => {
-    if (!liveBackendClient) {
+    if (!healthProbeClient) {
       res.status(200).type("application/json").send(JSON.stringify({ status: "ok" }));
       return;
     }
-    const result = await liveBackendClient.get(BACKEND_HTTP_HEALTH_PATH);
+    const result = await healthProbeClient.get(BACKEND_HTTP_HEALTH_PATH);
     if (result.ok) {
       res.status(200).type("application/json").send(JSON.stringify({ status: "ok", backend: { status: "ok" } }));
     } else {
@@ -17520,7 +17757,7 @@ function createExpressApp(options2) {
       );
     }
   });
-  const resourceMetadataUrl = mcpPublicUrl2 ? getOAuthProtectedResourceMetadataUrl(new URL(mcpPublicUrl2)) : void 0;
+  const resourceMetadataUrl = mcpPublicUrl2 ? getOAuthProtectedResourceMetadataUrl2(new URL(mcpPublicUrl2)) : void 0;
   const mcpOriginMiddleware = createMcpOriginMiddleware(allowedMcpOriginHostnames);
   const sendUnauthorized = (res, message) => {
     if (resourceMetadataUrl) {
@@ -17533,7 +17770,7 @@ function createExpressApp(options2) {
     if (message) body.message = message;
     res.status(401).json(body);
   };
-  const mcpAuthMiddleware = liveBackendClient ? async (req, res, next) => {
+  const mcpAuthMiddleware = tokenValidationClient ? async (req, res, next) => {
     const authHeader = req.headers.authorization;
     if (!authHeader || !authHeader.startsWith("Bearer ")) {
       sendUnauthorized(res);
@@ -17545,7 +17782,7 @@ function createExpressApp(options2) {
       return;
     }
     try {
-      req.mcpTokenPayload = await validateMcpToken(token, liveBackendClient);
+      req.mcpTokenPayload = await validateMcpToken(token, tokenValidationClient);
       req.auth = {
         token,
         clientId: req.mcpTokenPayload.userId,
@@ -17568,6 +17805,7 @@ function createExpressApp(options2) {
       const server = createInstrumentedMcpServer({ version: version2 });
       registerTools(server, {
         backendClients: backendClients2,
+        deploymentRouter: deploymentRouter2,
         mcpTokenPayload: readMcpTokenPayload(authInfo),
         checkoutBaseUrl: checkoutBaseUrl2,
         dashboardUrl: websiteUrl2
@@ -17589,7 +17827,13 @@ function createExpressApp(options2) {
     }
   });
   app2.post(mcpPath2, mcpOriginMiddleware, mcpAuthMiddleware, async (req, res) => {
-    await handleMcpRequest(req, res, req.body);
+    try {
+      await handleMcpRequest(req, res, req.body);
+    } finally {
+      if (isSentryEnabled()) {
+        await Sentry.flush(2e3);
+      }
+    }
   });
   const methodNotAllowed = (_req, res) => {
     res.status(405).set("Allow", "POST").type("application/json").send(
@@ -17609,8 +17853,10 @@ function createExpressApp(options2) {
 // src/main.http.ts
 var { host, port, mcpPath, allowedHosts, mcpPublicUrl, oauthIssuerUrl, docsBaseUrl, websiteUrl } = readMcpHttpListenConfig();
 var corsOrigin = resolveCorsOrigin();
-var backendUrlConfig = readRequiredDualBackendUrlConfig();
+var deploymentMode = readMcpDeploymentMode();
+var backendUrlConfig = readBackendUrlConfig(deploymentMode);
 var backendClients = createDualBackendClients(backendUrlConfig);
+var deploymentRouter = createMcpDeploymentRouter(backendClients, deploymentMode);
 var checkoutBaseUrl = resolveCheckoutBaseUrl();
 var app = createExpressApp({
   host,
@@ -17618,12 +17864,14 @@ var app = createExpressApp({
   allowedHosts,
   corsOrigin,
   backendClients,
+  deploymentRouter,
   mcpPublicUrl,
   oauthIssuerUrl,
   docsBaseUrl,
   websiteUrl,
   checkoutBaseUrl
 });
+console.error(`[mcp-http] deploymentMode=${deploymentMode}`);
 var httpServer = app.listen(port, host, () => {
   console.error(`[mcp-http] listening host=${host} port=${port} mcpPath=${mcpPath}`);
   console.error(