@apiosk/mcp 1.3.1 → 1.7.0

package/src/runtime.mjs

@@ -17,10 +17,130 @@ import {
   saveLocalApioskConfig,
 } from "./local-config.mjs";
 import { createLocalWalletStore } from "./wallet-store.mjs";
+import { logToolCall } from "./observability.mjs";
+import {
+  hostedCreateWalletToken,
+  hostedCreateWalletUnavailable,
+  hostedDeleteWallet,
+  hostedDeleteWalletToken,
+  hostedListWallets,
+  hostedListWalletTokens,
+  hostedUpdateWallet,
+  hostedUpdateWalletToken,
+  hostedWalletActivity,
+} from "./hosted-wallets.mjs";
+import {
+  PUBLISHER_TOOLS,
+  handlePublisherTool,
+  isPublisherTool,
+} from "./publisher.mjs";
+import { DISCOVER_TOOL, runDiscover } from "./discovery.mjs";
+import { searchKnownSources } from "./source-registry.mjs";
+import { INSPECT_TOOL, runInspect } from "./x402-inspect.mjs";
+import { FETCH_PAID_TOOL, runFetchPaid } from "./external-fetch.mjs";
 
 const DEFAULT_LIMIT = 25;
 const CACHE_TTL_MS = 60_000;
 const DEFAULT_GATEWAY_BASE_URL = "https://gateway.apiosk.com";
+const HOSTED_OAUTH_SCOPE = "mcp:tools";
+
+// Permissive default output schema advertised for every tool that does not
+// declare its own. MCP clients (ChatGPT, Claude, …) flag tools with no
+// outputSchema as "output schema recommended"; declaring one clears that hint.
+// Apiosk tool results are always returned as a JSON object in structuredContent
+// (see content()), so an open object schema both documents that contract and
+// validates every success payload without risking false rejections on the
+// varied per-tool result shapes. Individual tools can still ship a tighter
+// schema (e.g. dynamic listings via listing_metadata.mcp_tool.outputSchema),
+// which is preserved as-is.
+const DEFAULT_TOOL_OUTPUT_SCHEMA = {
+  type: "object",
+  additionalProperties: true,
+  description:
+    "Structured JSON result of the tool call. Mirrors the human-readable text content; the exact fields depend on the tool (an `error` field is present when the call fails).",
+};
+
+// Behaviour hints (MCP tool annotations). Clients like ChatGPT default an
+// un-annotated tool to the most cautious badges — "destructive" and
+// "open world" — so every write tool that ships no annotations reads as
+// dangerous. These presets make the badges accurate: wallet/account/keystore
+// management is a closed domain (the user's own Apiosk account), publishing
+// wires up an external upstream (open world), and deletes are destructive.
+const READ_ONLY_ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const CREATE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+const UPDATE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const DELETE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };
+const SETUP_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+const PUBLISH_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+const PUBLISH_UPDATE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
+const PUBLISH_DELETE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true };
+// Dynamic per-listing tools call arbitrary paid third-party APIs and spend
+// USDC, so an unspecified listing gets the same hints as apiosk_execute.
+const DYNAMIC_EXECUTE_ANNOTATIONS = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
+
+// Static tools whose literals don't already declare `annotations`. Discovery
+// and publisher (sk_live_) tools annotate themselves inline and are absent here.
+const TOOL_ANNOTATIONS = {
+  // Managed (dashboard) wallet + account tools — closed Apiosk-account domain.
+  apiosk_list_wallets: READ_ONLY_ANNOTATIONS,
+  apiosk_get_wallet_activity: READ_ONLY_ANNOTATIONS,
+  apiosk_list_wallet_api_keys: READ_ONLY_ANNOTATIONS,
+  apiosk_show_wallet_funding: READ_ONLY_ANNOTATIONS,
+  apiosk_create_wallet: CREATE_ANNOTATIONS,
+  apiosk_create_wallet_connect_string: CREATE_ANNOTATIONS,
+  apiosk_create_wallet_api_key: CREATE_ANNOTATIONS,
+  apiosk_create_account: CREATE_ANNOTATIONS,
+  apiosk_update_wallet: UPDATE_ANNOTATIONS,
+  apiosk_update_wallet_api_key: UPDATE_ANNOTATIONS,
+  apiosk_sign_in: UPDATE_ANNOTATIONS,
+  apiosk_delete_wallet: DELETE_ANNOTATIONS,
+  apiosk_delete_wallet_api_key: DELETE_ANNOTATIONS,
+  // Local (stdio) wallet keystore tools.
+  apiosk_wallet_list: READ_ONLY_ANNOTATIONS,
+  apiosk_wallet_reveal_secret: READ_ONLY_ANNOTATIONS,
+  apiosk_configure: READ_ONLY_ANNOTATIONS,
+  apiosk_wallet_create: CREATE_ANNOTATIONS,
+  apiosk_wallet_select: UPDATE_ANNOTATIONS,
+  apiosk_wallet_update: UPDATE_ANNOTATIONS,
+  apiosk_wallet_save_secret: UPDATE_ANNOTATIONS,
+  apiosk_wallet_delete: DELETE_ANNOTATIONS,
+  apiosk_get_started: SETUP_ANNOTATIONS,
+  // Wallet-signed publishing — registers an external upstream (open world).
+  apiosk_list_my_apis: READ_ONLY_ANNOTATIONS,
+  apiosk_publish_api: PUBLISH_ANNOTATIONS,
+  apiosk_update_api: PUBLISH_UPDATE_ANNOTATIONS,
+  apiosk_delete_api: PUBLISH_DELETE_ANNOTATIONS,
+};
+
+// Applied at the single list-emission boundary (runtime.listTools): fills in a
+// default output schema and behaviour annotations for any tool that doesn't
+// already declare its own, so clients stop flagging "output schema recommended"
+// and render accurate read-only/destructive/open-world badges.
+function normalizeToolForClient(tool, { hosted = false, protectedTool = false } = {}) {
+  if (!tool || typeof tool !== "object") return tool;
+  let next = tool;
+  if (!next.outputSchema) {
+    next = { ...next, outputSchema: DEFAULT_TOOL_OUTPUT_SCHEMA };
+  }
+  if (!next.annotations && TOOL_ANNOTATIONS[next.name]) {
+    next = { ...next, annotations: TOOL_ANNOTATIONS[next.name] };
+  }
+  if (hosted && !next.securitySchemes) {
+    const securitySchemes = protectedTool
+      ? [{ type: "oauth2", scopes: [HOSTED_OAUTH_SCOPE] }]
+      : [{ type: "noauth" }];
+    next = {
+      ...next,
+      securitySchemes,
+      _meta: {
+        ...(next._meta || {}),
+        // Back-compat mirror required by older ChatGPT connector clients.
+        securitySchemes,
+      },
+    };
+  }
+  return next;
+}
 
 const DASHBOARD_WALLET_TOOLS = [
   {
@@ -502,7 +622,7 @@ const PUBLISH_TOOLS = [
 
 const HELP_TOOL = {
   name: "apiosk_help",
-  description: "Explain what Apiosk MCP is, how to connect it, how auth and x402 payments work, the settlement rails (USDC and credits), and the recommended workflow for discovery, wallets, and publishing.",
+  description: "Explain what Apiosk MCP is, how to connect it, how auth and USDC/x402 payments work, and the recommended workflow for discovery, wallets, and publishing.",
   annotations: {
     readOnlyHint: true,
     openWorldHint: false,
@@ -513,8 +633,8 @@ const HELP_TOOL = {
     properties: {
       topic: {
         type: "string",
-        enum: ["overview", "setup", "auth", "workflow", "payments", "rails", "wallets", "publish", "configure"],
-        description: "Optional help topic. Defaults to overview. Use 'rails' to learn how settlement works across USDC and credits.",
+        enum: ["overview", "setup", "auth", "workflow", "discovery", "payments", "rails", "wallets", "publish", "configure"],
+        description: "Optional help topic. Defaults to overview. Use 'discovery' to learn which live sources apiosk_discover searches (Apiosk catalog + Coinbase Bazaar + well-known); use 'rails' for how USDC/x402 settlement works.",
       },
     },
   },
@@ -559,7 +679,7 @@ const EXPLORE_TOOL = {
 
 const SEARCH_TOOL = {
   name: "apiosk_search",
-  description: "Search and browse the Apiosk catalog. Use this first when you need to find APIs by capability, price, or category.",
+  description: "Search and browse the Apiosk catalog by capability, price, or category. For browsing/filtering the catalog. When the goal is to fulfil a user request with real paid data ('get me the live X'), prefer apiosk_discover, which decomposes the need and ranks the best endpoints across sources.",
   annotations: {
     readOnlyHint: true,
     openWorldHint: false,
@@ -639,6 +759,12 @@ const EXECUTE_TOOL = {
     openWorldHint: true,
     destructiveHint: true,
   },
+  _meta: {
+    "openai/outputTemplate": "ui://apiosk/result-canvas.html",
+    "openai/toolInvocation/invoking": "Fetching and paying for data…",
+    "openai/toolInvocation/invoked": "Paid data received",
+    ui: { resourceUri: "ui://apiosk/result-canvas.html" },
+  },
   inputSchema: {
     type: "object",
     required: ["slug"],
@@ -688,7 +814,7 @@ const HEALTH_TOOL = {
 const PAYMENT_GUIDE_TOOL = {
   name: "apiosk_payment_guide",
   description:
-    "Explain how to pay through the Apiosk gateway. Returns a buyer guide (how an agent settles a paid API call over USDC/x402 or credits, tailored to the current auth) and a provider guide (how to publish an API and get paid). Pass slug to scope buyer guidance to one listing, or role to pick a side.",
+    "Explain how to pay through the Apiosk gateway. Returns a buyer guide (how an agent settles a paid API call over USDC/x402, tailored to the current auth) and a provider guide (how to publish an API and get paid). Pass slug to scope buyer guidance to one listing, or role to pick a side.",
   annotations: {
     readOnlyHint: true,
     openWorldHint: false,
@@ -715,15 +841,21 @@ const DISCOVERY_TOOLS = [
   PAYMENT_GUIDE_TOOL,
   EXPLORE_TOOL,
   SEARCH_TOOL,
+  DISCOVER_TOOL,
+  INSPECT_TOOL,
   GET_API_TOOL,
   EXECUTE_TOOL,
 ];
 // Discovery + payment guidance available to every remote buyer, even before
-// they authorize (these tools are public / read-only).
+// they authorize (these tools are public / read-only). apiosk_discover and
+// apiosk_inspect_x402 are read-only too — they find candidate x402 endpoints and
+// read their 402 terms without spending, so buyers can plan a purchase pre-auth.
 const HOSTED_DISCOVERY_TOOLS = [
   HELP_TOOL,
   PAYMENT_GUIDE_TOOL,
   SEARCH_TOOL,
+  DISCOVER_TOOL,
+  INSPECT_TOOL,
   EXPLORE_TOOL,
   GET_API_TOOL,
   METADATA_TOOL,
@@ -734,18 +866,61 @@ const HOSTED_DISCOVERY_TOOLS = [
 // Managed buyer tools that work over request-scoped dashboard auth on the
 // hosted endpoint: prepaid credits + full managed agent-wallet CRUD. These are
 // protected (the OAuth layer requires authorization before they run).
-// apiosk_show_wallet_funding is intentionally excluded — it resolves a local /
+// apiosk_show_wallet_funding is intentionally excluded, it resolves a local /
 // env wallet, which does not exist on the hosted surface.
 const HOSTED_MANAGED_TOOLS = [
-  ...REMOTE_CREDITS_TOOLS,
   ...DASHBOARD_WALLET_TOOLS.filter((tool) => tool.name !== "apiosk_show_wallet_funding"),
 ];
 
 // The hosted/remote surface is fully capable: discovery, payment guidance,
 // generic + dynamic per-API execution, credits, and managed-wallet management.
-// Publishing stays local/portal-only because it requires a client-side signing
-// key the hosted server never holds.
-const HOSTED_REMOTE_TOOLS = [...HOSTED_DISCOVERY_TOOLS, ...HOSTED_MANAGED_TOOLS];
+// Wallet-signed publishing (apiosk_publish_api & co.) stays local/portal-only
+// because it requires a client-side signing key the hosted server never
+// holds; the x402 publisher tools work hosted because they authenticate with
+// a provider token (sk_live_…) instead of a wallet.
+// External-payment buyer tool: pay an x402 endpoint the gateway does NOT host,
+// from the connected managed wallet, via the gateway payer proxy. Protected
+// (spends USDC) and available in every mode that can present a connect token.
+const EXTERNAL_PAY_TOOLS = [FETCH_PAID_TOOL];
+
+const HOSTED_REMOTE_TOOLS = [
+  ...HOSTED_DISCOVERY_TOOLS,
+  ...HOSTED_MANAGED_TOOLS,
+  ...EXTERNAL_PAY_TOOLS,
+  ...PUBLISHER_TOOLS,
+];
+
+// Lean BUYER surface for the hosted connector. A buyer opening the connector in
+// ChatGPT/Claude should see the agentic flow + one wallet view — not 28 tools.
+// Ordered flow-first. The advanced wallet CRUD (create/update/delete wallet +
+// api-keys), explore/metadata/health, and provider publishing are dropped from
+// the default list. Nothing is lost: every hidden tool is still dispatchable by
+// name (callTool + isToolProtected are unchanged) and the full set is one env
+// flag away (APIOSK_MCP_FULL_TOOLS=true). apiosk_list_wallets stays so buyers can
+// see their wallet address, spend limits, and funding.
+const HOSTED_BUYER_TOOLS = [
+  HELP_TOOL,
+  DISCOVER_TOOL,
+  EXPLORE_TOOL,
+  INSPECT_TOOL,
+  EXECUTE_TOOL,
+  FETCH_PAID_TOOL,
+  GET_API_TOOL,
+  SEARCH_TOOL,
+  PAYMENT_GUIDE_TOOL,
+  DASHBOARD_WALLET_TOOLS.find((tool) => tool.name === "apiosk_list_wallets"),
+].filter(Boolean);
+
+// PROVIDER surface (caller authenticated with a sk_live_ provider key): a focused
+// publishing toolkit. The managed-wallet CRUD needs a dashboard JWT a provider
+// key does not carry, so those tools would fail anyway — they're excluded here.
+const HOSTED_PROVIDER_TOOLS = [
+  HELP_TOOL,
+  PAYMENT_GUIDE_TOOL,
+  SEARCH_TOOL,
+  GET_API_TOOL,
+  ...PUBLISHER_TOOLS,
+];
 
 const ALL_STATIC_TOOLS = [
   ...DISCOVERY_TOOLS,
@@ -754,15 +929,28 @@ const ALL_STATIC_TOOLS = [
   ...LOCAL_WALLET_TOOLS,
   ...DASHBOARD_WALLET_TOOLS,
   ...PUBLISH_TOOLS,
+  ...PUBLISHER_TOOLS,
 ];
 
+// These tools read or mutate client-machine state (local files, local signing
+// keys, or a local dashboard session). They must never execute in the hosted
+// multi-tenant server, even if a stale MCP client cached an older tool list or
+// the deployment accidentally carries APIOSK_ENABLE_LOCAL_WALLETS=true.
+const LOCAL_ONLY_TOOL_NAMES = new Set([
+  ...LOCAL_ACCOUNT_AND_CREDITS_TOOLS.map((tool) => tool.name),
+  ...LOCAL_WALLET_TOOLS.map((tool) => tool.name),
+  ...PUBLISH_TOOLS.map((tool) => tool.name),
+]);
+
 const PUBLIC_STATIC_TOOL_NAMES = new Set(
   DISCOVERY_TOOLS.map((tool) => tool.name).filter((name) => name !== "apiosk_execute")
 );
 const REMOTE_PROTECTED_STATIC_TOOL_NAMES = new Set([
   "apiosk_execute",
+  ...EXTERNAL_PAY_TOOLS.map((tool) => tool.name),
   ...REMOTE_CREDITS_TOOLS.map((tool) => tool.name),
   ...DASHBOARD_WALLET_TOOLS.map((tool) => tool.name),
+  ...PUBLISHER_TOOLS.map((tool) => tool.name),
 ]);
 
 function trimString(value) {
@@ -786,7 +974,7 @@ function sanitizeToolName(name, fallback) {
  * active but unverified -> pending review, active + verified -> live.
  *
  * NOTE: the public catalog (GET /v1/apis) hard-filters to active AND verified
- * rows, so entries built from it are always "live" — the field documents that
+ * rows, so entries built from it are always "live", the field documents that
  * invariant for catalog readers. The pending/disabled branches are reached when
  * this runs over a richer object (e.g. a get_api_detail response, which returns
  * the real active/verified flags).
@@ -821,6 +1009,18 @@ function buildCatalogEntry(api, toolName) {
   };
 }
 
+function normalizeCatalogToken(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function isWeatherLikeSlug(slug) {
+  return /weather|meteo|forecast/.test(normalizeCatalogToken(slug));
+}
+
 function buildDynamicTools(catalog, reservedTools) {
   const tools = [];
   const toolIndex = new Map();
@@ -872,7 +1072,16 @@ function buildDynamicTools(catalog, reservedTools) {
         type: "object",
         additionalProperties: true,
       },
-      annotations: api.listing_metadata?.mcp_tool?.annotations,
+      outputSchema:
+        api.listing_metadata?.mcp_tool?.outputSchema || DEFAULT_TOOL_OUTPUT_SCHEMA,
+      annotations:
+        api.listing_metadata?.mcp_tool?.annotations || DYNAMIC_EXECUTE_ANNOTATIONS,
+      _meta: {
+        "openai/outputTemplate": "ui://apiosk/result-canvas.html",
+        "openai/toolInvocation/invoking": `Fetching ${api.name || api.slug}…`,
+        "openai/toolInvocation/invoked": `${api.name || api.slug} received`,
+        ui: { resourceUri: "ui://apiosk/result-canvas.html" },
+      },
     });
 
     toolIndex.set(toolName, {
@@ -1202,6 +1411,35 @@ function buildHelpPayload(topic = "overview", options = {}) {
           : "Use APIOSK_PRIVATE_KEY if you need autonomous payment on the public server mode",
       ],
     },
+    discovery: {
+      topic: "discovery",
+      summary:
+        "apiosk_discover searches the whole x402 ecosystem in ONE call and returns ranked endpoints. This is the full list of sources it can explore. Call it whenever the user wants real/live/paid data.",
+      searched_by_default: [
+        "apiosk — the Apiosk catalog: first-party listings PLUS federated externals (imported from providers' /.well-known/x402, the APILayer & ApyHub ecosystems, direct provider integrations, and selected MCP skills). Paid via apiosk_execute.",
+        "bazaar — the Coinbase x402 Bazaar (~25k resources), searched LIVE every call. The central shared index most marketplaces + MCPs publish into. Paid via apiosk_fetch_paid.",
+      ],
+      opt_in_pass_sources_or_all: [
+        "x402-list — x402-list.com public directory (free REST).",
+        "x402-direct — x402.direct search engine with trust scores (free REST).",
+        "agentic-market — Coinbase Agentic.Market directory (free REST).",
+        "thirdweb — public thirdweb Payments x402 resource index (free REST).",
+        "payai — public PayAI facilitator discovery mirror (free REST).",
+        "x402engine — direct manifest with paid AI/media/code/web endpoints.",
+        "anchor-x402 — direct manifest with paid primitives and LLM endpoints.",
+        "x402scan — paid full-text resource search; returned as an inspect/fetch-paid pointer, never auto-paid.",
+        "apify — paid x402 prepaid-token endpoint plus the public Actor catalog; never auto-paid.",
+        "wellknown — probe a specific host's /.well-known/x402 (needs probe_hosts).",
+        "Use sources:['all'] to fan out to all directly wired free REST sources at once. Paid sources remain explicit opt-ins.",
+      ],
+      indexed_or_reference_only: [
+        "x402list.fun (paid MCP), awesome-x402 (markdown), and facilitators Nevermined / @swader / x402.rs — reference, not directly searchable.",
+      ],
+      important_note:
+        "These are DISCOVERY sources (where the agent LOOKS for endpoints) — NOT the same as a catalog listing's `source` field (where one existing entry was imported from). The Bazaar is queried by default, so external endpoints surface without passing sources; pass sources:['all'] to also sweep the other public directories.",
+      how_to:
+        "apiosk_discover({ query, segments, sources }) → one ranked list; each result tagged with `source`, `trust_tier`, and `executable_via`.",
+    },
     payments: {
       topic: "payments",
       summary: "Paid Apiosk APIs can return x402 payment requirements if the client is not configured to settle automatically.",
@@ -1238,10 +1476,10 @@ function buildHelpPayload(topic = "overview", options = {}) {
         "The connect string identifies the buyer's managed wallet and connect token; APIO_WALLET_* limits bound the USDC rail. See help topic 'setup' for the connect string format.",
       provider_settlement: {
         what_it_is:
-          "The settlement_rails above are how BUYERS pay. This is the PROVIDER (seller) side: how an API owner receives their earnings. Agents do not interact with it — it is provider-account configuration in the provider portal.",
+          "The settlement_rails above are how BUYERS pay. This is the PROVIDER (seller) side: how an API owner receives their earnings. Agents do not interact with it, it is provider-account configuration in the provider portal.",
         how_it_works: [
           "USDC earnings settle to the API's payout wallet (apis.wallet_address), which the portal links to a verified, Monerium-linked payout_wallets row.",
-          "Crypto -> EUR off-ramp mandate (optional): the provider signs an EIP-191 authorization and an on-chain mandate (ApioskOfframpExecutor on Base). Apiosk's offramp keeper then auto-converts their accumulated USDC to EURe via Monerium and redeems it to their IBAN over SEPA once the balance crosses their bundle threshold. Non-custodial — the keeper can never redirect funds or exceed the provider's on-chain per-run cap or cooldown.",
+          "Crypto -> EUR off-ramp mandate (optional): the provider signs an EIP-191 authorization and an on-chain mandate (ApioskOfframpExecutor on Base). Apiosk's offramp keeper then auto-converts their accumulated USDC to EURe via Monerium and redeems it to their IBAN over SEPA once the balance crosses their bundle threshold. Non-custodial, the keeper can never redirect funds or exceed the provider's on-chain per-run cap or cooldown.",
         ],
       },
     },
@@ -1278,7 +1516,7 @@ function buildHelpPayload(topic = "overview", options = {}) {
         "slug must use lowercase letters, numbers, and hyphens",
       ],
       identity_note:
-        "These tools manage listings via WALLET SIGNATURE — the community/MCP publish channel, owned by a synthetic platform account. That is a different identity from the provider portal, where providers manage APIs under a Supabase-auth account (owner_id) after Monerium KYB, and where listings auto-verify on create. A listing published here and one created in the portal are managed through different identities and do not currently round-trip between the two surfaces.",
+        "These tools manage listings via WALLET SIGNATURE, the community/MCP publish channel, owned by a synthetic platform account. That is a different identity from the provider portal, where providers manage APIs under a Supabase-auth account (owner_id) after Monerium KYB, and where listings auto-verify on create. A listing published here and one created in the portal are managed through different identities and do not currently round-trip between the two surfaces.",
     },
     configure: {
       topic: "configure",
@@ -1367,8 +1605,10 @@ export function createApioskMcpRuntime(options = {}) {
   const providedDashboardManager = options.walletManager || null;
   const hostedAuthEnabled = options.hostedAuthEnabled === true;
   const localWalletStore =
-    options.localWalletStore ||
-    (options.enableLocalWallets === false ? null : createLocalWalletStore(env));
+    hostedAuthEnabled
+      ? null
+      : options.localWalletStore ||
+        (options.enableLocalWallets === false ? null : createLocalWalletStore(env));
   const cache = {
     catalog: null,
     expiresAt: 0,
@@ -1378,6 +1618,7 @@ export function createApioskMcpRuntime(options = {}) {
   };
 
   async function getActiveExecutionWallet() {
+    if (hostedAuthEnabled) return null;
     try {
       const envWallet = resolveEnvPrivateWallet(env);
       if (envWallet) return envWallet;
@@ -1390,6 +1631,7 @@ export function createApioskMcpRuntime(options = {}) {
   }
 
   async function getSavedConfig() {
+    if (hostedAuthEnabled) return null;
     return readLocalApioskConfig(env);
   }
 
@@ -1551,7 +1793,16 @@ export function createApioskMcpRuntime(options = {}) {
 
   function getStaticTools(authInfo = null) {
     if (hostedAuthEnabled) {
-      return [...HOSTED_REMOTE_TOOLS];
+      // Escape hatch: expose the full 28-tool surface when explicitly opted in.
+      if (env.APIOSK_MCP_FULL_TOOLS === "true") {
+        return [...HOSTED_REMOTE_TOOLS];
+      }
+      // Providers authenticate with a sk_live_ key → focused publishing surface.
+      if (trimString(authInfo?.extra?.apiosk_provider_key)) {
+        return [...HOSTED_PROVIDER_TOOLS];
+      }
+      // Buyers (OAuth / connect token / pre-auth) → the lean agentic surface.
+      return [...HOSTED_BUYER_TOOLS];
     }
 
     const tools = [...DISCOVERY_TOOLS];
@@ -1562,6 +1813,14 @@ export function createApioskMcpRuntime(options = {}) {
       tools.push(...DASHBOARD_WALLET_TOOLS);
     }
 
+    // Provider-token x402 publishing works in every mode: hosted callers pass
+    // Authorization: Bearer sk_live_…, stdio callers set APIOSK_PROVIDER_TOKEN.
+    tools.push(...PUBLISHER_TOOLS);
+
+    // External x402 pay works with any connect token (env APIOSK_CONNECT_TOKEN in
+    // stdio, or a request-scoped token on the hosted surface).
+    tools.push(...EXTERNAL_PAY_TOOLS);
+
     return tools;
   }
 
@@ -1580,6 +1839,51 @@ export function createApioskMcpRuntime(options = {}) {
     return cache.catalog;
   }
 
+  async function resolveExecutableApiSlug(slug, authInfo = null) {
+    const requested = normalizeCatalogToken(slug);
+    if (!requested) return slug;
+
+    const catalog = await getCatalog(false, authInfo);
+    const exact = catalog.find((api) => normalizeCatalogToken(api.slug) === requested);
+    if (exact) return exact.slug;
+
+    const aliases = new Map([
+      ["weather", "open-meteo"],
+      ["weather-api", "open-meteo"],
+      ["hugen-weather", "open-meteo"],
+      ["open-meteo-weather", "open-meteo"],
+    ]);
+    const alias = aliases.get(requested);
+    if (alias && catalog.some((api) => normalizeCatalogToken(api.slug) === alias)) {
+      return alias;
+    }
+
+    if (isWeatherLikeSlug(requested)) {
+      const weather = catalog.find((api) => {
+        const haystack = [
+          api.slug,
+          api.name,
+          api.description,
+          api.category,
+          api.raw_category,
+          ...(Array.isArray(api.listing_metadata?.tags) ? api.listing_metadata.tags : []),
+        ]
+          .map(normalizeCatalogToken)
+          .join(" ");
+
+        return (
+          api.active !== false &&
+          api.verified !== false &&
+          /weather|meteo|forecast/.test(haystack)
+        );
+      });
+
+      if (weather?.slug) return weather.slug;
+    }
+
+    return slug;
+  }
+
   async function getTools(force = false, authInfo = null) {
     if (!force && cache.dynamicTools && Date.now() < cache.expiresAt) {
       return [...getStaticTools(authInfo), ...cache.dynamicTools];
@@ -1993,12 +2297,20 @@ export function createApioskMcpRuntime(options = {}) {
     });
 
     const catalog = response.apis || [];
+    const sourceMatches = searchKnownSources(argumentsObject.search, {
+      limit: argumentsObject.limit || DEFAULT_LIMIT,
+    });
     await getTools(false, authInfo);
     const capability = await resolvePaymentCapability(authInfo);
 
     return content({
       apis: catalog.map((api) => buildCatalogEntry(api, cache.toolNamesBySlug.get(api.slug) || null)),
+      sources: sourceMatches,
       meta: response.meta,
+      source_meta: {
+        total: sourceMatches.length,
+        note: "These are direct x402 discovery sources, not Apiosk catalog API listings. Their public and paid endpoints are included inline.",
+      },
       payment: buildDiscoveryPaymentHint({
         capability,
         mode: capability.mode,
@@ -2007,7 +2319,9 @@ export function createApioskMcpRuntime(options = {}) {
       for_providers:
         "Listing your own API? Call apiosk_payment_guide with role='provider' (or apiosk_publish_api) to publish it for other agents.",
       next_steps:
-        "Call apiosk_get_api for full metadata plus a per-listing payment block, use the API-specific tool directly when tool_name is present, or call apiosk_payment_guide to learn exactly how to settle a paid call.",
+        sourceMatches.length > 0
+          ? "For a matched source, pass its discover_source to apiosk_discover. For endpoints marked payment_required=true, call apiosk_inspect_x402 first and only then apiosk_fetch_paid after the user confirms the live price. Catalog APIs still use apiosk_get_api/apiosk_execute."
+          : "Call apiosk_get_api for full metadata plus a per-listing payment block, use the API-specific tool directly when tool_name is present, or call apiosk_payment_guide to learn exactly how to settle a paid call.",
     });
   }
 
@@ -2079,13 +2393,53 @@ export function createApioskMcpRuntime(options = {}) {
     });
   }
 
+  // Agentic discovery: aggregate + rank candidate x402 endpoints across sources
+  // (Phase 1: the Apiosk catalog, which already includes federated externals).
+  // Reuses the request-scoped client so catalog reads honour the same gateway
+  // base URL and connect-token threading as every other tool.
+  async function handleDiscover(argumentsObject = {}, authInfo = null) {
+    const client = await getClient(authInfo);
+    const savedConfig = await getSavedConfig().catch(() => null);
+    return runDiscover(argumentsObject, {
+      listApis: (params) => client.listApis(params),
+      gatewayBaseUrl: resolveGatewayBaseUrl(env, savedConfig),
+    });
+  }
+
+  // Read an arbitrary URL's x402 402 terms without paying. Read-only probe; no
+  // wallet/connect token is used, so it needs no auth.
+  async function handleInspect(argumentsObject = {}, authInfo = null) {
+    const savedConfig = await getSavedConfig().catch(() => null);
+    let gatewayHost = "";
+    try {
+      gatewayHost = new URL(resolveGatewayBaseUrl(env, savedConfig)).hostname;
+    } catch {
+      gatewayHost = "";
+    }
+    return runInspect(argumentsObject, { gatewayHost });
+  }
+
+  // Pay an external (non-Apiosk-hosted) x402 endpoint through the gateway payer
+  // proxy, using the same connect token the runtime threads to the gateway for
+  // catalog settlement. The gateway enforces spend caps and does the signing.
+  async function handleFetchPaid(argumentsObject = {}, authInfo = null) {
+    const savedConfig = await getSavedConfig().catch(() => null);
+    const requestConnectToken = trimString(authInfo?.extra?.apiosk_connect_token);
+    const envConnectToken = trimString(env.APIOSK_CONNECT_TOKEN || savedConfig?.connect_token);
+    return runFetchPaid(argumentsObject, {
+      connectToken: requestConnectToken || envConnectToken,
+      gatewayBaseUrl: resolveGatewayBaseUrl(env, savedConfig),
+    });
+  }
+
   async function handleExecute(argumentsObject = {}, authInfo = null) {
     if (!argumentsObject.slug) {
       return errorContent("Missing required field: slug");
     }
 
     const client = await getClient(authInfo);
-    const result = await client.execute(argumentsObject.slug, argumentsObject.input, {
+    const resolvedSlug = await resolveExecutableApiSlug(argumentsObject.slug, authInfo);
+    const result = await client.execute(resolvedSlug, argumentsObject.input, {
       operation: argumentsObject.operation,
       query: argumentsObject.query,
       pathParams: argumentsObject.path_params,
@@ -2094,7 +2448,15 @@ export function createApioskMcpRuntime(options = {}) {
       },
     });
 
-    return content(result);
+    return content(
+      resolvedSlug === argumentsObject.slug
+        ? result
+        : {
+            requested_slug: argumentsObject.slug,
+            resolved_slug: resolvedSlug,
+            result,
+          }
+    );
   }
 
   async function handleDynamicExecute(tool, argumentsObject = {}, authInfo = null) {
@@ -2286,11 +2648,37 @@ export function createApioskMcpRuntime(options = {}) {
     });
   }
 
+  // Hosted (OAuth / wallet sign-in) sessions manage wallets straight against
+  // Supabase REST with the caller's own JWT — the legacy dashboard backend
+  // these tools used to proxy to no longer exists (dashboard.apiosk.com is now
+  // the provider-portal SPA, whose catch-all answers /api/* with index.html).
+  // The requestDashboard proxy path is kept only for stdio setups that point
+  // APIOSK_CONTROL_PLANE_URL at their own control plane.
+  function hostedWalletContext(authInfo = null) {
+    const sessionToken = resolveRequestDashboardUserToken(authInfo);
+    if (!sessionToken) return null;
+    return {
+      env,
+      sessionToken,
+      userId: trimString(authInfo?.extra?.userId),
+    };
+  }
+
   async function handleWalletList(authInfo = null) {
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      return content(await hostedListWallets(hosted));
+    }
     return content(await requestDashboard("/api/agent-wallets", {}, {}, authInfo));
   }
 
   async function handleWalletCreate(argumentsObject = {}, authInfo = null) {
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      // Key derivation + encryption lived in the retired dashboard backend, so
+      // hosted sessions get an honest explanation instead of proxied HTML.
+      return errorContent(hostedCreateWalletUnavailable());
+    }
     return content(
       await requestDashboard(
         "/api/agent-wallets",
@@ -2309,6 +2697,22 @@ export function createApioskMcpRuntime(options = {}) {
       return errorContent("Missing required field: wallet_id");
     }
 
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      return content(
+        await hostedUpdateWallet({
+          ...hosted,
+          walletId: argumentsObject.wallet_id,
+          label: argumentsObject.label,
+          status: argumentsObject.status,
+          dailyLimitUsdc: argumentsObject.daily_limit_usdc,
+          perTxLimitUsdc: argumentsObject.per_tx_limit_usdc,
+          color: argumentsObject.color,
+          icon: argumentsObject.icon,
+        })
+      );
+    }
+
     const { wallet_id, ...updates } = argumentsObject;
     return content(
       await requestDashboard(
@@ -2328,6 +2732,13 @@ export function createApioskMcpRuntime(options = {}) {
       return errorContent("Missing required field: wallet_id");
     }
 
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      return content(
+        await hostedDeleteWallet({ ...hosted, walletId: argumentsObject.wallet_id })
+      );
+    }
+
     return content(
       await requestDashboard(
         `/api/agent-wallets/${argumentsObject.wallet_id}`,
@@ -2345,6 +2756,17 @@ export function createApioskMcpRuntime(options = {}) {
       return errorContent("Missing required field: wallet_id");
     }
 
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      return content(
+        await hostedWalletActivity({
+          ...hosted,
+          walletId: argumentsObject.wallet_id,
+          limit: argumentsObject.limit,
+        })
+      );
+    }
+
     const params = new URLSearchParams();
     if (argumentsObject.page !== undefined) params.set("page", String(argumentsObject.page));
     if (argumentsObject.limit !== undefined) params.set("limit", String(argumentsObject.limit));
@@ -2365,6 +2787,20 @@ export function createApioskMcpRuntime(options = {}) {
       return errorContent("Missing required field: wallet_id");
     }
 
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      const created = await hostedCreateWalletToken({
+        ...hosted,
+        walletId: argumentsObject.wallet_id,
+        name: argumentsObject.token_name,
+        revokeExisting: argumentsObject.revoke_existing === true,
+      });
+      return content({
+        ...created,
+        connect_string: `apiosk:connect:${created.connect_token}`,
+      });
+    }
+
     const { wallet_id, ...body } = argumentsObject;
     return content(
       await requestDashboard(
@@ -2384,6 +2820,13 @@ export function createApioskMcpRuntime(options = {}) {
       return errorContent("Missing required field: wallet_id");
     }
 
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      return content(
+        await hostedListWalletTokens({ ...hosted, walletId: argumentsObject.wallet_id })
+      );
+    }
+
     return content(
       await requestDashboard(
         `/api/agent-wallets/${argumentsObject.wallet_id}/api-keys`,
@@ -2399,6 +2842,19 @@ export function createApioskMcpRuntime(options = {}) {
       return errorContent("Missing required field: wallet_id");
     }
 
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      return content(
+        await hostedCreateWalletToken({
+          ...hosted,
+          walletId: argumentsObject.wallet_id,
+          name: argumentsObject.name,
+          expirationDays: argumentsObject.expiration_days,
+          revokeExisting: argumentsObject.revoke_existing === true,
+        })
+      );
+    }
+
     const { wallet_id, ...body } = argumentsObject;
     return content(
       await requestDashboard(
@@ -2421,6 +2877,20 @@ export function createApioskMcpRuntime(options = {}) {
       return errorContent("Missing required field: key_id");
     }
 
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      return content(
+        await hostedUpdateWalletToken({
+          ...hosted,
+          walletId: argumentsObject.wallet_id,
+          keyId: argumentsObject.key_id,
+          name: argumentsObject.name,
+          expirationDays: argumentsObject.expiration_days,
+          revoke: argumentsObject.revoke,
+        })
+      );
+    }
+
     const { wallet_id, key_id, ...body } = argumentsObject;
     return content(
       await requestDashboard(
@@ -2443,6 +2913,17 @@ export function createApioskMcpRuntime(options = {}) {
       return errorContent("Missing required field: key_id");
     }
 
+    const hosted = hostedWalletContext(authInfo);
+    if (hosted) {
+      return content(
+        await hostedDeleteWalletToken({
+          ...hosted,
+          walletId: argumentsObject.wallet_id,
+          keyId: argumentsObject.key_id,
+        })
+      );
+    }
+
     return content(
       await requestDashboard(
         `/api/agent-wallets/${argumentsObject.wallet_id}/api-keys/${argumentsObject.key_id}`,
@@ -2482,7 +2963,7 @@ export function createApioskMcpRuntime(options = {}) {
     }
 
     // Force include_qr_data_url so we can append an inline image content
-    // block below — clients that render images (Claude Desktop, MCP
+    // block below, clients that render images (Claude Desktop, MCP
     // Inspector) will then show the funding QR right next to the
     // newly-created wallet without a follow-up tool call.
     created.configure = await buildConfigurePayload({
@@ -2535,7 +3016,7 @@ export function createApioskMcpRuntime(options = {}) {
       `Token:   USDC (${baseUsdcContract})`,
       "",
       "WARNING: only Base mainnet USDC. Sending from Ethereum, Polygon, Solana,",
-      "or any other network will permanently lose the funds — this address is",
+      "or any other network will permanently lose the funds, this address is",
       "Base only.",
       "",
       `Block explorer: ${receive.explorer_url}`,
@@ -2550,7 +3031,7 @@ export function createApioskMcpRuntime(options = {}) {
 
     // Render the QR inline via MCP image content when the buyer's client
     // supports images (Claude Desktop, the MCP Inspector, etc.). Falls back
-    // gracefully on terminals without image support — the text block above
+    // gracefully on terminals without image support, the text block above
     // still has the address and the ANSI QR.
     const dataUrl = receive.qr_code_data_url;
     if (typeof dataUrl === "string" && dataUrl.startsWith("data:image/png;base64,")) {
@@ -3030,12 +3511,92 @@ export function createApioskMcpRuntime(options = {}) {
     });
   }
 
+  // A 402 means the buyer's configured rails could not cover the call. Tell
+  // the caller what THEIR next step is, based on how this request
+  // authenticated, instead of always giving local-stdio advice.
+  function buildPaymentRequiredHint(authInfo = null) {
+    const extra = authInfo?.extra || {};
+    const connectWallet = trimString(
+      extra.apiosk_connect_wallet_address || extra.apioskConnectWalletAddress
+    );
+
+    if (trimString(extra.apiosk_connect_token)) {
+      const walletNote = connectWallet ? ` (${connectWallet})` : "";
+      return (
+        `Your managed Apiosk wallet${walletNote} could not cover this call — it is out of USDC, ` +
+        "over its spending limit, or missing settlement approval. Send USDC on Base mainnet " +
+        "(chain 8453) to the wallet address and retry; payment then settles automatically. " +
+        "Use apiosk_list_wallets to see your wallets and funding instructions."
+      );
+    }
+
+    if (hasRequestScopedDashboardAccess(authInfo)) {
+      return (
+        "You are signed in, but no payable managed wallet is linked to this session. " +
+        "Use apiosk_list_wallets to check your wallets: if one exists, fund it with USDC on Base mainnet " +
+        "and re-authorize the Apiosk app so a fresh payment token is minted; if none exists, set one up " +
+        "in the Apiosk buyer portal first."
+      );
+    }
+
+    return hostedAuthEnabled
+      ? "Authorize Apiosk in your MCP client, then use apiosk_list_wallets to confirm that a funded managed wallet is linked before retrying."
+      : "Run apiosk_get_started in the local stdio package, or configure APIOSK_PRIVATE_KEY, to enable automatic x402 settlement.";
+  }
+
+  // Observability wrapper: time + log every tools/call dispatch to mcp_tool_calls
+  // (fire-and-forget — a logging failure never affects the tool result). See
+  // observability.mjs. Raw tokens/args are never persisted (hash + key-names only).
   async function callTool(name, argumentsObject = {}, authInfo = null) {
+    const startedAt = Date.now();
+    let outcome = "ok";
+    let errorCode = null;
+    try {
+      const result = await dispatchTool(name, argumentsObject, authInfo);
+      if (result && result.isError) outcome = "error";
+      else if (result && result.status === "payment_required") outcome = "refused";
+      return result;
+    } catch (error) {
+      outcome = "error";
+      errorCode = (error && (error.code || error.name)) || null;
+      throw error;
+    } finally {
+      try {
+        logToolCall(env, {
+          toolName: name,
+          outcome,
+          errorCode,
+          latencyMs: Date.now() - startedAt,
+          authInfo,
+          argKeys: argumentsObject && typeof argumentsObject === "object" ? Object.keys(argumentsObject) : [],
+        });
+      } catch {
+        /* observability must never break a tool call */
+      }
+    }
+  }
+
+  async function dispatchTool(name, argumentsObject = {}, authInfo = null) {
     try {
+      if (hostedAuthEnabled && LOCAL_ONLY_TOOL_NAMES.has(name)) {
+        return content({
+          status: "unsupported",
+          error_code: "tool.local_only",
+          message: `${name} is only available in the local stdio package and cannot run on the hosted Apiosk MCP server.`,
+          next_steps: [
+            "Use apiosk_search, apiosk_explore, or apiosk_discover anonymously.",
+            "For paid or account-specific actions, authorize Apiosk in the MCP client and use apiosk_list_wallets or apiosk_execute.",
+          ],
+        });
+      }
+
       if (name === "apiosk_help") return await handleHelp(argumentsObject);
       if (name === "apiosk_payment_guide") return await handlePaymentGuide(argumentsObject, authInfo);
       if (name === "apiosk_explore") return await handleExplore(argumentsObject, authInfo);
       if (name === "apiosk_search") return await handleSearch(argumentsObject, authInfo);
+      if (name === "apiosk_discover") return await handleDiscover(argumentsObject, authInfo);
+      if (name === "apiosk_inspect_x402") return await handleInspect(argumentsObject, authInfo);
+      if (name === "apiosk_fetch_paid") return await handleFetchPaid(argumentsObject, authInfo);
       if (name === "apiosk_get_api" || name === "apiosk_metadata") {
         return await handleGetApi(argumentsObject, authInfo);
       }
@@ -3054,6 +3615,8 @@ export function createApioskMcpRuntime(options = {}) {
       if (name === "apiosk_wallet_reveal_secret") return await handleLocalWalletReveal(argumentsObject);
       if (name === "apiosk_wallet_save_secret") return await handleLocalWalletSave(argumentsObject);
 
+      if (isPublisherTool(name)) return await handlePublisherTool(name, argumentsObject, authInfo, { env });
+
       if (name === "apiosk_publish_api") return await handlePublishApi(argumentsObject);
       if (name === "apiosk_list_my_apis") return await handleListMyApis(argumentsObject);
       if (name === "apiosk_update_api") return await handleUpdateApi(argumentsObject);
@@ -3080,10 +3643,14 @@ export function createApioskMcpRuntime(options = {}) {
       return await handleDynamicExecute(tool, argumentsObject, authInfo);
     } catch (error) {
       if (error instanceof ApioskPaymentRequiredError) {
-        return errorContent({
-          error: error.message,
-          hint:
-            "Run apiosk_get_started in the local stdio package, or configure APIOSK_PRIVATE_KEY, to enable automatic x402 settlement.",
+        // A valid 402 is a business state, not an MCP protocol failure. Returning
+        // isError made ChatGPT/Claude collapse it into JSON-RPC -32603 and hid
+        // the actionable funding guidance from the model.
+        return content({
+          status: "payment_required",
+          error_code: "payment.wallet_unfunded_or_unavailable",
+          message: error.message,
+          hint: buildPaymentRequiredHint(authInfo),
           payment_required: error.paymentRequired,
         });
       }
@@ -3095,7 +3662,19 @@ export function createApioskMcpRuntime(options = {}) {
   }
 
   return {
-    listTools: (authInfo = null) => getTools(false, authInfo),
+    listTools: async (authInfo = null) => {
+      const tools = await getTools(false, authInfo);
+      return Promise.all(
+        tools.map(async (tool) =>
+          normalizeToolForClient(tool, {
+            hosted: hostedAuthEnabled,
+            protectedTool: hostedAuthEnabled
+              ? await isToolProtected(tool.name, authInfo)
+              : false,
+          })
+        )
+      );
+    },
     isToolProtected,
     callTool,
   };