@apiosk/mcp 1.3.1 → 2.0.0

package/server.json

@@ -1,26 +1,97 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.obcraft/apiosk-mcp",
-  "title": "Apiosk",
-  "description": "AI-native payments: discover, pay for, execute, and publish monetized APIs through MCP.",
-  "version": "1.3.1",
+  "title": "Apiosk Connect",
+  "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://apiosk.com/logo.svg",
+      "src": "https://mcp.apiosk.com/brand/apiosk-a-20260921.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "1254x1254"
+      ],
+      "theme": "light"
+    },
+    {
+      "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": {
     "url": "https://github.com/obcraft/apiosk-mcp",
     "source": "github"
   },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@apiosk/mcp",
+      "version": "2.0.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "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_GATEWAY_V2_URL",
+          "description": "Gateway v2 origin. Defaults to https://gateway.apiosk.com; set only for a local or staging gateway.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        }
+      ]
+    },
+    {
+      "registryType": "pypi",
+      "identifier": "apiosk-mcp",
+      "version": "2.0.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "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_GATEWAY_V2_URL",
+          "description": "Gateway v2 origin. Defaults to https://gateway.apiosk.com; set only for a local or staging gateway.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        }
+      ]
+    }
+  ],
   "remotes": [
     {
       "type": "streamable-http",
@@ -29,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,16 +1,31 @@
+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 { createHostedOAuthSupport, resolveHostedMcpUrls } from "./src/oauth.mjs";
+import { V2_RESOURCE } from "./src/gateway-v2.mjs";
+import {
+  createHostedOAuthSupport,
+  resolveHostedMcpUrls,
+} from "./src/oauth.mjs";
 import { createApioskMcpRuntime } from "./src/runtime.mjs";
+import { openSession, closeSession } from "./src/observability.mjs";
 import {
   resolveOpenAiAppsChallengeToken,
   sendOpenAiAppsChallenge,
 } from "./well-known.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 ||
@@ -46,10 +61,11 @@ function normalizeControlPlanePath(pathname = "") {
 }
 
 function shouldProxyControlPlanePath(pathname = "") {
+  // 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 === "/api/auth/mcp-sign-in" ||
-    normalizedPath === "/api/auth/mcp-sign-up" ||
     normalizedPath.startsWith("/api/credits/") ||
     normalizedPath === "/api/agent-wallets" ||
     normalizedPath.startsWith("/api/agent-wallets/")
@@ -111,75 +127,41 @@ function renderMcpWelcomeHtml(mcpUrl) {
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <meta name="robots" content="noindex" />
-<title>Apiosk MCP</title>
+<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 MCP</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>
-    </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>Secure MCP endpoint</h2>
+    <code class="endpoint">${mcpUrl}</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>
       <a href="https://dashboard.apiosk.com" target="_blank" rel="noopener">Dashboard</a>
       <a href="https://github.com/obcraft/apiosk-mcp" target="_blank" rel="noopener">Docs &amp; source</a>
     </div>
-    <footer>Apiosk MCP &middot; ${SERVER_INFO.name} v${SERVER_INFO.version}</footer>
+    <footer>Apiosk Connect &middot; ${SERVER_INFO.name} v${SERVER_INFO.version}</footer>
   </div>
 </main>
 </body>
@@ -199,12 +181,12 @@ function sendMcpWelcome(req, res) {
   }
 
   res.status(200).json({
-    name: "Apiosk MCP",
+    name: "Apiosk Connect",
     server: SERVER_INFO,
-    description:
-      "Apiosk MCP server endpoint. Connect it from an MCP client to 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"),
     connect: {
       claude_code: `claude mcp add --transport http apiosk ${mcpUrl}`,
     },
@@ -215,26 +197,48 @@ 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);
 const port = Number(process.env.PORT || 3000);
 const { issuerUrl, mcpServerUrl } = resolveHostedMcpUrls({
   env: process.env,
   port,
 });
 const runtime = createApioskMcpRuntime({
-  enableLocalWallets: process.env.APIOSK_ENABLE_LOCAL_WALLETS === "true",
+  // 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({
   env: process.env,
-  controlPlaneBaseUrl: CONTROL_PLANE_BACKEND_URL,
   issuerUrl,
   mcpServerUrl,
   appName: "Apiosk",
-  resourceName: "Apiosk MCP",
+  resourceName: "Apiosk Connect",
 });
 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);
@@ -244,11 +248,62 @@ 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")
+    .type("html")
+    .send(createSettlementDisclosurePage());
+});
+
 app.all("/api/*path", async (req, res) => {
   try {
     const pathname = req.path || req.originalUrl || "";
@@ -270,6 +325,70 @@ app.all("/api/*path", 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 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],
+    });
+  } catch (error) {
+    res.status(500).json({
+      error: "server_card_unavailable",
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+});
+
+// Machine-readable index of every paid x402 route published through Apiosk,
+// reshaped from the gateway's /.well-known/x402 document (60s cache).
+app.get(["/.well-known/apiosk-routes.json", "/discovery"], async (req, res) => {
+  try {
+    const document = await buildDiscoveryDocument({ env: process.env });
+    res.setHeader("cache-control", "public, max-age=60");
+    res.json(document);
+  } catch (error) {
+    res.status(502).json({
+      error: "bad_gateway",
+      message: error instanceof Error ? error.message : String(error),
+      status: 502,
+    });
+  }
+});
+
 app.get("/health", async (req, res) => {
   try {
     const tools = await listApioskTools({ runtime });
@@ -288,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,
   });
@@ -354,10 +473,78 @@ app.delete("/mcp", (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`);
+// Legacy HTTP+SSE transport (protocol version 2024-11-05), kept alongside
+// Streamable HTTP for older MCP clients. Current ChatGPT and Claude installs
+// should use the preferred /mcp Streamable HTTP endpoint.
+const sseTransports = new Map();
+
+app.get("/sse", async (req, res) => {
+  const server = createApioskMcpServer({ runtime });
+  const transport = new SSEServerTransport("/messages", res);
+  sseTransports.set(transport.sessionId, transport);
+
+  // Observability: record the SSE connection (the "who's connected / installs"
+  // roster) and mark it closed on disconnect. Fire-and-forget.
+  openSession(process.env, {
+    sessionId: transport.sessionId,
+    transport: "sse",
+    ip: req.ip,
+    userAgent: req.headers["user-agent"],
+  });
+
+  res.on("close", () => {
+    sseTransports.delete(transport.sessionId);
+    closeSession(process.env, transport.sessionId);
+    transport.close().catch(() => {});
+    server.close().catch(() => {});
+  });
+
+  try {
+    await server.connect(transport);
+  } catch (error) {
+    console.error("Error establishing /sse stream:", error);
+    sseTransports.delete(transport.sessionId);
+  }
+});
+
+app.post("/messages", mcpAuthMiddleware, async (req, res) => {
+  const sessionId = typeof req.query.sessionId === "string" ? req.query.sessionId : "";
+  const transport = sseTransports.get(sessionId);
+
+  if (!transport) {
+    res.status(400).json({
+      jsonrpc: "2.0",
+      id: null,
+      error: {
+        code: -32000,
+        message: "Bad Request: No SSE session found for the given sessionId.",
+      },
+    });
+    return;
+  }
+
+  try {
+    await transport.handlePostMessage(req, res, req.body);
+  } catch (error) {
+    console.error("Error handling /messages request:", error);
+    if (!res.headersSent) {
+      res.status(500).json({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32603,
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  }
+});
+
+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)));
+    });
+  }
+}