@apiosk/mcp 1.3.0

package/docs/sepa-rail.md

@@ -0,0 +1,134 @@
+# Settlement rails — USDC, SEPA incasso, credits
+
+Apiosk is **one mandate, any rail**. A single buyer connect token can settle a
+paid API call over any of three rails. The gateway picks the rail per call —
+the agent does not need to know or choose which one is used.
+
+| Rail | What it is | Best for |
+| --- | --- | --- |
+| `usdc_x402` | On-chain USDC on Base (chain `8453`), settled per call via an x402 payment proof from the agent wallet or `APIOSK_PRIVATE_KEY`. | Crypto-native agents with a funded wallet. |
+| `sepa_incasso` | EU **SEPA Direct Debit** (incasso). Paid calls are appended to a ledger and collected later in batches from the buyer's bank account. No per-call bank transaction. | EU buyers; high call volume; lowest fees. |
+| `credits` | Prepaid balance topped up once by a human (Adyen/Mollie), then spent down per call (`apiosk_buy_credits`). | Humans who want to pre-fund and let an agent spend. |
+
+### Rail fallback order
+
+1. **USDC / x402 wallet** — when the agent can produce a payment proof.
+2. **SEPA incasso ledger** — when the buyer has an active SEPA mandate. No proof
+   needed: the call is *recorded*, not blocked.
+3. **Prepaid credits** balance.
+
+A `402 Payment Required` is only returned when none of the buyer's enabled rails
+can cover the call.
+
+---
+
+## SEPA incasso (direct debit), end to end
+
+An incasso lets Apiosk pull euros from the buyer's bank account under a one-time
+mandate, so an agent can keep calling paid APIs without signing or funding each
+call.
+
+### 1. Mandate setup — once, by a human
+
+In the buyer portal the buyer authorizes a recurring SEPA mandate:
+
+- **iDEAL** (NL): a one-cent verification payment returns a reusable
+  direct-debit mandate. Recurring calls then use `method=directdebit`.
+- **PayPal** / **card**: alternative mandates for non-NL buyers (recurring calls
+  use `method=paypal` / `method=creditcard`).
+
+Agents never perform this step — they only need the connect token afterward.
+
+### 2. Collection terms — once, by the buyer
+
+The mandate authorizes bounded collection:
+
+- **Threshold:** €25–€500 (default €25, floor €25).
+- **Max age:** 7, 14, or 30 days.
+
+These bound how much, and for how long, calls can accrue before a collection is
+triggered.
+
+### 3. Per call — automatic, deferred
+
+When a paid call settles over SEPA, the gateway appends a **SEPA ledger debit**
+row carrying the full breakdown and returns success immediately:
+
+```json
+{
+  "total_eur": "0.10",
+  "apiosk_fee_rate": "0.03",
+  "apiosk_fee_pct": "3.0000",
+  "apiosk_fee_eur": "0.003",
+  "provider_net_eur": "0.097"
+}
+```
+
+No bank transaction happens yet — only a ledger entry.
+
+### 4. Batch collection — background worker
+
+A worker flushes a buyer's unbatched ledger into **one** Mollie SEPA Direct
+Debit when either condition is met:
+
+- outstanding (unbatched) sum **crosses the threshold**, OR
+- the **oldest unbatched entry passes the max age**.
+
+Many micro-calls collapse into a single bank debit. The worker opens a batch via
+the `sepa_open_settlement_batch` RPC and calls the `mollie_settle_sepa_batch`
+edge function to create the direct debit.
+
+---
+
+## Economics
+
+- **Apiosk platform fee: 2% by default** of each call's gross, recorded per ledger row.
+- **Mollie SEPA Direct Debit fee: ~€0.30 per collection (per batch)** — not per
+  call. This is why sub-€25 thresholds are not offered: batching amortizes the
+  fixed bank fee across many calls.
+- The provider receives gross minus the Apiosk platform fee; the Mollie fee is netted
+  at collection time.
+
+## Operational defaults
+
+| Setting | Default | Env / source |
+| --- | --- | --- |
+| Buyer threshold | €25 (range 25–500) | buyer portal, `sepa_collection_threshold_eur` |
+| Buyer max age | 7 / 14 / 30 days | buyer portal |
+| Batch worker cadence | 1800 s | `SEPA_BATCH_POLL_SECONDS` |
+| Batch flush amount | €25 | `MOLLIE_BATCH_FLUSH_EUR` |
+| Batch flush age | 7 days | `MOLLIE_BATCH_FLUSH_DAYS` |
+
+## Connect string and SEPA
+
+The connect string identifies the buyer's managed wallet and connect token:
+
+```bash
+export APIO_GATEWAY_URL=https://gateway.apiosk.com
+export APIO_CHAIN_ID=8453
+export APIO_AGENT_WALLET_ADDRESS=0x...
+export APIO_CONNECT_TOKEN=aw_...
+export APIO_CONNECT_AUTHORIZATION=Bearer aw_...
+export APIO_CONNECT_HEADER_NAME=X-Apiosk-Connect-Token
+# Optional USDC-rail guardrails:
+export APIO_WALLET_DAILY_LIMIT_USDC=100
+export APIO_WALLET_PER_TX_LIMIT_USDC=1
+```
+
+The `APIO_WALLET_*` limits only bound the **USDC** rail. The **SEPA mandate and
+its threshold/age terms live server-side** against the same buyer account, so the
+identical connect token transparently settles over SEPA incasso when USDC is
+unavailable — no extra connect-string fields are required. An agent holding only
+this connect token can therefore make paid calls with no on-chain balance; those
+calls land on the SEPA ledger and are collected in the next batch.
+
+## Agent guidance
+
+- Agents do **not** set up the mandate — that is a one-time human action in the
+  buyer portal.
+- SEPA-backed calls succeed immediately even with no wallet balance and no x402
+  proof; settlement is deferred to the batch.
+- Inspect outstanding (unbatched) SEPA balance and upcoming collections via the
+  buyer portal or `apiosk_get_credits_status`.
+- For the machine-readable version of this doc, call `apiosk_help` with
+  `topic="rails"`.

package/dxt.json

@@ -0,0 +1,46 @@
+{
+  "name": "apiosk-mcp",
+  "version": "1.3.0",
+  "description": "Official MCP server for browsing, paying for, and publishing Apiosk APIs",
+  "author": "Apiosk",
+  "license": "MIT",
+  "repository": "https://github.com/apiosk/apiosk-mcp",
+  "mcp": {
+    "command": "node",
+    "args": ["index.mjs"]
+  },
+  "tools": [
+    {
+      "name": "apiosk_explore",
+      "description": "Browse Apiosk listing groups before narrowing with search."
+    },
+    {
+      "name": "apiosk_search",
+      "description": "Search the Apiosk catalog and discover API-specific dynamic tools."
+    },
+    {
+      "name": "apiosk_payment_guide",
+      "description": "Guide for paying through the Apiosk gateway — buyer (how to settle a paid call) and provider (how to publish and get paid)."
+    },
+    {
+      "name": "apiosk_get_api",
+      "description": "Get full listing detail and agent metadata for a specific Apiosk slug."
+    },
+    {
+      "name": "apiosk_execute",
+      "description": "Fallback execute tool for any Apiosk API slug."
+    },
+    {
+      "name": "apiosk_wallet_create",
+      "description": "Create or import a local wallet for autonomous pay and publish flows."
+    },
+    {
+      "name": "apiosk_configure",
+      "description": "Show a structured wallet funding and Apiosk management menu, including QR output when available."
+    },
+    {
+      "name": "apiosk_publish_api",
+      "description": "Publish an API directly to Apiosk with signed wallet auth."
+    }
+  ]
+}

package/index.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createApioskMcpServer } from "./src/create-server.mjs";
+import { createApioskMcpRuntime } from "./src/runtime.mjs";
+
+const runtime = createApioskMcpRuntime({ enableLocalWallets: true });
+const server = createApioskMcpServer({ runtime });
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@apiosk/mcp",
+  "version": "1.3.0",
+  "description": "Official MCP server for browsing, paying for, and publishing Apiosk APIs",
+  "mcpName": "io.github.obcraft/apiosk-mcp",
+  "main": "index.mjs",
+  "exports": {
+    ".": "./src/create-server.mjs",
+    "./runtime": "./src/runtime.mjs",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "apiosk-mcp-server": "./index.mjs",
+    "apiosk-mcp": "./index.mjs",
+    "apiosk": "./index.mjs"
+  },
+  "scripts": {
+    "pack:check": "npm pack --dry-run",
+    "smoke:new-env": "bash scripts/smoke-new-env.sh",
+    "test:macbook-air": "bash scripts/test-macbook-air.sh",
+    "test:live": "bash scripts/test-live-url.sh",
+    "test": "node --test",
+    "dev": "node server.mjs",
+    "start": "node server.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "apiosk",
+    "api",
+    "model-context-protocol",
+    "x402",
+    "agent-tools",
+    "payments"
+  ],
+  "author": "Apiosk",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "type": "module",
+  "homepage": "https://apiosk.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apiosk/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/apiosk/mcp/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.mjs",
+    "server.mjs",
+    "well-known.mjs",
+    "server.json",
+    "dxt.json",
+    "src",
+    "README.md",
+    "docs"
+  ],
+  "dependencies": {
+    "@apiosk/sdk": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "express": "^5.2.1",
+    "qrcode": "^1.5.4",
+    "viem": "^2.47.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@flydotio/dockerfile": "^0.7.10",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.5.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}

package/server.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.obcraft/apiosk-mcp",
+  "title": "Apiosk",
+  "description": "Discover, pay for, execute, and publish Apiosk APIs through MCP.",
+  "version": "1.3.0",
+  "repository": {
+    "url": "https://github.com/obcraft/apiosk-mcp",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.apiosk.com/mcp"
+    }
+  ]
+}

package/server.mjs

@@ -0,0 +1,373 @@
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  SERVER_INFO,
+  createApioskMcpServer,
+  listApioskTools,
+} from "./src/create-server.mjs";
+import { createHostedOAuthSupport, resolveHostedMcpUrls } from "./src/oauth.mjs";
+import { createApioskMcpRuntime } from "./src/runtime.mjs";
+import {
+  resolveOpenAiAppsChallengeToken,
+  sendOpenAiAppsChallenge,
+} from "./well-known.mjs";
+
+const CONTROL_PLANE_BACKEND_URL = (
+  process.env.APIOSK_CONTROL_PLANE_BACKEND_URL ||
+  process.env.APIOSK_DASHBOARD_URL ||
+  "https://dashboard.apiosk.com"
+).replace(/\/+$/, "");
+const OPENAI_APPS_CHALLENGE_TOKEN = resolveOpenAiAppsChallengeToken(process.env);
+const OPENAI_APPS_CHALLENGE_PATH_PATTERN =
+  /^\/\.well-known\/openai-apps-challenge(?:\/\.well-known\/openai-apps-challenge)*\/?$/;
+
+function normalizeControlPlanePath(pathname = "") {
+  const basePath = String(pathname || "")
+    .split("?")[0]
+    .replace(/\/+$/, "");
+
+  if (!basePath) {
+    return "/";
+  }
+
+  if (basePath === "/api") {
+    return "/api";
+  }
+
+  if (basePath.startsWith("/api/")) {
+    return basePath;
+  }
+
+  if (basePath.startsWith("/")) {
+    return `/api${basePath}`;
+  }
+
+  return `/api/${basePath}`;
+}
+
+function shouldProxyControlPlanePath(pathname = "") {
+  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/")
+  );
+}
+
+async function proxyControlPlaneRequest(req, res) {
+  const targetUrl = new URL(req.originalUrl || req.url || "/", CONTROL_PLANE_BACKEND_URL);
+  const headers = new Headers();
+
+  for (const [key, value] of Object.entries(req.headers || {})) {
+    if (value == null) continue;
+    if (["host", "content-length", "connection"].includes(key.toLowerCase())) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) headers.append(key, item);
+    } else {
+      headers.set(key, value);
+    }
+  }
+
+  let body = undefined;
+  if (!["GET", "HEAD"].includes(req.method.toUpperCase())) {
+    if (typeof req.body === "string") {
+      body = req.body;
+    } else if (req.body !== undefined && req.body !== null) {
+      headers.set("content-type", headers.get("content-type") || "application/json");
+      body = JSON.stringify(req.body);
+    }
+  }
+
+  const response = await fetch(targetUrl, {
+    method: req.method,
+    headers,
+    body,
+    redirect: "manual",
+  });
+
+  res.status(response.status);
+  response.headers.forEach((value, key) => {
+    if (["content-encoding", "transfer-encoding", "connection"].includes(key.toLowerCase())) return;
+    res.setHeader(key, value);
+  });
+
+  const text = await response.text();
+  res.send(text);
+}
+
+function resolvePublicMcpUrl(req) {
+  const forwardedProto = String(req.headers["x-forwarded-proto"] || "").split(",")[0].trim();
+  const proto = forwardedProto || req.protocol || "https";
+  const host = req.headers.host || "mcp.apiosk.com";
+  return `${proto}://${host}/mcp`;
+}
+
+function renderMcpWelcomeHtml(mcpUrl) {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<meta name="robots" content="noindex" />
+<title>Apiosk MCP</title>
+<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; }
+</style>
+</head>
+<body>
+<main>
+  <div class="card">
+    <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>
+
+    <h2>Connect from Claude Code</h2>
+    <code>claude mcp add --transport http apiosk ${mcpUrl}</code>
+
+    <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>
+  </div>
+</main>
+</body>
+</html>`;
+}
+
+// Browsers (Accept: text/html) get a friendly welcome page; other non-protocol
+// callers get a JSON welcome. MCP protocol clients (Accept: text/event-stream)
+// are handled separately with the spec-compliant 405.
+function sendMcpWelcome(req, res) {
+  const mcpUrl = resolvePublicMcpUrl(req);
+  const accept = String(req.headers.accept || "");
+
+  if (accept.includes("text/html")) {
+    res.status(200).type("html").send(renderMcpWelcomeHtml(mcpUrl));
+    return;
+  }
+
+  res.status(200).json({
+    name: "Apiosk MCP",
+    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.",
+    transport: "streamable-http",
+    endpoint: mcpUrl,
+    connect: {
+      claude_code: `claude mcp add --transport http apiosk ${mcpUrl}`,
+    },
+    docs: "https://github.com/obcraft/apiosk-mcp",
+    health: "/health",
+  });
+}
+
+// Public Fly deployment must accept the Fly hostname instead of localhost-only
+// host validation defaults.
+const app = createMcpExpressApp({ host: "0.0.0.0" });
+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",
+  hostedAuthEnabled: true,
+});
+const hostedOAuth = createHostedOAuthSupport({
+  env: process.env,
+  controlPlaneBaseUrl: CONTROL_PLANE_BACKEND_URL,
+  issuerUrl,
+  mcpServerUrl,
+  appName: "Apiosk",
+  resourceName: "Apiosk MCP",
+});
+const mcpAuthMiddleware = hostedOAuth.createMcpAuthMiddleware(runtime);
+
+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);
+if (hostedOAuth.oauthMetadata.registration_endpoint) {
+  app.use(
+    new URL(hostedOAuth.oauthMetadata.registration_endpoint).pathname,
+    hostedOAuth.registrationRouter
+  );
+}
+
+app.get(OPENAI_APPS_CHALLENGE_PATH_PATTERN, (req, res) => {
+  return sendOpenAiAppsChallenge(res, OPENAI_APPS_CHALLENGE_TOKEN);
+});
+
+app.all("/api/*path", async (req, res) => {
+  try {
+    const pathname = req.path || req.originalUrl || "";
+    if (!shouldProxyControlPlanePath(pathname)) {
+      return res.status(404).json({
+        error: "not_found",
+        message: "Unknown MCP control-plane route.",
+        status: 404,
+      });
+    }
+
+    await proxyControlPlaneRequest(req, res);
+  } 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 });
+    res.json({
+      status: "ok",
+      server: SERVER_INFO,
+      tool_count: tools.length,
+    });
+  } catch (error) {
+    res.status(503).json({
+      status: "degraded",
+      server: SERVER_INFO,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+});
+
+app.post("/mcp", mcpAuthMiddleware, async (req, res) => {
+  const server = createApioskMcpServer({ runtime });
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+  });
+
+  try {
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+
+    res.on("close", () => {
+      transport.close().catch(() => {});
+      server.close().catch(() => {});
+    });
+  } catch (error) {
+    console.error("Error handling MCP request:", error);
+
+    if (!res.headersSent) {
+      return res.status(500).json({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32603,
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    }
+  } finally {
+    if (res.writableEnded) {
+      await transport.close().catch(() => {});
+      await server.close().catch(() => {});
+    }
+  }
+});
+
+app.get("/mcp", (req, res) => {
+  const accept = String(req.headers.accept || "");
+
+  // MCP Streamable HTTP clients open the optional SSE stream via a GET with
+  // Accept: text/event-stream. This stateless server does not provide that
+  // stream, so keep the spec-compliant 405 for protocol clients.
+  if (accept.includes("text/event-stream")) {
+    return res.status(405).json({
+      jsonrpc: "2.0",
+      id: null,
+      error: {
+        code: -32000,
+        message: "Method not allowed.",
+      },
+    });
+  }
+
+  // Humans navigating here in a browser (or curling the URL) get a welcome.
+  return sendMcpWelcome(req, res);
+});
+
+app.delete("/mcp", (req, res) => {
+  res.status(405).json({
+    jsonrpc: "2.0",
+    id: null,
+    error: {
+      code: -32000,
+      message: "Method not allowed.",
+    },
+  });
+});
+
+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(`OAuth issuer: ${issuerUrl.href}`);
+  console.log(`OAuth protected-resource metadata: ${hostedOAuth.resourceMetadataUrl}`);
+  try {
+    const tools = await listApioskTools({ runtime });
+    console.log(`Loaded ${tools.length} tools from the Apiosk catalog.`);
+  } catch (error) {
+    console.warn(
+      `Unable to prefetch Apiosk catalog on startup: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+});

package/src/create-server.mjs

@@ -0,0 +1,37 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { createApioskMcpRuntime } from "./runtime.mjs";
+
+export const SERVER_INFO = {
+  name: "apiosk-mcp",
+  version: "1.3.0",
+};
+
+function resolveRuntime(options = {}) {
+  return options.runtime || createApioskMcpRuntime(options);
+}
+
+export async function listApioskTools(options = {}) {
+  return resolveRuntime(options).listTools(options.authInfo);
+}
+
+export function createApioskMcpServer(options = {}) {
+  const runtime = resolveRuntime(options);
+  const server = new Server(
+    SERVER_INFO,
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => ({
+    tools: await runtime.listTools(extra.authInfo),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    return runtime.callTool(request.params.name, request.params.arguments || {}, extra.authInfo);
+  });
+
+  return server;
+}