@apiosk/mcp 1.7.0 → 2.0.0

package/server.json

@@ -2,24 +2,40 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.obcraft/apiosk-mcp",
   "title": "Apiosk Connect",
-  "description": "Discover, pay for, execute, and publish APIs through Apiosk.",
-  "version": "1.7.0",
+  "description": "Ask a data question, review one plan and total price ceiling, approve in the chat card within your connected account's spending limits, and receive source-backed results. Resume without buying the same work twice.",
+  "version": "2.0.0",
   "websiteUrl": "https://apiosk.com",
   "icons": [
     {
-      "src": "https://mcp.apiosk.com/logo-optimized-light.png",
+      "src": "https://mcp.apiosk.com/brand/apiosk-a-20260921.png",
       "mimeType": "image/png",
-      "sizes": ["2048x2048"]
+      "sizes": [
+        "1254x1254"
+      ],
+      "theme": "light"
     },
     {
-      "src": "https://apiosk.com/logo.svg",
+      "src": "https://mcp.apiosk.com/brand/mark-20260918.svg",
       "mimeType": "image/svg+xml",
-      "sizes": ["any"]
+      "sizes": [
+        "any"
+      ]
+    },
+    {
+      "src": "https://mcp.apiosk.com/brand/mark-light-20260918.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "512x512"
+      ],
+      "theme": "light"
     },
     {
-      "src": "https://apiosk.com/apple-touch-icon.png",
+      "src": "https://mcp.apiosk.com/brand/mark-dark-20260918.png",
       "mimeType": "image/png",
-      "sizes": ["180x180"]
+      "sizes": [
+        "512x512"
+      ],
+      "theme": "dark"
     }
   ],
   "repository": {
@@ -30,23 +46,23 @@
     {
       "registryType": "npm",
       "identifier": "@apiosk/mcp",
-      "version": "1.7.0",
+      "version": "2.0.0",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
-          "name": "APIOSK_PRIVATE_KEY",
-          "description": "Optional wallet private key for automatic x402 payments.",
-          "isRequired": false,
+          "name": "APIOSK_CONNECT_TOKEN",
+          "description": "Apiosk agent token for stdio (apk_access_… from a connection, or a legacy apk_live_… agent key). Hosted MCP uses OAuth instead. Every tool acts for a connected account.",
+          "isRequired": true,
           "isSecret": true,
           "format": "string"
         },
         {
-          "name": "APIOSK_CONNECT_TOKEN",
-          "description": "Optional dashboard-managed access token.",
+          "name": "APIOSK_GATEWAY_V2_URL",
+          "description": "Gateway v2 origin. Defaults to https://gateway.apiosk.com; set only for a local or staging gateway.",
           "isRequired": false,
-          "isSecret": true,
+          "isSecret": false,
           "format": "string"
         }
       ]
@@ -54,23 +70,23 @@
     {
       "registryType": "pypi",
       "identifier": "apiosk-mcp",
-      "version": "1.7.0",
+      "version": "2.0.0",
       "transport": {
         "type": "stdio"
       },
       "environmentVariables": [
         {
-          "name": "APIOSK_PRIVATE_KEY",
-          "description": "Optional wallet private key for automatic x402 payments.",
-          "isRequired": false,
+          "name": "APIOSK_CONNECT_TOKEN",
+          "description": "Apiosk agent token for stdio (apk_access_… from a connection, or a legacy apk_live_… agent key). Hosted MCP uses OAuth instead. Every tool acts for a connected account.",
+          "isRequired": true,
           "isSecret": true,
           "format": "string"
         },
         {
-          "name": "APIOSK_CONNECT_TOKEN",
-          "description": "Optional dashboard-managed access token.",
+          "name": "APIOSK_GATEWAY_V2_URL",
+          "description": "Gateway v2 origin. Defaults to https://gateway.apiosk.com; set only for a local or staging gateway.",
           "isRequired": false,
-          "isSecret": true,
+          "isSecret": false,
           "format": "string"
         }
       ]
@@ -84,8 +100,26 @@
   ],
   "_meta": {
     "com.apiosk": {
-      "tags": ["payments", "finance", "x402", "commerce", "crypto"],
-      "categories": ["payments", "finance"]
+      "tags": [
+        "payments",
+        "finance",
+        "x402",
+        "commerce",
+        "crypto"
+      ],
+      "categories": [
+        "payments",
+        "finance"
+      ],
+      "tools": [
+        "apiosk_sources",
+        "apiosk_discover",
+        "apiosk_search",
+        "apiosk_prepare",
+        "apiosk_execute",
+        "apiosk_status",
+        "apiosk_approve"
+      ]
     }
   }
 }

package/server.mjs

@@ -1,15 +1,16 @@
+import { registerBrandRoutes, BRAND_LINKS } from "./src/brand-routes.mjs";
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import { fileURLToPath } from "node:url";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import {
-  SERVER_INFO,
+  resolveServerPresentation,
   createApioskMcpServer,
   listApioskTools,
 } from "./src/create-server.mjs";
+import { V2_RESOURCE } from "./src/gateway-v2.mjs";
 import {
   createHostedOAuthSupport,
-  createMcpWalletAuthNonce,
   resolveHostedMcpUrls,
 } from "./src/oauth.mjs";
 import { createApioskMcpRuntime } from "./src/runtime.mjs";
@@ -18,15 +19,14 @@ import {
   resolveOpenAiAppsChallengeToken,
   sendOpenAiAppsChallenge,
 } from "./well-known.mjs";
-import {
-  buildDiscoveryDocument,
-  getOpenApiRouteDocument,
-} from "./src/publisher.mjs";
+import { buildDiscoveryDocument } from "./src/well-known-routes.mjs";
 import {
   SETTLEMENT_DISCLOSURE_PATH,
   createSettlementDisclosurePage,
 } from "./src/settlement-disclosure.mjs";
 
+const { info: SERVER_INFO, description: SERVER_DESCRIPTION, instructions: SERVER_INSTRUCTIONS } = resolveServerPresentation();
+
 const CONTROL_PLANE_BACKEND_URL = (
   process.env.APIOSK_CONTROL_PLANE_BACKEND_URL ||
   process.env.APIOSK_DASHBOARD_URL ||
@@ -61,9 +61,9 @@ function normalizeControlPlanePath(pathname = "") {
 }
 
 function shouldProxyControlPlanePath(pathname = "") {
-  // Hosted sign-in is wallet-only now (see src/oauth.mjs); the email/password
-  // /api/auth/mcp-sign-in|sign-up routes never existed on the control plane, so
-  // they are no longer proxied.
+  // Hosted sign-in happens entirely at buy.apiosk.com now (see
+  // mcp/01-portal-handoff.md); this server neither renders a sign-in page nor
+  // proxies auth routes to the control plane.
   const normalizedPath = normalizeControlPlanePath(pathname);
   return (
     normalizedPath.startsWith("/api/credits/") ||
@@ -128,76 +128,33 @@ function renderMcpWelcomeHtml(mcpUrl) {
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <meta name="robots" content="noindex" />
 <title>Apiosk Connect</title>
+${BRAND_LINKS}
 <style>
-  :root { color-scheme: dark; }
-  * { box-sizing: border-box; }
-  body {
-    margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center;
-    background: radial-gradient(1200px 600px at 50% -10%, #1b2230, #0b0e14 60%);
-    color: #e6e9ef; font: 15px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
-    padding: 32px;
-  }
-  main { max-width: 640px; width: 100%; }
-  .badge {
-    display: inline-block; font-size: 12px; letter-spacing: .08em; text-transform: uppercase;
-    color: #8aa0c6; border: 1px solid #2a3344; border-radius: 999px; padding: 4px 12px; margin-bottom: 20px;
-  }
-  h1 { font-size: 30px; margin: 0 0 12px; letter-spacing: -.02em; }
-  p { color: #b8c0cf; margin: 0 0 16px; }
-  .lead { color: #d6dce6; font-size: 17px; }
-  ul { color: #b8c0cf; margin: 0 0 16px; padding-left: 20px; }
-  li { margin: 6px 0; }
-  code {
-    font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px;
-    background: #141a24; border: 1px solid #232c3a; border-radius: 6px; padding: 2px 7px; color: #cfe0ff;
-  }
-  .card { background: #0f141c; border: 1px solid #1f2937; border-radius: 14px; padding: 28px 30px; }
-  .endpoint {
-    display: block; margin: 4px 0 20px; padding: 12px 14px; background: #141a24;
-    border: 1px solid #232c3a; border-radius: 8px; color: #cfe0ff; word-break: break-all;
-    font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px;
-  }
-  h2 { font-size: 13px; letter-spacing: .06em; text-transform: uppercase; color: #7f8aa0; margin: 24px 0 8px; }
-  a { color: #7aa2ff; text-decoration: none; }
-  a:hover { text-decoration: underline; }
-  .links { display: flex; gap: 18px; flex-wrap: wrap; margin-top: 18px; padding-top: 18px; border-top: 1px solid #1f2937; }
-  footer { color: #6b7689; font-size: 12px; margin-top: 20px; }
+  @font-face{font-family:Inter;src:url("/brand/inter-latin-500-normal.woff2") format("woff2");font-weight:500;font-display:swap}@font-face{font-family:Inter;src:url("/brand/inter-latin-600-normal.woff2") format("woff2");font-weight:600;font-display:swap}
+  :root{color-scheme:light dark;--bg:#f8f8fb;--card:#fff;--text:#1f2028;--muted:#676371;--border:#e7e3ef;--soft:#f2f1f6;--accent:#6349db;--wash:rgb(99 73 219/.07)}
+  @media(prefers-color-scheme:dark){:root{--bg:#0d0f13;--card:#15171d;--text:#ecebf2;--muted:#a5a2b0;--border:#262a34;--soft:#1d2028;--accent:#c3a0ff;--wash:rgb(195 160 255/.12)}}
+  *{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;background:radial-gradient(760px 340px at 50% -12%,var(--wash),transparent 70%),var(--bg);color:var(--text);font:500 14px/1.5 Inter,ui-sans-serif,system-ui,sans-serif;letter-spacing:-.011em;padding:24px;-webkit-font-smoothing:antialiased}
+  main{max-width:560px;width:100%}.card{background:var(--card);border:1px solid var(--border);border-radius:18px;padding:26px;box-shadow:0 18px 45px -38px rgba(72,42,145,.45)}
+  .brand{display:block;width:92px;height:30px;margin-bottom:24px}.brand img{display:block;width:92px;height:30px;object-fit:contain;object-position:left center}
+  .badge{display:inline-block;font-size:10px;color:var(--muted);border:1px solid var(--border);border-radius:999px;padding:4px 8px;margin-bottom:12px}
+  h1{font-size:25px;font-weight:600;line-height:1.18;margin:0 0 8px;letter-spacing:-.032em}p{color:var(--muted);margin:0}.lead{font-size:14px}
+  .steps{display:grid;gap:8px;margin:20px 0}.step{display:flex;align-items:center;gap:10px;padding:10px 11px;background:var(--soft);border-radius:11px}.step b{display:grid;place-items:center;width:22px;height:22px;border-radius:7px;background:var(--wash);color:var(--accent);font-size:10px}.step span{font-size:12px}
+  h2{font-size:11px;font-weight:600;margin:18px 0 7px}.endpoint{display:block;padding:10px 11px;background:var(--soft);border:1px solid var(--border);border-radius:10px;color:var(--text);word-break:break-all;font:500 11px/1.5 Inter,ui-sans-serif,system-ui,sans-serif}
+  details{margin-top:12px;color:var(--muted);font-size:12px}details code{display:block;margin-top:8px;padding:9px 10px;background:var(--soft);border-radius:8px;word-break:break-all}.links{display:flex;gap:15px;flex-wrap:wrap;margin-top:20px;padding-top:16px;border-top:1px solid var(--border)}a{color:var(--accent);text-decoration:none}a:hover{text-decoration:underline}footer{color:var(--muted);font-size:10px;margin-top:14px}
 </style>
 </head>
 <body>
 <main>
   <div class="card">
+    <picture class="brand"><source media="(prefers-color-scheme:dark)" srcset="/brand/wordmark-white-320.png"><img src="/brand/wordmark-black-320.png" alt="Apiosk" width="320" height="103"></picture>
     <span class="badge">Model Context Protocol</span>
-    <h1>Welcome to Apiosk Connect</h1>
-    <p class="lead">
-      This is the Apiosk MCP server endpoint &mdash; it lets AI agents discover, pay for,
-      execute, and publish APIs through the Apiosk gateway. It is a machine endpoint, not a
-      website, so connect it from an MCP client (Claude, Cursor, ChatGPT, and others) rather
-      than browsing it here.
-    </p>
-
-    <h2>What you can do with it</h2>
-    <ul>
-      <li><strong>Discover</strong> APIs, datasets, and services in the Apiosk catalog.</li>
-      <li><strong>Pay</strong> per call automatically in USDC (x402 on Base).</li>
-      <li><strong>Execute</strong> any listing through a uniform contract or its API-specific tool.</li>
-      <li><strong>Publish &amp; manage</strong> your own APIs so other agents can find and pay for them.</li>
-      <li><strong>Ship paid x402 routes from a coding agent</strong> &mdash; connect with
-        <code>Authorization: Bearer sk_live_&hellip;</code> (a provider API key) and use
-        <code>publish_x402_route</code>, <code>test_x402_route</code>, and friends.</li>
-    </ul>
-
-    <h2>Endpoint</h2>
-    <code class="endpoint">${mcpUrl}</code>
+    <h1>Connect Apiosk to your chatbot</h1>
+    <p class="lead">Ask for specialist data, approve the total price in Apiosk and receive the source-backed result in the same conversation.</p>
+    <div class="steps"><div class="step"><b>1</b><span>Ask a data question</span></div><div class="step"><b>2</b><span>Review and approve the price</span></div><div class="step"><b>3</b><span>Receive the result and source JSON</span></div></div>
 
-    <h2>Connect from Claude Code</h2>
-    <code>claude mcp add --transport http apiosk ${mcpUrl}</code>
-
-    <h2>Connect from ChatGPT</h2>
+    <h2>Secure MCP endpoint</h2>
     <code class="endpoint">${mcpUrl}</code>
-
-    <h2>Legacy SSE fallback</h2>
-    <code class="endpoint">${mcpUrl.replace(/\/mcp$/, "/sse")}</code>
+    <details><summary>Manual setup</summary><code>claude mcp add --transport http apiosk ${mcpUrl}</code><code>${mcpUrl.replace(/\/mcp$/, "/sse")}</code></details>
 
     <div class="links">
       <a href="/health">Health</a>
@@ -226,8 +183,7 @@ function sendMcpWelcome(req, res) {
   res.status(200).json({
     name: "Apiosk Connect",
     server: SERVER_INFO,
-    description:
-      "Apiosk Connect lets MCP clients discover, pay for, execute, and publish APIs through the Apiosk gateway.",
+    description: SERVER_DESCRIPTION,
     transport: "streamable-http",
     endpoint: mcpUrl,
     legacy_sse_endpoint: mcpUrl.replace(/\/mcp$/, "/sse"),
@@ -241,7 +197,8 @@ function sendMcpWelcome(req, res) {
 
 // Public Fly deployment must accept the Fly hostname instead of localhost-only
 // host validation defaults.
-const app = createMcpExpressApp({ host: "0.0.0.0" });
+const bindHost = process.env.APIOSK_MCP_BIND_HOST || "0.0.0.0";
+const app = createMcpExpressApp({ host: bindHost });
 // Fly terminates TLS and adds one trusted proxy hop. Without this,
 // express-rate-limit rejects X-Forwarded-For and can surface as MCP -32603.
 app.set("trust proxy", 1);
@@ -251,10 +208,8 @@ const { issuerUrl, mcpServerUrl } = resolveHostedMcpUrls({
   port,
 });
 const runtime = createApioskMcpRuntime({
-  // Hosted MCP is multi-tenant and must never read/write machine-local wallet
-  // or config state. Buyer identity and payment capability are request-scoped
-  // through OAuth/connect tokens; local wallets belong only to stdio installs.
-  enableLocalWallets: false,
+  // Hosted MCP is multi-tenant: the buyer's identity arrives on each request
+  // through OAuth and never falls back to a machine-wide token.
   hostedAuthEnabled: true,
 });
 const hostedOAuth = createHostedOAuthSupport({
@@ -266,6 +221,24 @@ const hostedOAuth = createHostedOAuthSupport({
 });
 const mcpAuthMiddleware = hostedOAuth.createMcpAuthMiddleware(runtime);
 
+// Operational evidence without buyer prompts, credentials, OAuth codes or
+// result bodies. In particular distinguish a host timeout from an auth error.
+app.use((req, res, next) => {
+  const path = req.path;
+  if (!["/mcp", "/messages", "/token", "/authorize", "/register", "/.well-known/oauth-authorization-server", "/.well-known/oauth-protected-resource/mcp"].includes(path)) return next();
+  const started = Date.now();
+  res.once("finish", () => console.info(JSON.stringify({
+    event: "mcp_request", path, method: req.method,
+    rpc_method: ["initialize", "tools/list", "tools/call", "resources/list", "resources/read", "notifications/initialized"].includes(req.body?.method) ? req.body.method : undefined,
+    client_name: req.body?.method === "initialize" && /^[a-zA-Z0-9 ._/-]{1,80}$/.test(req.body?.params?.clientInfo?.name || "") ? req.body.params.clientInfo.name : undefined,
+    client_family: /openai|chatgpt/i.test(req.headers['user-agent'] || '') ? 'openai' : /claude|anthropic/i.test(req.headers['user-agent'] || '') ? 'anthropic' : 'other',
+    has_bearer: /^Bearer /i.test(req.headers.authorization || ''),
+    ui_resource: req.body?.method === 'resources/read' && /^ui:\/\/apiosk\/gateway-v2-card-v[0-9]+(?:-chatgpt)?\.html$/.test(req.body?.params?.uri || '') ? req.body.params.uri : undefined,
+    status: res.statusCode, duration_ms: Date.now() - started,
+  })));
+  next();
+});
+
 app.use(hostedOAuth.metadataRouter);
 app.use(new URL(hostedOAuth.oauthMetadata.authorization_endpoint).pathname, hostedOAuth.authorizationRouter);
 app.use(new URL(hostedOAuth.oauthMetadata.token_endpoint).pathname, hostedOAuth.tokenRouter);
@@ -275,15 +248,55 @@ if (hostedOAuth.oauthMetadata.registration_endpoint) {
     hostedOAuth.registrationRouter
   );
 }
+// buy.apiosk.com's return leg for the portal handoff (mcp/01-portal-handoff.md).
+app.get("/authorize/callback", (req, res) => hostedOAuth.handlePortalCallback(req, res));
 
 app.get(OPENAI_APPS_CHALLENGE_PATH_PATTERN, (req, res) => {
   return sendOpenAiAppsChallenge(res, OPENAI_APPS_CHALLENGE_TOKEN);
 });
 
+// Public favicon discovery complements MCP initialize metadata for hosts
+// that resolve connector branding from the server's origin.
+registerBrandRoutes(app);
+app.get("/", (req, res) => {
+  res.setHeader("cache-control", "public, max-age=0, must-revalidate");
+  return sendMcpWelcome(req, res);
+});
+
+// Preserve the original URL for already-installed connectors.
 app.get("/logo-optimized-light.png", (req, res) => {
+  res.setHeader("cache-control", "public, max-age=0, must-revalidate");
   res.type("png").sendFile(fileURLToPath(new URL("./logo-optimized-light.png", import.meta.url)));
 });
 
+// Only the declared, versioned brand files are exposed.
+for (const icon of SERVER_INFO.icons) {
+  const pathname = new URL(icon.src).pathname;
+  const filename = pathname.slice("/brand/".length);
+  app.get(pathname, (_req, res) => {
+    res.setHeader("cache-control", "public, max-age=31536000, immutable");
+    res.type(icon.mimeType).sendFile(fileURLToPath(new URL(`./assets/brand/${filename}`, import.meta.url)));
+  });
+}
+
+// UI resources use the same compact wordmark and self-hosted Inter weights as
+// the App. Keep this an explicit allowlist: /brand is not a general file
+// server, and adding a packaged asset does not make it public by accident.
+for (const asset of [
+  { filename: "wordmark-black-320.png", type: "image/png" },
+  { filename: "wordmark-white-320.png", type: "image/png" },
+  { filename: "inter-latin-400-normal.woff2", type: "font/woff2" },
+  { filename: "inter-latin-500-normal.woff2", type: "font/woff2" },
+  { filename: "inter-latin-600-normal.woff2", type: "font/woff2" },
+]) {
+  app.get(`/brand/${asset.filename}`, (_req, res) => {
+    res.setHeader("cache-control", "public, max-age=31536000, immutable");
+    res.type(asset.type).sendFile(
+      fileURLToPath(new URL(`./assets/brand/${asset.filename}`, import.meta.url))
+    );
+  });
+}
+
 app.get(SETTLEMENT_DISCLOSURE_PATH, (_req, res) => {
   res
     .setHeader("cache-control", "public, max-age=300")
@@ -291,55 +304,6 @@ app.get(SETTLEMENT_DISCLOSURE_PATH, (_req, res) => {
     .send(createSettlementDisclosurePage());
 });
 
-// Self-hosted browser bundles for the /authorize wallet flows. Served
-// same-origin because embedded mobile browsers can refuse cross-origin dynamic
-// module imports. Regenerate with scripts/build-wallet-lib.mjs after upgrades.
-const browserBundleFiles = new Map([
-  ["wallet-accounts.mjs", new URL("./src/assets/wallet-accounts.mjs", import.meta.url)],
-  ["walletconnect-provider.mjs", new URL("./src/assets/walletconnect-provider.mjs", import.meta.url)],
-]);
-const browserBundleCache = new Map();
-
-app.get("/assets/:bundle", async (req, res, next) => {
-  const bundleUrl = browserBundleFiles.get(req.params.bundle);
-  if (!bundleUrl) return next();
-
-  try {
-    let bundle = browserBundleCache.get(req.params.bundle);
-    if (!bundle) {
-      const { readFile } = await import("node:fs/promises");
-      bundle = await readFile(bundleUrl);
-      browserBundleCache.set(req.params.bundle, bundle);
-    }
-    res.setHeader("content-type", "text/javascript; charset=utf-8");
-    res.setHeader("cache-control", "public, max-age=3600");
-    res.send(bundle);
-  } catch (error) {
-    res.status(404).json({
-      error: "not_found",
-      message: "Wallet library bundle is not available on this deployment.",
-      status: 404,
-    });
-  }
-});
-
-app.post("/api/auth/mcp-wallet-nonce", async (req, res) => {
-  try {
-    const nonce = await createMcpWalletAuthNonce({ env: process.env });
-    res.status(200).json(nonce);
-  } catch (error) {
-    const status = Number.isFinite(error?.status) ? error.status : 502;
-    res.status(status).json({
-      error: "wallet_auth_unavailable",
-      message:
-        error instanceof Error
-          ? error.message
-          : "Wallet sign-in is temporarily unavailable.",
-      status,
-    });
-  }
-});
-
 app.all("/api/*path", async (req, res) => {
   try {
     const pathname = req.path || req.originalUrl || "";
@@ -361,29 +325,50 @@ app.all("/api/*path", async (req, res) => {
   }
 });
 
-// Hosted OpenAPI spec for a published x402 route (generate_openapi_spec
-// returns this URL). Built live from the gateway database, so it always
-// reflects the current listing. Accepts /openapi/<route_id> and
-// /openapi/<route_id>.json.
-app.get("/openapi/:routeId", async (req, res) => {
+// Static server card (SEP-1649). Lets a registry read this server's identity,
+// auth model and capabilities without opening an MCP session.
+//
+// Built from the SAME runtime that answers tools/list rather than from a
+// hand-written literal, because a card that disagrees with the live server is
+// worse than no card: a scanner would publish a tool list nobody can call.
+//
+// `authentication.required` is true: every Gateway v2 tool acts for a
+// connected Apiosk account, so hosts configure OAuth when they connect.
+app.get("/.well-known/mcp/server-card.json", async (req, res) => {
   try {
-    const document = await getOpenApiRouteDocument(req.params.routeId, {
-      env: process.env,
+    const tools = await listApioskTools({ hostedAuthEnabled: true });
+    res.setHeader("cache-control", "public, max-age=300");
+    res.json({
+      serverInfo: SERVER_INFO,
+      // Repeated at the top level, not only inside serverInfo. Registries look
+      // for these where their own schema puts them, and a scanner that finds
+      // nothing publishes a listing with a blank description and a placeholder
+      // icon — which is exactly what happened to apiosk/apiosk on first
+      // publish. Duplication is cheap; an empty storefront is not.
+      name: SERVER_INFO.name,
+      title: SERVER_INFO.title,
+      description: SERVER_DESCRIPTION,
+      version: SERVER_INFO.version,
+      websiteUrl: "https://apiosk.com",
+      icons: SERVER_INFO.icons,
+      instructions: SERVER_INSTRUCTIONS,
+      authentication: {
+        required: true,
+        schemes: ["oauth2"],
+      },
+      capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+      },
+      tools,
+      prompts: [],
+      resources: [V2_RESOURCE],
     });
-    if (!document) {
-      return res.status(404).json({
-        error: "not_found",
-        message: "No published route matches this id.",
-        status: 404,
-      });
-    }
-    res.setHeader("cache-control", "public, max-age=60");
-    res.json(document);
   } catch (error) {
-    res.status(502).json({
-      error: "bad_gateway",
+    res.status(500).json({
+      error: "server_card_unavailable",
       message: error instanceof Error ? error.message : String(error),
-      status: 502,
     });
   }
 });
@@ -422,7 +407,7 @@ app.get("/health", async (req, res) => {
 });
 
 app.post("/mcp", mcpAuthMiddleware, async (req, res) => {
-  const server = createApioskMcpServer({ runtime });
+  const server = createApioskMcpServer({ runtime, legacyUiMime: /openai|chatgpt/i.test(req.headers["user-agent"] || "") });
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: undefined,
   });
@@ -555,11 +540,11 @@ app.post("/messages", mcpAuthMiddleware, async (req, res) => {
   }
 });
 
-app.listen(port, "0.0.0.0", async () => {
-  console.log(`Apiosk MCP server listening on http://0.0.0.0:${port}`);
-  console.log(`Health check: http://0.0.0.0:${port}/health`);
-  console.log(`MCP endpoint: http://0.0.0.0:${port}/mcp`);
-  console.log(`Legacy SSE endpoint: http://0.0.0.0:${port}/sse`);
+app.listen(port, bindHost, async () => {
+  console.log(`Apiosk MCP server listening on http://${bindHost}:${port}`);
+  console.log(`Health check: http://${bindHost}:${port}/health`);
+  console.log(`MCP endpoint: http://${bindHost}:${port}/mcp`);
+  console.log(`Legacy SSE endpoint: http://${bindHost}:${port}/sse`);
   console.log(`OAuth issuer: ${issuerUrl.href}`);
   console.log(`OAuth protected-resource metadata: ${hostedOAuth.resourceMetadataUrl}`);
   try {

package/src/approval-feedback.mjs

@@ -0,0 +1,21 @@
+// Self-contained so the card can use the same account-currency formatter.
+export function approvalFeedback(data, money, fallback) {
+  const error = data?.errors?.find(error => typeof error?.message === 'string');
+  const message = data?.message || error?.message || fallback;
+  const details = error?.details;
+  if (!details || details.currency !== 'USD') return message;
+  const required = money(details.required_atomic, 'USD', true);
+  const available = money(details.available_atomic, 'USD');
+  if (required == null || available == null) return message;
+  const end = ' Nothing was purchased by this approval attempt.';
+  switch (error.code) {
+    case 'approval_per_request_limit':
+      return 'This request needs up to ' + required + ', but your connection allows ' + available + ' per request. Set higher limits below, or ask a smaller question.' + end;
+    case 'approval_daily_limit':
+      return 'This request needs up to ' + required + ', but your connection has ' + available + ' left in its daily budget. Set a higher daily limit below, try later, or ask a smaller question.' + end;
+    case 'approval_balance_insufficient':
+      return 'This request needs up to ' + required + ', but your available Apiosk balance is ' + available + '. Add funds in Apiosk > Balance, or ask a smaller question.' + end;
+    default:
+      return message;
+  }
+}

package/src/brand-routes.mjs

@@ -0,0 +1,28 @@
+import { fileURLToPath } from "node:url";
+
+export const BRAND_LINKS = `<link rel="icon" type="image/png" href="/brand/apiosk-a-20260921.png" sizes="1254x1254" media="(prefers-color-scheme: light)" />
+<link rel="icon" href="/favicon.ico?v=20260921" sizes="16x16 32x32 48x48" media="(prefers-color-scheme: light)" />
+<link rel="icon" href="/favicon-dark.ico?v=20260918" sizes="16x16 32x32 48x48" media="(prefers-color-scheme: dark)" />
+<link rel="icon" type="image/svg+xml" href="/favicon.svg?v=20260918" />
+<link rel="icon" type="image/png" sizes="512x512" href="/brand/mark-light-20260918.png" media="(prefers-color-scheme: light)" />
+<link rel="icon" type="image/png" sizes="512x512" href="/brand/mark-dark-20260918.png" media="(prefers-color-scheme: dark)" />
+<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png?v=20260918" />`;
+
+export function registerBrandRoutes(app) {
+  for (const [path, filename, type] of [
+    ["/favicon.ico", "favicon.ico", "image/x-icon"],
+    ["/favicon-dark.ico", "favicon-dark.ico", "image/x-icon"],
+    ["/favicon.svg", "mark-20260918.svg", "image/svg+xml"],
+    ["/favicon.png", "apiosk-a-20260921.png", "image/png"],
+    ["/apple-touch-icon.png", "apple-touch-icon.png", "image/png"],
+    // Cached clients can still request earlier metadata and card URLs.
+    ["/brand/mark-20260905-transparent.svg", "mark-20260918.svg", "image/svg+xml"],
+    ["/brand/mark-light-20260905-transparent.png", "mark-light-20260918.png", "image/png"],
+    ["/brand/mark-dark-20260905-transparent.png", "mark-dark-20260918.png", "image/png"],
+  ]) {
+    app.get(path, (_req, res) => {
+      res.setHeader("cache-control", "public, max-age=0, must-revalidate");
+      res.type(type).sendFile(fileURLToPath(new URL(`../assets/brand/${filename}`, import.meta.url)));
+    });
+  }
+}