@solvapay/mcp-core 0.2.3 → 0.2.4

package/dist/index.cjs

@@ -53,6 +53,7 @@ __export(index_exports, {
   createBuildBootstrapPayload: () => createBuildBootstrapPayload,
   decodeJwtPayload: () => decodeJwtPayload,
   defaultGetCustomerRef: () => defaultGetCustomerRef,
+  defaultIsChatGptRequest: () => defaultIsChatGptRequest,
   deriveIcons: () => deriveIcons,
   enrichPurchase: () => enrichPurchase,
   extractBearerToken: () => extractBearerToken,
@@ -503,9 +504,24 @@ function mergeCsp(overrides, apiBaseUrl) {
 }
 
 // src/hideToolsByAudience.ts
-function applyHideToolsByAudience(server, audiences) {
+var CHATGPT_CLIENT_RE = /openai-mcp/i;
+function readHeader(headers, name) {
+  if (!headers) return void 0;
+  const raw = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(raw)) return raw[0];
+  return typeof raw === "string" ? raw : void 0;
+}
+function defaultIsChatGptRequest(ctx) {
+  const ua = readHeader(ctx.extra?.requestInfo?.headers, "user-agent");
+  if (ua && CHATGPT_CLIENT_RE.test(ua)) return true;
+  const clientVersion = ctx.server?.server?.getClientVersion?.();
+  const clientName = typeof clientVersion?.name === "string" ? clientVersion.name : void 0;
+  return clientName !== void 0 && CHATGPT_CLIENT_RE.test(clientName);
+}
+function applyHideToolsByAudience(server, audiences, options = {}) {
   if (!audiences || audiences.length === 0) return;
   const hidden = new Set(audiences);
+  const bypassWhen = options.bypassWhen ?? defaultIsChatGptRequest;
   const inner = server.server;
   if (!inner || typeof inner !== "object" || !(inner._requestHandlers instanceof Map)) {
     return;
@@ -513,8 +529,26 @@ function applyHideToolsByAudience(server, audiences) {
   const handlers = inner._requestHandlers;
   const original = handlers.get("tools/list");
   if (!original) return;
+  const warned = /* @__PURE__ */ new Set();
   handlers.set("tools/list", async (req, extra) => {
     const res = await original(req, extra);
+    if (bypassWhen({
+      server,
+      extra
+    })) {
+      const ua = readHeader(
+        extra?.requestInfo?.headers,
+        "user-agent"
+      );
+      const context = ua ? `ua=${ua}` : "no user-agent";
+      if (!warned.has(context)) {
+        warned.add(context);
+        console.warn(
+          `[solvapay/mcp] hideToolsByAudience filter bypassed (${context}); returning full tools/list catalog.`
+        );
+      }
+      return res;
+    }
     const tools = Array.isArray(res?.tools) ? res.tools : [];
     return {
       ...res,
@@ -766,7 +800,10 @@ function buildSolvaPayDescriptors(options) {
       handler: async (args, extra) => trace(name, args, extra, async () => {
         const mode = parseMode(args.mode);
         const data = await buildBootstrapPayload(view, extra);
-        return narratedToolResult(name, data, mode, toolMeta);
+        return narratedToolResult(name, data, mode, {
+          ...toolMeta,
+          "openai/widgetSessionId": crypto.randomUUID()
+        });
       })
     });
   };
@@ -967,7 +1004,7 @@ function buildSolvaPayDescriptors(options) {
           MCP_TOOL_NAMES.activatePlan,
           await buildBootstrapPayload("checkout", extra),
           mode,
-          toolMeta
+          { ...toolMeta, "openai/widgetSessionId": crypto.randomUUID() }
         );
       }
       const auth = requireCustomerRef(extra);
@@ -1377,6 +1414,7 @@ function buildAuthInfoFromBearer(authorization, options = {}) {
   createBuildBootstrapPayload,
   decodeJwtPayload,
   defaultGetCustomerRef,
+  defaultIsChatGptRequest,
   deriveIcons,
   enrichPurchase,
   extractBearerToken,

package/dist/index.d.cts

@@ -734,6 +734,12 @@ declare function parseMode(raw: unknown): SolvaPayToolMode;
  *
  * The narrator is picked by the `tool` name; unknown tools fall back
  * to the JSON dump that `toolResult` produces today.
+ *
+ * Meta keys other than `ui` (notably `openai/widgetSessionId`, the
+ * ChatGPT MCP routing-bug workaround stamped by intent tools — see
+ * the descriptors.ts top-of-file comment) are preserved across all
+ * three modes. Don't strip additional `_meta` keys here without
+ * checking `descriptors.ts` first.
  */
 declare function narratedToolResult(tool: IntentTool | string, data: BootstrapPayload, mode?: SolvaPayToolMode, baseMeta?: Record<string, unknown> | undefined): SolvaPayCallToolResult;
 /**
@@ -861,7 +867,7 @@ declare const SOLVAPAY_DEFAULT_CSP: Required<SolvaPayMcpCsp>;
 declare function mergeCsp(overrides: SolvaPayMcpCsp | undefined, apiBaseUrl?: string): Required<SolvaPayMcpCsp>;
 
 /**
- * `applyHideToolsByAudience(server, audiences)` — wraps the
+ * `applyHideToolsByAudience(server, audiences, options?)` — wraps the
  * `tools/list` request handler on an `@modelcontextprotocol/sdk`
  * `McpServer` so tool descriptors whose `_meta.audience` matches one
  * of the supplied values are filtered out of the response.
@@ -869,21 +875,50 @@ declare function mergeCsp(overrides: SolvaPayMcpCsp | undefined, apiBaseUrl?: st
  * The tools stay `enabled: true` on the server, so `tools/call` still
  * reaches their handlers — this helper only affects the `tools/list`
  * response shape. Use `['ui']` when deploying to a text-host MCP
- * client (Claude Desktop, MCPJam, ChatGPT connectors) that won't
+ * client (Claude Desktop, MCPJam, ChatGPT connector) that won't
  * embed the SolvaPay iframe surface, while still allowing the iframe
  * to invoke the hidden transport tools (`create_payment_intent` etc.)
  * for server-side work.
  *
- * Internal-map reach-in rationale: `Protocol.setRequestHandler`
- * contains an `assertCanSetRequestHandler` guard that fails when the
- * SDK has already registered a handler for the method during
- * registration — i.e. `tools/list` after any tool registration. The
- * guard only fires through the public wrapper; the underlying
- * `_requestHandlers` map accepts a replacement silently. Touching the
- * map directly therefore sidesteps the guard without going through
- * public API surface that could change in a minor SDK bump. The one
- * piece of SDK-internal knowledge we live with until the SDK ships a
- * first-class "replace handler" affordance.
+ * # ChatGPT auto-bypass
+ *
+ * ChatGPT's Custom Connector gateway re-validates iframe-initiated
+ * `tools/call` against the cached `tools/list` catalog. A tool hidden
+ * from `tools/list` becomes uncallable from the embedded iframe and
+ * surfaces in the UI as `MCP error -32000: MCP Resource not found`.
+ *
+ * To keep the cleaner LLM-facing catalog on every other host while
+ * the iframe still works on ChatGPT, the default behaviour
+ * automatically returns the **full** unfiltered catalog when the
+ * incoming `tools/list` request originates from ChatGPT — detected by
+ * matching `request.headers['user-agent']` and the post-`initialize`
+ * `server.getClientVersion().name` against `/openai-mcp/i`. The first
+ * triggers on the discovery `tools/list` ChatGPT issues before
+ * `initialize` (so `getClientVersion()` is empty); the second is a
+ * defence-in-depth fallback for any future relay that strips the
+ * client UA.
+ *
+ * The User-Agent shape was confirmed live against ChatGPT's MCP
+ * runtime (`openai-mcp/1.0.0 (ChatGPT)` as of 2026-05). The pattern
+ * is intentionally broad so a UA bump to `openai-mcp/2.x` keeps
+ * working without code changes.
+ *
+ * Override the detection by passing `bypassWhen` — useful when a
+ * future iframe-capable host needs the same treatment, or when
+ * ChatGPT-served deployments want the LLM-narrow catalog regardless
+ * (`bypassWhen: () => false`).
+ *
+ * # Internal-map reach-in rationale
+ *
+ * `Protocol.setRequestHandler` contains an `assertCanSetRequestHandler`
+ * guard that fails when the SDK has already registered a handler for
+ * the method during registration — i.e. `tools/list` after any tool
+ * registration. The guard only fires through the public wrapper; the
+ * underlying `_requestHandlers` map accepts a replacement silently.
+ * Touching the map directly therefore sidesteps the guard without
+ * going through public API surface that could change in a minor SDK
+ * bump. The one piece of SDK-internal knowledge we live with until
+ * the SDK ships a first-class "replace handler" affordance.
  *
  * No-op when `audiences` is empty or falsy.
  *
@@ -892,7 +927,58 @@ declare function mergeCsp(overrides: SolvaPayMcpCsp | undefined, apiBaseUrl?: st
  * `@solvapay/mcp/fetch` (unified `createSolvaPayMcpFetch`) can apply
  * the same filter without each re-implementing the reach-in.
  */
-declare function applyHideToolsByAudience(server: unknown, audiences: readonly string[] | undefined): void;
+/**
+ * Headers shape exposed by the MCP SDK's `RequestHandlerExtra.requestInfo`.
+ * Mirrors `IsomorphicHeaders` from the SDK without taking a type dep.
+ */
+type IsomorphicHeaders = Record<string, string | string[] | undefined>;
+/**
+ * Subset of `RequestHandlerExtra` (from `@modelcontextprotocol/sdk`)
+ * that the bypass predicate inspects. Typed loosely so we don't
+ * couple to the SDK's exact shape.
+ */
+interface ApplyHideToolsByAudienceExtra {
+    requestInfo?: {
+        headers?: IsomorphicHeaders;
+    } | undefined;
+    [key: string]: unknown;
+}
+interface ApplyHideToolsByAudienceContext {
+    /** The MCP server instance the filter is being applied to. */
+    server: unknown;
+    /**
+     * The `RequestHandlerExtra` the SDK passed to the wrapped
+     * `tools/list` handler. May be undefined for non-HTTP transports
+     * (e.g. stdio) where there's no request information.
+     */
+    extra?: ApplyHideToolsByAudienceExtra;
+}
+type HideToolsByAudienceBypass = (ctx: ApplyHideToolsByAudienceContext) => boolean;
+interface ApplyHideToolsByAudienceOptions {
+    /**
+     * When this predicate returns `true` for an incoming `tools/list`
+     * request, the audience filter is skipped and the full catalog is
+     * returned. Defaults to `defaultIsChatGptRequest` — see the file
+     * header for the rationale.
+     *
+     * Pass an integrator-supplied predicate to extend the bypass to
+     * another host (e.g. a future iframe-capable client), or `() =>
+     * false` to apply the filter unconditionally.
+     */
+    bypassWhen?: HideToolsByAudienceBypass;
+}
+/**
+ * Default `bypassWhen` — returns true when the incoming request looks
+ * like it's coming from ChatGPT's MCP runtime. Two signals:
+ *
+ *  1. HTTP `User-Agent` header (works on the pre-`initialize`
+ *     discovery `tools/list`, so we have a signal even before the
+ *     SDK's `getClientVersion()` is populated).
+ *  2. `server.getClientVersion()?.name` (covers any host that relays
+ *     ChatGPT requests without forwarding the upstream UA).
+ */
+declare function defaultIsChatGptRequest(ctx: ApplyHideToolsByAudienceContext): boolean;
+declare function applyHideToolsByAudience(server: unknown, audiences: readonly string[] | undefined, options?: ApplyHideToolsByAudienceOptions): void;
 
 /**
  * `buildSolvaPayDescriptors(options)` — framework-neutral tool surface
@@ -905,6 +991,28 @@ declare function applyHideToolsByAudience(server: unknown, audiences: readonly s
  * mechanical difference: instead of calling `registerAppTool(server, ...)`,
  * we push `{ name, handler, ... }` onto a `tools[]` array the adapter
  * iterates.
+ *
+ * ----
+ *
+ * `_meta["openai/widgetSessionId"]` workaround. Every intent-tool
+ * response stamps a freshly-minted UUID on `_meta["openai/widgetSessionId"]`.
+ * This is a low-risk forward-looking workaround for the ChatGPT MCP
+ * connector's stale `link_<id>` routing bug, where the host returns
+ * `-32000 MCP Resource not found` on the second `tools/call` of a
+ * session even though the call never reaches the server. A fresh UUID
+ * per invocation gives the host a routing key that changes every call,
+ * which the OpenAI Apps SDK community thread reports unsticks the
+ * failure mode.
+ *
+ * Sources:
+ *   - https://community.openai.com/t/connector-tool-calls-generating-fresh-mcp-session-each-invocation/1364975
+ *   - https://github.com/openai/openai-apps-sdk-examples/issues/165
+ *   - https://developers.openai.com/apps-sdk/reference/ (`_meta` payload)
+ *   - openai/openai-apps-sdk-examples shopping_cart_python uses the
+ *     same `meta["openai/widgetSessionId"]` shape.
+ *
+ * Removable once the upstream bug ships a fix; safe on any host that
+ * doesn't consume the key.
  */
 
 /**
@@ -1196,4 +1304,4 @@ interface BuildAuthInfoFromBearerOptions extends McpBearerCustomerRefOptions {
 }
 declare function buildAuthInfoFromBearer(authorization?: string | null, options?: BuildAuthInfoFromBearerOptions): McpToolExtra['authInfo'] | null;
 
-export { type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type IntentTool, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpCsp, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, applyHideToolsByAudience, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, deriveIcons, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, mergeCsp, narrateActivatePlan, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resolveOAuthPaths, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };
+export { type ApplyHideToolsByAudienceContext, type ApplyHideToolsByAudienceExtra, type ApplyHideToolsByAudienceOptions, type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type HideToolsByAudienceBypass, type IntentTool, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpCsp, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, applyHideToolsByAudience, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, defaultIsChatGptRequest, deriveIcons, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, mergeCsp, narrateActivatePlan, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resolveOAuthPaths, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };

package/dist/index.d.ts

@@ -734,6 +734,12 @@ declare function parseMode(raw: unknown): SolvaPayToolMode;
  *
  * The narrator is picked by the `tool` name; unknown tools fall back
  * to the JSON dump that `toolResult` produces today.
+ *
+ * Meta keys other than `ui` (notably `openai/widgetSessionId`, the
+ * ChatGPT MCP routing-bug workaround stamped by intent tools — see
+ * the descriptors.ts top-of-file comment) are preserved across all
+ * three modes. Don't strip additional `_meta` keys here without
+ * checking `descriptors.ts` first.
  */
 declare function narratedToolResult(tool: IntentTool | string, data: BootstrapPayload, mode?: SolvaPayToolMode, baseMeta?: Record<string, unknown> | undefined): SolvaPayCallToolResult;
 /**
@@ -861,7 +867,7 @@ declare const SOLVAPAY_DEFAULT_CSP: Required<SolvaPayMcpCsp>;
 declare function mergeCsp(overrides: SolvaPayMcpCsp | undefined, apiBaseUrl?: string): Required<SolvaPayMcpCsp>;
 
 /**
- * `applyHideToolsByAudience(server, audiences)` — wraps the
+ * `applyHideToolsByAudience(server, audiences, options?)` — wraps the
  * `tools/list` request handler on an `@modelcontextprotocol/sdk`
  * `McpServer` so tool descriptors whose `_meta.audience` matches one
  * of the supplied values are filtered out of the response.
@@ -869,21 +875,50 @@ declare function mergeCsp(overrides: SolvaPayMcpCsp | undefined, apiBaseUrl?: st
  * The tools stay `enabled: true` on the server, so `tools/call` still
  * reaches their handlers — this helper only affects the `tools/list`
  * response shape. Use `['ui']` when deploying to a text-host MCP
- * client (Claude Desktop, MCPJam, ChatGPT connectors) that won't
+ * client (Claude Desktop, MCPJam, ChatGPT connector) that won't
  * embed the SolvaPay iframe surface, while still allowing the iframe
  * to invoke the hidden transport tools (`create_payment_intent` etc.)
  * for server-side work.
  *
- * Internal-map reach-in rationale: `Protocol.setRequestHandler`
- * contains an `assertCanSetRequestHandler` guard that fails when the
- * SDK has already registered a handler for the method during
- * registration — i.e. `tools/list` after any tool registration. The
- * guard only fires through the public wrapper; the underlying
- * `_requestHandlers` map accepts a replacement silently. Touching the
- * map directly therefore sidesteps the guard without going through
- * public API surface that could change in a minor SDK bump. The one
- * piece of SDK-internal knowledge we live with until the SDK ships a
- * first-class "replace handler" affordance.
+ * # ChatGPT auto-bypass
+ *
+ * ChatGPT's Custom Connector gateway re-validates iframe-initiated
+ * `tools/call` against the cached `tools/list` catalog. A tool hidden
+ * from `tools/list` becomes uncallable from the embedded iframe and
+ * surfaces in the UI as `MCP error -32000: MCP Resource not found`.
+ *
+ * To keep the cleaner LLM-facing catalog on every other host while
+ * the iframe still works on ChatGPT, the default behaviour
+ * automatically returns the **full** unfiltered catalog when the
+ * incoming `tools/list` request originates from ChatGPT — detected by
+ * matching `request.headers['user-agent']` and the post-`initialize`
+ * `server.getClientVersion().name` against `/openai-mcp/i`. The first
+ * triggers on the discovery `tools/list` ChatGPT issues before
+ * `initialize` (so `getClientVersion()` is empty); the second is a
+ * defence-in-depth fallback for any future relay that strips the
+ * client UA.
+ *
+ * The User-Agent shape was confirmed live against ChatGPT's MCP
+ * runtime (`openai-mcp/1.0.0 (ChatGPT)` as of 2026-05). The pattern
+ * is intentionally broad so a UA bump to `openai-mcp/2.x` keeps
+ * working without code changes.
+ *
+ * Override the detection by passing `bypassWhen` — useful when a
+ * future iframe-capable host needs the same treatment, or when
+ * ChatGPT-served deployments want the LLM-narrow catalog regardless
+ * (`bypassWhen: () => false`).
+ *
+ * # Internal-map reach-in rationale
+ *
+ * `Protocol.setRequestHandler` contains an `assertCanSetRequestHandler`
+ * guard that fails when the SDK has already registered a handler for
+ * the method during registration — i.e. `tools/list` after any tool
+ * registration. The guard only fires through the public wrapper; the
+ * underlying `_requestHandlers` map accepts a replacement silently.
+ * Touching the map directly therefore sidesteps the guard without
+ * going through public API surface that could change in a minor SDK
+ * bump. The one piece of SDK-internal knowledge we live with until
+ * the SDK ships a first-class "replace handler" affordance.
  *
  * No-op when `audiences` is empty or falsy.
  *
@@ -892,7 +927,58 @@ declare function mergeCsp(overrides: SolvaPayMcpCsp | undefined, apiBaseUrl?: st
  * `@solvapay/mcp/fetch` (unified `createSolvaPayMcpFetch`) can apply
  * the same filter without each re-implementing the reach-in.
  */
-declare function applyHideToolsByAudience(server: unknown, audiences: readonly string[] | undefined): void;
+/**
+ * Headers shape exposed by the MCP SDK's `RequestHandlerExtra.requestInfo`.
+ * Mirrors `IsomorphicHeaders` from the SDK without taking a type dep.
+ */
+type IsomorphicHeaders = Record<string, string | string[] | undefined>;
+/**
+ * Subset of `RequestHandlerExtra` (from `@modelcontextprotocol/sdk`)
+ * that the bypass predicate inspects. Typed loosely so we don't
+ * couple to the SDK's exact shape.
+ */
+interface ApplyHideToolsByAudienceExtra {
+    requestInfo?: {
+        headers?: IsomorphicHeaders;
+    } | undefined;
+    [key: string]: unknown;
+}
+interface ApplyHideToolsByAudienceContext {
+    /** The MCP server instance the filter is being applied to. */
+    server: unknown;
+    /**
+     * The `RequestHandlerExtra` the SDK passed to the wrapped
+     * `tools/list` handler. May be undefined for non-HTTP transports
+     * (e.g. stdio) where there's no request information.
+     */
+    extra?: ApplyHideToolsByAudienceExtra;
+}
+type HideToolsByAudienceBypass = (ctx: ApplyHideToolsByAudienceContext) => boolean;
+interface ApplyHideToolsByAudienceOptions {
+    /**
+     * When this predicate returns `true` for an incoming `tools/list`
+     * request, the audience filter is skipped and the full catalog is
+     * returned. Defaults to `defaultIsChatGptRequest` — see the file
+     * header for the rationale.
+     *
+     * Pass an integrator-supplied predicate to extend the bypass to
+     * another host (e.g. a future iframe-capable client), or `() =>
+     * false` to apply the filter unconditionally.
+     */
+    bypassWhen?: HideToolsByAudienceBypass;
+}
+/**
+ * Default `bypassWhen` — returns true when the incoming request looks
+ * like it's coming from ChatGPT's MCP runtime. Two signals:
+ *
+ *  1. HTTP `User-Agent` header (works on the pre-`initialize`
+ *     discovery `tools/list`, so we have a signal even before the
+ *     SDK's `getClientVersion()` is populated).
+ *  2. `server.getClientVersion()?.name` (covers any host that relays
+ *     ChatGPT requests without forwarding the upstream UA).
+ */
+declare function defaultIsChatGptRequest(ctx: ApplyHideToolsByAudienceContext): boolean;
+declare function applyHideToolsByAudience(server: unknown, audiences: readonly string[] | undefined, options?: ApplyHideToolsByAudienceOptions): void;
 
 /**
  * `buildSolvaPayDescriptors(options)` — framework-neutral tool surface
@@ -905,6 +991,28 @@ declare function applyHideToolsByAudience(server: unknown, audiences: readonly s
  * mechanical difference: instead of calling `registerAppTool(server, ...)`,
  * we push `{ name, handler, ... }` onto a `tools[]` array the adapter
  * iterates.
+ *
+ * ----
+ *
+ * `_meta["openai/widgetSessionId"]` workaround. Every intent-tool
+ * response stamps a freshly-minted UUID on `_meta["openai/widgetSessionId"]`.
+ * This is a low-risk forward-looking workaround for the ChatGPT MCP
+ * connector's stale `link_<id>` routing bug, where the host returns
+ * `-32000 MCP Resource not found` on the second `tools/call` of a
+ * session even though the call never reaches the server. A fresh UUID
+ * per invocation gives the host a routing key that changes every call,
+ * which the OpenAI Apps SDK community thread reports unsticks the
+ * failure mode.
+ *
+ * Sources:
+ *   - https://community.openai.com/t/connector-tool-calls-generating-fresh-mcp-session-each-invocation/1364975
+ *   - https://github.com/openai/openai-apps-sdk-examples/issues/165
+ *   - https://developers.openai.com/apps-sdk/reference/ (`_meta` payload)
+ *   - openai/openai-apps-sdk-examples shopping_cart_python uses the
+ *     same `meta["openai/widgetSessionId"]` shape.
+ *
+ * Removable once the upstream bug ships a fix; safe on any host that
+ * doesn't consume the key.
  */
 
 /**
@@ -1196,4 +1304,4 @@ interface BuildAuthInfoFromBearerOptions extends McpBearerCustomerRefOptions {
 }
 declare function buildAuthInfoFromBearer(authorization?: string | null, options?: BuildAuthInfoFromBearerOptions): McpToolExtra['authInfo'] | null;
 
-export { type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type IntentTool, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpCsp, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, applyHideToolsByAudience, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, deriveIcons, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, mergeCsp, narrateActivatePlan, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resolveOAuthPaths, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };
+export { type ApplyHideToolsByAudienceContext, type ApplyHideToolsByAudienceExtra, type ApplyHideToolsByAudienceOptions, type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type HideToolsByAudienceBypass, type IntentTool, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpCsp, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, applyHideToolsByAudience, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, defaultIsChatGptRequest, deriveIcons, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, mergeCsp, narrateActivatePlan, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resolveOAuthPaths, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };

package/dist/index.js

@@ -424,9 +424,24 @@ function mergeCsp(overrides, apiBaseUrl) {
 }
 
 // src/hideToolsByAudience.ts
-function applyHideToolsByAudience(server, audiences) {
+var CHATGPT_CLIENT_RE = /openai-mcp/i;
+function readHeader(headers, name) {
+  if (!headers) return void 0;
+  const raw = headers[name] ?? headers[name.toLowerCase()];
+  if (Array.isArray(raw)) return raw[0];
+  return typeof raw === "string" ? raw : void 0;
+}
+function defaultIsChatGptRequest(ctx) {
+  const ua = readHeader(ctx.extra?.requestInfo?.headers, "user-agent");
+  if (ua && CHATGPT_CLIENT_RE.test(ua)) return true;
+  const clientVersion = ctx.server?.server?.getClientVersion?.();
+  const clientName = typeof clientVersion?.name === "string" ? clientVersion.name : void 0;
+  return clientName !== void 0 && CHATGPT_CLIENT_RE.test(clientName);
+}
+function applyHideToolsByAudience(server, audiences, options = {}) {
   if (!audiences || audiences.length === 0) return;
   const hidden = new Set(audiences);
+  const bypassWhen = options.bypassWhen ?? defaultIsChatGptRequest;
   const inner = server.server;
   if (!inner || typeof inner !== "object" || !(inner._requestHandlers instanceof Map)) {
     return;
@@ -434,8 +449,26 @@ function applyHideToolsByAudience(server, audiences) {
   const handlers = inner._requestHandlers;
   const original = handlers.get("tools/list");
   if (!original) return;
+  const warned = /* @__PURE__ */ new Set();
   handlers.set("tools/list", async (req, extra) => {
     const res = await original(req, extra);
+    if (bypassWhen({
+      server,
+      extra
+    })) {
+      const ua = readHeader(
+        extra?.requestInfo?.headers,
+        "user-agent"
+      );
+      const context = ua ? `ua=${ua}` : "no user-agent";
+      if (!warned.has(context)) {
+        warned.add(context);
+        console.warn(
+          `[solvapay/mcp] hideToolsByAudience filter bypassed (${context}); returning full tools/list catalog.`
+        );
+      }
+      return res;
+    }
     const tools = Array.isArray(res?.tools) ? res.tools : [];
     return {
       ...res,
@@ -706,7 +739,10 @@ function buildSolvaPayDescriptors(options) {
       handler: async (args, extra) => trace(name, args, extra, async () => {
         const mode = parseMode(args.mode);
         const data = await buildBootstrapPayload(view, extra);
-        return narratedToolResult(name, data, mode, toolMeta);
+        return narratedToolResult(name, data, mode, {
+          ...toolMeta,
+          "openai/widgetSessionId": crypto.randomUUID()
+        });
       })
     });
   };
@@ -907,7 +943,7 @@ function buildSolvaPayDescriptors(options) {
           MCP_TOOL_NAMES.activatePlan,
           await buildBootstrapPayload("checkout", extra),
           mode,
-          toolMeta
+          { ...toolMeta, "openai/widgetSessionId": crypto.randomUUID() }
         );
       }
       const auth = requireCustomerRef(extra);
@@ -1316,6 +1352,7 @@ export {
   createBuildBootstrapPayload,
   decodeJwtPayload,
   defaultGetCustomerRef,
+  defaultIsChatGptRequest,
   deriveIcons,
   enrichPurchase,
   extractBearerToken,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/mcp-core",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Framework-neutral MCP contracts for the SolvaPay SDK (tool names, descriptors, payable handler, paywall meta, CSP, bootstrap payload, OAuth discovery JSON builders, bearer/JWT helpers).",
   "type": "module",
   "main": "./dist/index.cjs",