@solvapay/mcp 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -25,73 +25,15 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/server.ts
-var import_server2 = require("@modelcontextprotocol/ext-apps/server");
-var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
-var import_mcp_core2 = require("@solvapay/mcp-core");
-
-// src/registerPayableTool.ts
+// src/internal/buildMcpServer.ts
 var import_server = require("@modelcontextprotocol/ext-apps/server");
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_mcp_core = require("@solvapay/mcp-core");
-function registerPayableTool(server, name, options) {
-  const {
-    solvaPay,
-    resourceUri,
-    schema,
-    product,
-    title,
-    description,
-    handler,
-    buildBootstrap,
-    getCustomerRef,
-    meta,
-    annotations,
-    icons
-  } = options;
-  const protectedHandler = (0, import_mcp_core.buildPayableHandler)(
-    solvaPay,
-    { product, resourceUri, buildBootstrap, getCustomerRef },
-    handler
-  );
-  const baseMeta = meta ?? {};
-  const baseUi = baseMeta.ui ?? {};
-  const hasIcons = icons !== void 0 && icons.length > 0;
-  const mergedUi = {
-    resourceUri,
-    ...baseUi,
-    ...hasIcons ? { icons } : {}
-  };
-  const toolMeta = { ...baseMeta, ui: mergedUi };
-  const effectiveAnnotations = {
-    readOnlyHint: true,
-    openWorldHint: true,
-    ...annotations
-  };
-  return (0, import_server.registerAppTool)(
-    server,
-    name,
-    // Note: `registerAppTool`'s config type is stricter than ours —
-    // casting so `title` / `description` stay optional and the input
-    // schema flows through correctly at the registration layer.
-    {
-      ...title !== void 0 ? { title } : {},
-      ...description !== void 0 ? { description } : {},
-      ...schema !== void 0 ? { inputSchema: schema } : {},
-      _meta: toolMeta,
-      annotations: effectiveAnnotations,
-      ...icons !== void 0 && icons.length > 0 ? { icons } : {}
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    },
-    async (args, extra) => await protectedHandler(args, extra)
-  );
-}
-
-// src/server.ts
 function registerDescriptor(server, tool) {
   const baseMeta = tool.meta ?? {};
   const baseUi = baseMeta.ui ?? {};
   const metaWithIcons = tool.icons && tool.icons.length > 0 ? { ...baseMeta, ui: { ...baseUi, icons: tool.icons } } : baseMeta;
-  (0, import_server2.registerAppTool)(
+  (0, import_server.registerAppTool)(
     server,
     tool.name,
     {
@@ -144,41 +86,55 @@ function registerDocsResource(server, docs) {
     })
   );
 }
-function createSolvaPayMcpServer(options) {
+function buildSolvaPayMcpServer(options) {
   const {
-    additionalTools,
     registerPrompts = true,
     registerDocsResources = true,
     serverName,
     serverVersion = "1.0.0",
+    hideToolsByAudience: _hideToolsByAudience,
     ...descriptorOptions
   } = options;
-  const { tools, resource, prompts, docsResources, buildBootstrapPayload } = (0, import_mcp_core2.buildSolvaPayDescriptors)(descriptorOptions);
+  const descriptors = (0, import_mcp_core.buildSolvaPayDescriptors)(descriptorOptions);
   const effectiveServerName = serverName ?? descriptorOptions.branding?.brandName ?? "solvapay-mcp-server";
-  const server = new import_mcp.McpServer({ name: effectiveServerName, version: serverVersion });
-  for (const tool of tools) {
+  const serverIcons = (0, import_mcp_core.deriveIcons)(descriptorOptions.branding);
+  const server = new import_mcp.McpServer({
+    name: effectiveServerName,
+    version: serverVersion,
+    ...serverIcons ? { icons: serverIcons } : {}
+  });
+  for (const tool of descriptors.tools) {
     registerDescriptor(server, tool);
   }
   if (registerPrompts) {
-    for (const prompt of prompts) {
+    for (const prompt of descriptors.prompts) {
       registerPromptDescriptor(server, prompt);
     }
   }
   if (registerDocsResources) {
-    for (const docs of docsResources) {
+    for (const docs of descriptors.docsResources) {
       registerDocsResource(server, docs);
     }
   }
-  (0, import_server2.registerAppResource)(
+  const resource = descriptors.resource;
+  (0, import_server.registerAppResource)(
     server,
     resource.uri,
     resource.uri,
     {
-      mimeType: import_server2.RESOURCE_MIME_TYPE,
+      mimeType: import_server.RESOURCE_MIME_TYPE,
       _meta: {
         ui: {
           csp: resource.csp,
-          prefersBorder: true
+          // `false` asks the host to skip painting its own outer card /
+          // border around the iframe. The widget paints its own frame
+          // via `.solvapay-mcp-card`, and `<AppHeader>` renders the
+          // merchant mark at the top; a host-painted card on top of
+          // that produced a nested-container look (visible on MCP Jam
+          // with the earlier `true` default). Hosts that honour the
+          // preference (per the MCP Apps spec) now render us flush
+          // inside their conversation surface.
+          prefersBorder: false
         }
       }
     },
@@ -186,32 +142,117 @@ function createSolvaPayMcpServer(options) {
       contents: [
         {
           uri: resource.uri,
-          mimeType: import_server2.RESOURCE_MIME_TYPE,
+          mimeType: import_server.RESOURCE_MIME_TYPE,
           text: await resource.readHtml(),
           _meta: {
             ui: {
               csp: resource.csp,
-              prefersBorder: true
+              prefersBorder: false
             }
           }
         }
       ]
     })
   );
+  return { server, descriptors };
+}
+
+// src/registerPayableTool.ts
+var import_server2 = require("@modelcontextprotocol/ext-apps/server");
+var import_mcp_core2 = require("@solvapay/mcp-core");
+function registerPayableTool(server, name, options) {
+  const {
+    solvaPay,
+    schema,
+    product,
+    title,
+    description,
+    handler,
+    buildBootstrap,
+    getCustomerRef,
+    meta,
+    annotations,
+    icons
+  } = options;
+  const protectedHandler = (0, import_mcp_core2.buildPayableHandler)(
+    solvaPay,
+    { product, buildBootstrap, getCustomerRef },
+    handler
+  );
+  const baseMeta = meta ?? {};
+  const baseUi = baseMeta.ui ?? {};
+  const hasIcons = icons !== void 0 && icons.length > 0;
+  const mergedUi = {
+    ...baseUi,
+    ...hasIcons ? { icons } : {}
+  };
+  const hasUi = Object.keys(mergedUi).length > 0;
+  const toolMeta = hasUi ? { ...baseMeta, ui: mergedUi } : { ...baseMeta };
+  const effectiveAnnotations = {
+    readOnlyHint: true,
+    openWorldHint: true,
+    ...annotations
+  };
+  const hasUiResource = hasUi && typeof mergedUi.resourceUri === "string";
+  const toolConfig = {
+    ...title !== void 0 ? { title } : {},
+    ...description !== void 0 ? { description } : {},
+    ...schema !== void 0 ? { inputSchema: schema } : {},
+    ...Object.keys(toolMeta).length > 0 ? { _meta: toolMeta } : {},
+    annotations: effectiveAnnotations,
+    ...icons !== void 0 && icons.length > 0 ? { icons } : {}
+  };
+  const toolCallback = async (args, extra) => await protectedHandler(args, extra);
+  if (hasUiResource) {
+    return (0, import_server2.registerAppTool)(
+      server,
+      name,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      toolConfig,
+      toolCallback
+    );
+  }
+  return server.registerTool(
+    name,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toolConfig,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toolCallback
+  );
+}
+
+// src/server.ts
+function createSolvaPayMcpServer(options) {
+  const {
+    additionalTools,
+    registerPrompts = true,
+    registerDocsResources = true,
+    serverName,
+    serverVersion = "1.0.0",
+    hideToolsByAudience,
+    ...descriptorOptions
+  } = options;
+  const { server, descriptors } = buildSolvaPayMcpServer({
+    ...descriptorOptions,
+    registerPrompts,
+    registerDocsResources,
+    ...serverName !== void 0 ? { serverName } : {},
+    serverVersion
+  });
   if (additionalTools) {
     const { solvaPay, productRef, resourceUri } = descriptorOptions;
     const registerPayable = (name, opts) => {
       registerPayableTool(server, name, {
         solvaPay,
-        resourceUri,
         ...opts,
         product: opts.product ?? productRef,
-        buildBootstrap: opts.buildBootstrap ?? buildBootstrapPayload
+        buildBootstrap: opts.buildBootstrap ?? descriptors.buildBootstrapPayload
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
       });
     };
     additionalTools({ server, solvaPay, resourceUri, productRef, registerPayable });
   }
+  (0, import_mcp_core.applyHideToolsByAudience)(server, hideToolsByAudience);
   return server;
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -9,12 +9,19 @@ import { SolvaPay } from '@solvapay/server';
  * a paywall-protected MCP tool on the official `@modelcontextprotocol/sdk`
  * `McpServer`.
  *
- * Always advertises `_meta.ui.resourceUri` at the descriptor level so
- * descriptor-reading hosts (MCPJam's `ResultsPanel`, MCP App inspector)
- * learn the widget exists and open the MCP App iframe when a paywall or
- * nudge response lands. `buildPayableHandler` stamps the same metadata
- * on the result envelope as a secondary signal for hosts that key off
- * tool-call results (Claude Desktop, mcp-ui, ChatGPT Apps).
+ * Payable data tools do NOT advertise `_meta.ui.resourceUri` at the
+ * descriptor level by default. Per SEP-1865 / MCP Apps (2026-01-26),
+ * descriptor-advertising means the host MUST open the iframe on every
+ * call — so auto-stamping would flash an empty widget next to every
+ * successful `search_knowledge` / `predict_direction` result. Paywall
+ * / nudge / activation responses are text-only narrations instead,
+ * with the recovery intent tool (`upgrade` / `topup` / `activate_plan`)
+ * named in `content[0].text` and `checkoutUrl` inlined for
+ * terminal-first hosts.
+ *
+ * Merchants who deliberately want the widget opened on every call
+ * (e.g. the tool's UX genuinely is the iframe — rare) can opt in with
+ * `meta: { ui: { resourceUri } }`.
  *
  * Mirrors the positional-`name` shape of `registerAppTool` to keep the
  * convention consistent across the ecosystem.
@@ -30,11 +37,6 @@ type InferHandlerArgs<InputSchema> = [InputSchema] extends [undefined] ? Record<
 interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown> {
     /** The initialised SolvaPay instance used to build `payable({ product }).mcp(handler)`. */
     solvaPay: SolvaPay;
-    /**
-     * UI resource URI the MCP host should open to render the paywall view.
-     * Typically `'ui://<app>/<resource>.html'`.
-     */
-    resourceUri: string;
     /** Zod-compatible input schema (raw shape or discriminated schema). */
     schema?: InputSchema;
     /** SolvaPay product ref to protect this tool against. */
@@ -55,8 +57,8 @@ interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | Any
      *  - `ctx.product` — bootstrap product projection.
      *  - `ctx.respond(data, options?)` — return an envelope. `options`
      *    carries `text` (override `content[0].text`), `nudge` (inline
-     *    upsell strip), and the reserved `units` (V1.1 variable billing —
-     *    V1 silently ignores).
+     *    text-suffix upsell copy), and the reserved `units` (V1.1
+     *    variable billing — V1 silently ignores).
      *  - `ctx.gate(reason?)` — stops handler execution and emits a
      *    paywall response through the adapter's `formatGate` channel.
      *    Rare — the SDK normally fires the paywall automatically via
@@ -70,10 +72,10 @@ interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | Any
      */
     handler: PayableHandler<InferHandlerArgs<InputSchema>, TData>;
     /**
-     * Builds the full `BootstrapPayload` embedded on paywall results so
-     * the React shell renders the paywall view directly from the gate
-     * response. Wire from
-     * `buildSolvaPayDescriptors(...).buildBootstrapPayload`.
+     * Builds the full `BootstrapPayload`. Accepted for forward
+     * compatibility with intent-tool reuse, but the text-only payable
+     * branch does NOT invoke it — gate responses ride through as
+     * `structuredContent = gate` + `content[0].text = gate.message`.
      */
     buildBootstrap?: BuildBootstrapPayloadFn;
     /**
@@ -85,12 +87,12 @@ interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | Any
      * Additional `_meta` merged onto the tool **descriptor** (the tool
      * advertisement returned by `tools/list`).
      *
-     * `registerPayableTool` always injects `ui.resourceUri` at the
-     * descriptor level so hosts that read widget metadata from
-     * `tools/list` (MCPJam's `ResultsPanel` reads
-     * `toolMeta.ui.resourceUri` from the tool definition) can open the
-     * MCP App iframe when a paywall/nudge response lands. Merchant
-     * `meta.ui.resourceUri` overrides the default if supplied.
+     * `registerPayableTool` does NOT inject `ui.resourceUri` by default:
+     * per SEP-1865 descriptor-advertising means hosts MUST open the
+     * iframe on every call, so auto-stamping produced empty widgets on
+     * silent success. Merchants who want the widget opened for every
+     * call can opt in explicitly via
+     * `meta: { ui: { resourceUri: 'ui://...' } }`.
      */
     meta?: Record<string, unknown>;
     /**
@@ -105,9 +107,7 @@ interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | Any
      * Brand icons surfaced on `tools/list`. Hosts that read tool
      * metadata for the chrome strip (ChatGPT, Claude Desktop) swap the
      * default placeholder for this asset. Pass a square logomark for
-     * best results. Merchants typically share one `icons[]` across
-     * every tool — consider a single branding source at the server
-     * level.
+     * best results.
      */
     icons?: SolvaPayToolIcon[];
 }
@@ -122,9 +122,10 @@ declare function registerPayableTool<InputSchema extends ZodRawShapeCompat | Any
  * fresh `McpServer` from the official `@modelcontextprotocol/sdk`,
  * plus the UI resource the `open_*` tools reference.
  *
- * Internals are a thin mapper over `buildSolvaPayDescriptors` from
- * `@solvapay/mcp-core` — this package is the only one importing
- * `@modelcontextprotocol/*`.
+ * Internals delegate to `internal/buildMcpServer` (shared with the
+ * `./fetch` subpath entry) so the two factories register the same 11
+ * tools in the same order off the same `buildSolvaPayDescriptors`
+ * bundle without duplicating the registration loop.
  */
 
 /**
@@ -143,7 +144,7 @@ interface AdditionalToolsContext {
      * Zod `schema` flows through to the handler's `args` parameter so
      * merchants get inferred arg types without a second declaration.
      */
-    registerPayable: <InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown>(name: string, options: Omit<RegisterPayableToolOptions<InputSchema, TData>, 'solvaPay' | 'resourceUri' | 'product'> & {
+    registerPayable: <InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown>(name: string, options: Omit<RegisterPayableToolOptions<InputSchema, TData>, 'solvaPay' | 'product'> & {
         product?: string;
     }) => void;
 }
@@ -171,6 +172,21 @@ interface CreateSolvaPayMcpServerOptions extends BuildSolvaPayDescriptorsOptions
     serverName?: string;
     /** Overrides the default `McpServer` version. */
     serverVersion?: string;
+    /**
+     * After registration, wrap the `tools/list` handler to drop any
+     * tool whose `_meta.audience` matches one of these values. The
+     * tools stay `enabled: true` so `tools/call` still reaches their
+     * handlers — this option only affects the `tools/list` response
+     * shape. Pass `['ui']` when deploying to a text-host MCP client
+     * (Claude Desktop, MCPJam, ChatGPT connectors) that won't embed
+     * the SolvaPay iframe surface, so the LLM's tool catalogue only
+     * surfaces the intent tools (`upgrade` / `manage_account` /
+     * `activate_plan` / `topup`) and merchant-registered data tools.
+     * The hidden transport tools (`create_payment_intent`, etc.) stay
+     * callable so the iframe can still invoke them for server-side
+     * work.
+     */
+    hideToolsByAudience?: string[];
 }
 /**
  * Build the MCP server and register the full SolvaPay tool surface.

package/dist/index.d.ts

@@ -9,12 +9,19 @@ import { SolvaPay } from '@solvapay/server';
  * a paywall-protected MCP tool on the official `@modelcontextprotocol/sdk`
  * `McpServer`.
  *
- * Always advertises `_meta.ui.resourceUri` at the descriptor level so
- * descriptor-reading hosts (MCPJam's `ResultsPanel`, MCP App inspector)
- * learn the widget exists and open the MCP App iframe when a paywall or
- * nudge response lands. `buildPayableHandler` stamps the same metadata
- * on the result envelope as a secondary signal for hosts that key off
- * tool-call results (Claude Desktop, mcp-ui, ChatGPT Apps).
+ * Payable data tools do NOT advertise `_meta.ui.resourceUri` at the
+ * descriptor level by default. Per SEP-1865 / MCP Apps (2026-01-26),
+ * descriptor-advertising means the host MUST open the iframe on every
+ * call — so auto-stamping would flash an empty widget next to every
+ * successful `search_knowledge` / `predict_direction` result. Paywall
+ * / nudge / activation responses are text-only narrations instead,
+ * with the recovery intent tool (`upgrade` / `topup` / `activate_plan`)
+ * named in `content[0].text` and `checkoutUrl` inlined for
+ * terminal-first hosts.
+ *
+ * Merchants who deliberately want the widget opened on every call
+ * (e.g. the tool's UX genuinely is the iframe — rare) can opt in with
+ * `meta: { ui: { resourceUri } }`.
  *
  * Mirrors the positional-`name` shape of `registerAppTool` to keep the
  * convention consistent across the ecosystem.
@@ -30,11 +37,6 @@ type InferHandlerArgs<InputSchema> = [InputSchema] extends [undefined] ? Record<
 interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown> {
     /** The initialised SolvaPay instance used to build `payable({ product }).mcp(handler)`. */
     solvaPay: SolvaPay;
-    /**
-     * UI resource URI the MCP host should open to render the paywall view.
-     * Typically `'ui://<app>/<resource>.html'`.
-     */
-    resourceUri: string;
     /** Zod-compatible input schema (raw shape or discriminated schema). */
     schema?: InputSchema;
     /** SolvaPay product ref to protect this tool against. */
@@ -55,8 +57,8 @@ interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | Any
      *  - `ctx.product` — bootstrap product projection.
      *  - `ctx.respond(data, options?)` — return an envelope. `options`
      *    carries `text` (override `content[0].text`), `nudge` (inline
-     *    upsell strip), and the reserved `units` (V1.1 variable billing —
-     *    V1 silently ignores).
+     *    text-suffix upsell copy), and the reserved `units` (V1.1
+     *    variable billing — V1 silently ignores).
      *  - `ctx.gate(reason?)` — stops handler execution and emits a
      *    paywall response through the adapter's `formatGate` channel.
      *    Rare — the SDK normally fires the paywall automatically via
@@ -70,10 +72,10 @@ interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | Any
      */
     handler: PayableHandler<InferHandlerArgs<InputSchema>, TData>;
     /**
-     * Builds the full `BootstrapPayload` embedded on paywall results so
-     * the React shell renders the paywall view directly from the gate
-     * response. Wire from
-     * `buildSolvaPayDescriptors(...).buildBootstrapPayload`.
+     * Builds the full `BootstrapPayload`. Accepted for forward
+     * compatibility with intent-tool reuse, but the text-only payable
+     * branch does NOT invoke it — gate responses ride through as
+     * `structuredContent = gate` + `content[0].text = gate.message`.
      */
     buildBootstrap?: BuildBootstrapPayloadFn;
     /**
@@ -85,12 +87,12 @@ interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | Any
      * Additional `_meta` merged onto the tool **descriptor** (the tool
      * advertisement returned by `tools/list`).
      *
-     * `registerPayableTool` always injects `ui.resourceUri` at the
-     * descriptor level so hosts that read widget metadata from
-     * `tools/list` (MCPJam's `ResultsPanel` reads
-     * `toolMeta.ui.resourceUri` from the tool definition) can open the
-     * MCP App iframe when a paywall/nudge response lands. Merchant
-     * `meta.ui.resourceUri` overrides the default if supplied.
+     * `registerPayableTool` does NOT inject `ui.resourceUri` by default:
+     * per SEP-1865 descriptor-advertising means hosts MUST open the
+     * iframe on every call, so auto-stamping produced empty widgets on
+     * silent success. Merchants who want the widget opened for every
+     * call can opt in explicitly via
+     * `meta: { ui: { resourceUri: 'ui://...' } }`.
      */
     meta?: Record<string, unknown>;
     /**
@@ -105,9 +107,7 @@ interface RegisterPayableToolOptions<InputSchema extends ZodRawShapeCompat | Any
      * Brand icons surfaced on `tools/list`. Hosts that read tool
      * metadata for the chrome strip (ChatGPT, Claude Desktop) swap the
      * default placeholder for this asset. Pass a square logomark for
-     * best results. Merchants typically share one `icons[]` across
-     * every tool — consider a single branding source at the server
-     * level.
+     * best results.
      */
     icons?: SolvaPayToolIcon[];
 }
@@ -122,9 +122,10 @@ declare function registerPayableTool<InputSchema extends ZodRawShapeCompat | Any
  * fresh `McpServer` from the official `@modelcontextprotocol/sdk`,
  * plus the UI resource the `open_*` tools reference.
  *
- * Internals are a thin mapper over `buildSolvaPayDescriptors` from
- * `@solvapay/mcp-core` — this package is the only one importing
- * `@modelcontextprotocol/*`.
+ * Internals delegate to `internal/buildMcpServer` (shared with the
+ * `./fetch` subpath entry) so the two factories register the same 11
+ * tools in the same order off the same `buildSolvaPayDescriptors`
+ * bundle without duplicating the registration loop.
  */
 
 /**
@@ -143,7 +144,7 @@ interface AdditionalToolsContext {
      * Zod `schema` flows through to the handler's `args` parameter so
      * merchants get inferred arg types without a second declaration.
      */
-    registerPayable: <InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown>(name: string, options: Omit<RegisterPayableToolOptions<InputSchema, TData>, 'solvaPay' | 'resourceUri' | 'product'> & {
+    registerPayable: <InputSchema extends ZodRawShapeCompat | AnySchema | undefined = undefined, TData = unknown>(name: string, options: Omit<RegisterPayableToolOptions<InputSchema, TData>, 'solvaPay' | 'product'> & {
         product?: string;
     }) => void;
 }
@@ -171,6 +172,21 @@ interface CreateSolvaPayMcpServerOptions extends BuildSolvaPayDescriptorsOptions
     serverName?: string;
     /** Overrides the default `McpServer` version. */
     serverVersion?: string;
+    /**
+     * After registration, wrap the `tools/list` handler to drop any
+     * tool whose `_meta.audience` matches one of these values. The
+     * tools stay `enabled: true` so `tools/call` still reaches their
+     * handlers — this option only affects the `tools/list` response
+     * shape. Pass `['ui']` when deploying to a text-host MCP client
+     * (Claude Desktop, MCPJam, ChatGPT connectors) that won't embed
+     * the SolvaPay iframe surface, so the LLM's tool catalogue only
+     * surfaces the intent tools (`upgrade` / `manage_account` /
+     * `activate_plan` / `topup`) and merchant-registered data tools.
+     * The hidden transport tools (`create_payment_intent`, etc.) stay
+     * callable so the iframe can still invoke them for server-side
+     * work.
+     */
+    hideToolsByAudience?: string[];
 }
 /**
  * Build the MCP server and register the full SolvaPay tool surface.