crawlforge-mcp-server 5.10.0 → 6.1.0

package/src/server/requestContext.js

@@ -69,3 +69,53 @@ export function setActualCost(n) {
 export function reportedActualCost() {
   return requestContext.getStore()?.actualCost ?? null;
 }
+
+/**
+ * Record the McpServer instance that is actually serving this request, and the
+ * wire era it speaks.
+ *
+ * Neither HTTP leg serves from the top-level McpServer that server.js
+ * registers everything on: the 2025-era path connects one clone per session,
+ * and the modern leg builds a fresh clone per request (see
+ * transports/streamableHttp.js). Only a clone is ever `.connect()`ed, so only a
+ * clone has a negotiated protocol version, the client's declared capabilities,
+ * and a channel to send a server-to-client request on. The template has none of
+ * those, which is why anything reading them off it (ElicitationHelper) got
+ * `undefined` on every HTTP request.
+ *
+ * Stdio stamps nothing: there the top-level instance IS the connected one, and
+ * the accessors below return null so callers fall back to it.
+ *
+ * @param {object|null} server the serving McpServer
+ * @param {'legacy'|'modern'|null} [era] the wire era it serves
+ */
+export function setServingServer(server, era = null) {
+  const store = requestContext.getStore();
+  if (!store) return;
+  store.servingServer = server ?? null;
+  store.servingEra = era;
+}
+
+/** The McpServer serving this request, or null on stdio / outside a context. */
+export function servingServer() {
+  return requestContext.getStore()?.servingServer ?? null;
+}
+
+/** The wire era serving this request: 'legacy' | 'modern' | null (stdio). */
+export function servingEra() {
+  return requestContext.getStore()?.servingEra ?? null;
+}
+
+/**
+ * The JSON-RPC id of the request being served, or null when unknown.
+ *
+ * A server-to-client request sent from inside a tool has to say which inbound
+ * request it belongs to: the 2025-era streamable HTTP transport routes an
+ * unrelated request to the standalone GET SSE stream and silently DROPS it when
+ * the client never opened one, which turns an elicitation prompt into a
+ * 60-second stall before it fails open. withAuth stamps this from the SDK's
+ * per-request `ctx`; stdio has no streams to pick between and ignores it.
+ */
+export function servingRequestId() {
+  return requestContext.getStore()?.servingRequestId ?? null;
+}

package/src/server/specHygiene.js

@@ -1,19 +1,22 @@
 /**
  * specHygiene — Phase 6 protocol-hygiene wrapper.
  *
- * Applies three MCP wire-level upgrades to an already-registered McpServer
+ * Applies four MCP wire-level upgrades to an already-registered McpServer
  * without changing how tools/prompts are declared anywhere else:
  *
  *   1. JSON Schema 2020-12 dialect stamping on every tool's inputSchema /
- *      outputSchema (the SDK's zod-to-json-schema conversion still emits
- *      draft-07-style `definitions` / `#/definitions/...` refs).
+ *      outputSchema. Under the v2 SDK + zod 4 the conversion already emits
+ *      2020-12 with `$defs`, so the `definitions` -> `$defs` rewrite below is
+ *      now defensive rather than load-bearing; it is kept because the stamping
+ *      and ordering passes still walk the same tree (Phase 4.1 kept behaviour
+ *      identical — removing the rewrite is a separate, verifiable change).
  *   2. Deterministic (alphabetical) tool ordering in tools/list, so clients
  *      that prompt-cache tools/list get stable hits across restarts.
  *   3. SEP-973 icons metadata on every tool/prompt lacking one.
  *   4. SEP-2549-style cache hints on tools/call results for a fixed
  *      allowlist of read-only, idempotent tools (see note below).
  *
- * Wiring: SDK 1.30 has no plugin hook for this, so applySpecHygiene() must be
+ * Wiring: the SDK has no plugin hook for this, so applySpecHygiene() must be
  * called once, after all server.registerTool()/registerPrompt() calls and
  * before transport.connect(). It reaches into `server.server` (the
  * underlying Protocol), captures the ListTools/CallTool/ListPrompts handlers
@@ -22,26 +25,18 @@
  * handler for the same method (confirmed from the SDK source: only
  * `assertCanSetRequestHandler`, called by McpServer's own registration path,
  * throws on a pre-existing handler; `setRequestHandler` itself does not).
+ * In v2 `setRequestHandler` takes a method string rather than a Zod schema.
  *
- * SEP-2549 note: as specified (2026-07-28 RC), `ttlMs` / `cacheScope`
- * ("public"|"private") are defined on tools/list, prompts/list,
- * resources/list, resources/read and resources/templates/list results —
- * there is no CacheableResult for tools/call. Since this deliverable asks
- * for tools/call cache hints, the same two field names are carried into a
- * namespaced `_meta` key following the SDK's own
- * `io.modelcontextprotocol/<name>` convention (see RELATED_TASK_META_KEY in
- * @modelcontextprotocol/sdk/types.js):
+ * SEP-2549 note: as specified (2026-07-28), `ttlMs` / `cacheScope`
+ * ("public"|"private") are defined on server/discover results — there is no
+ * CacheableResult for tools/call. Since this deliverable asks for tools/call
+ * cache hints, the same two field names are carried into a namespaced `_meta`
+ * key following the SDK's own `io.modelcontextprotocol/<name>` convention:
  *   result._meta["io.modelcontextprotocol/cacheable"] = { ttlMs, cacheScope }
  * This is a documented adaptation, not a key confirmed by the spec text for
  * tools/call — revisit if/when a SEP defines call-result caching explicitly.
  */
 
-import {
-  ListToolsRequestSchema,
-  CallToolRequestSchema,
-  ListPromptsRequestSchema
-} from '@modelcontextprotocol/sdk/types.js';
-
 const APPLIED = Symbol('crawlforge.specHygiene.applied');
 
 const JSON_SCHEMA_2020_12 = 'https://json-schema.org/draft/2020-12/schema';
@@ -158,7 +153,7 @@ function wrapToolsCall(innerHandler, cacheableTools) {
  * tools/prompts are registered and before transport.connect(). Idempotent:
  * a second call on the same server is a no-op.
  *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/server').McpServer} server
  * @param {object} [overrides]
  * @param {{src:string,mimeType?:string,sizes?:string[]}} [overrides.icon] — default icon injected into tools/prompts lacking one
  * @param {Record<string,{ttlMs:number,cacheScope:'public'|'private'}>} [overrides.cacheableTools] — tool-name -> cache hint map for tools/call
@@ -177,16 +172,16 @@ export function applySpecHygiene(server, overrides = {}) {
 
   const innerToolsList = protocol._requestHandlers.get('tools/list');
   if (innerToolsList) {
-    protocol.setRequestHandler(ListToolsRequestSchema, wrapToolsList(innerToolsList, icon));
+    protocol.setRequestHandler('tools/list', wrapToolsList(innerToolsList, icon));
   }
 
   const innerToolsCall = protocol._requestHandlers.get('tools/call');
   if (innerToolsCall) {
-    protocol.setRequestHandler(CallToolRequestSchema, wrapToolsCall(innerToolsCall, cacheableTools));
+    protocol.setRequestHandler('tools/call', wrapToolsCall(innerToolsCall, cacheableTools));
   }
 
   const innerPromptsList = protocol._requestHandlers.get('prompts/list');
   if (innerPromptsList) {
-    protocol.setRequestHandler(ListPromptsRequestSchema, wrapPromptsList(innerPromptsList, icon));
+    protocol.setRequestHandler('prompts/list', wrapPromptsList(innerPromptsList, icon));
   }
 }

package/src/server/transports/stdio.js

@@ -2,12 +2,11 @@
  * stdio transport setup — extracted from server.js runServer().
  * Used when server is launched without the --http flag.
  */
-
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 
 /**
  * Connect the MCP server to stdio transport and log startup message.
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/server').McpServer} server
  */
 export async function connectStdio(server) {
   const transport = new StdioServerTransport();

package/src/server/transports/streamableHttp.js

@@ -1,42 +1,62 @@
 /**
- * Streamable HTTP transport (MCP spec 2025-06-18).
+ * Dual-era Streamable HTTP transport.
  *
- * Single endpoint at /mcp:
- *   - POST /mcp           — JSON-RPC request, response as JSON or SSE stream
- *   - GET  /mcp           — SSE stream for server → client notifications
- *   - DELETE /mcp         — terminate session
+ * One endpoint at /mcp serves both protocol eras, routed by the SDK's own
+ * classification (`isLegacyRequest`) so this module can never disagree with it:
  *
- * Session resumption:
- *   - Server generates a session id and returns it as `Mcp-Session-Id` on init
- *   - Clients re-send `Mcp-Session-Id` on subsequent requests to resume state
+ *   - 2026-07-28 ("modern"): stateless, one server instance per request, each
+ *     request carrying its own `_meta` envelope (protocol version, clientInfo,
+ *     clientCapabilities) plus the SEP-2243 `Mcp-Method` / `Mcp-Name` headers.
+ *     Served by `createMcpHandler(..., { legacy: 'reject' })`, which owns the
+ *     Content-Type gate (415), the header/body cross-checks (-32020) and
+ *     `server/discover`.
+ *   - 2025-era ("legacy"): the sessionful path below — POST /mcp initialize
+ *     issues an `Mcp-Session-Id`, GET /mcp opens the notification SSE stream,
+ *     DELETE /mcp terminates the session. One transport + cloned McpServer per
+ *     session, kept in the `sessions` Map.
  *
  * Auth:
- *   - Bearer / X-API-Key required per request (creator mode bypasses)
+ *   - Bearer / X-API-Key required per request on BOTH eras, before any era
+ *     routing happens (creator mode bypasses, loopback only)
  *   - When OAuth is enabled (CRAWLFORGE_OAUTH_ENABLED=true), OAuth bearer
  *     tokens are validated by the OAuth provider and mapped server-side to
  *     a CrawlForge API key. See src/server/auth/oauth.js.
  *
  * Observability:
  *   - GET /metrics returns Prometheus exposition (when observability enabled)
- *   - GET /health returns liveness probe
- *
- * Replaces the legacy stateless http.js. Old /mcp endpoint behavior is
- * preserved when CRAWLFORGE_LEGACY_HTTP=true (one-release deprecation window);
- * `http.js`'s connectHttp() forwards straight into this module's legacy mode.
+ *   - GET /health returns liveness probe + the protocol revisions served
  */
-
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, createMcpHandler, isLegacyRequest, SUPPORTED_PROTOCOL_VERSIONS } from "@modelcontextprotocol/server";
+import { NodeStreamableHTTPServerTransport, toNodeHandler, toWebRequest } from "@modelcontextprotocol/node";
 import { createServer } from 'node:http';
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { requestContext } from '../requestContext.js';
-import { z } from 'zod';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { requestContext, setServingServer } from '../requestContext.js';
+import { applySpecHygiene } from '../specHygiene.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
 const SERVER_VERSION = pkg.version;
 
+/**
+ * Protocol revisions this endpoint serves, newest first: the modern era's
+ * revisions followed by the 2025-era list the SDK negotiates via `initialize`.
+ *
+ * The modern list mirrors the SDK's internal SUPPORTED_MODERN_PROTOCOL_VERSIONS,
+ * which is deliberately not exported. streamableHttp.test.js pins it against a
+ * live `server/discover` result, so an SDK upgrade that adds a revision fails a
+ * test rather than drifting silently.
+ */
+const MODERN_PROTOCOL_VERSIONS = Object.freeze(['2026-07-28']);
+const PROTOCOL_VERSIONS = Object.freeze([...MODERN_PROTOCOL_VERSIONS, ...SUPPORTED_PROTOCOL_VERSIONS]);
+
+/**
+ * SEP-2549 cache hint for the `server/discover` result (2026-07-28 only). The
+ * advertisement is the same for every caller and only changes when the server
+ * is redeployed, so it is `public`; the 5-minute TTL matches the tools/call
+ * hints in specHygiene.js. Without a hint the SDK emits `0` / `'private'`.
+ */
+const DISCOVER_CACHE_HINT = Object.freeze({ ttlMs: 300000, cacheScope: 'public' });
+
 /**
  * Build the `tools` array for the Smithery static server card, straight from
  * the live tool registry.
@@ -59,10 +79,9 @@ function buildToolCards(server) {
     .map(([name, tool]) => {
       let inputSchema = { type: 'object', properties: {} };
       try {
-        const shape = tool?.inputSchema;
-        if (shape) {
-          const zodObject = typeof shape?.safeParse === 'function' ? shape : z.object(shape);
-          const converted = zodToJsonSchema(zodObject, { $refStrategy: 'none' });
+        if (tool?.inputSchema) {
+          // The SDK's own conversion, so the card mirrors what tools/list serves.
+          const converted = { ...server.toolInputSchemaJson(name) };
           delete converted.$schema;
           inputSchema = converted;
         }
@@ -89,23 +108,34 @@ function buildToolCards(server) {
  * prompt tables — plain config + handler-closure references, no per-connection
  * state — then re-runs the same internal handler-wiring methods McpServer
  * itself calls from registerTool/registerResource/registerPrompt. This
- * depends on @modelcontextprotocol/sdk 1.30.0's internal McpServer/Server
- * field names (`_registered*`, `set*RequestHandlers`, `_capabilities`,
- * `_taskStore`); re-check on SDK upgrades.
+ * depends on the SDK's internal McpServer/Server field names
+ * (`_registered*`, `set*RequestHandlers`, `_capabilities`); re-verified
+ * against @modelcontextprotocol/server 2.0.0, which still exposes all of
+ * them. `_taskStore` is gone — v2 removed experimental tasks (SEP-2663).
+ * Re-check on SDK upgrades.
+ *
+ * The same clone backs a 2025-era session and a single 2026-era request, so
+ * both eras serve exactly the same tools — the SDK's "one factory for both
+ * legs" rule.
+ *
+ * applySpecHygiene() runs on the clone because its wrappers live on the
+ * template's own Protocol instance, not in the `_registered*` tables the clone
+ * copies: without this call an HTTP client got unsorted, icon-less tools/list
+ * results and no SEP-2549 cache markers on tools/call, while a stdio client
+ * got all three.
  *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} templateServer
+ * @param {import('@modelcontextprotocol/server').McpServer} templateServer
  */
 function cloneServerForSession(templateServer) {
   const low = templateServer.server;
-  // capabilities + taskStore must survive the clone: the SDK's Protocol
-  // constructor wires the tasks/* request handlers only when options.taskStore
-  // is present, and without it a tools/call on any task-capable tool
-  // (crawl_deep, batch_scrape, deep_research, agent) throws
-  // 'No task store provided for task-capable tool.'
+  // capabilities must survive the clone so the session server advertises the
+  // same surface as the template. cacheHints only reaches the 2026-era encode
+  // seam (it rides a symbol-keyed property that is never serialized), so a
+  // 2025-era response is byte-identical with or without it.
   const sessionServer = new McpServer(low._serverInfo, {
     instructions: low._instructions,
     capabilities: low._capabilities,
-    taskStore: low._taskStore
+    cacheHints: { 'server/discover': DISCOVER_CACHE_HINT }
   });
 
   sessionServer._registeredTools = templateServer._registeredTools;
@@ -118,9 +148,18 @@ function cloneServerForSession(templateServer) {
   if (templateServer._promptHandlersInitialized) sessionServer.setPromptRequestHandlers();
   if (templateServer._completionHandlerInitialized) sessionServer.setCompletionRequestHandler();
 
+  applySpecHygiene(sessionServer);
+
   return sessionServer;
 }
 
+/** Reads a request body to completion as UTF-8. */
+async function readRequestBody(req) {
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
 /** Best-effort close — swallows errors so cleanup never throws into a request handler. */
 function safeClose(closable) {
   if (closable && typeof closable.close === 'function') {
@@ -138,14 +177,14 @@ function sendRpcError(res, status, code, message) {
 }
 
 /**
- * Stateful, session-aware Streamable HTTP transport.
+ * Dual-era Streamable HTTP transport: stateless 2026-07-28 and sessionful
+ * 2025-era traffic on the same /mcp route.
  *
- * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {import('@modelcontextprotocol/server').McpServer} server
  * @param {import('../../core/AuthManager.js').default} authManager
  * @param {import('../../utils/Logger.js').logger} logger
  * @param {object} [options]
  * @param {number} [options.port=3000]
- * @param {boolean} [options.legacy=false]  — if true, run in stateless mode (3.1 behavior)
  * @param {object} [options.oauth]          — OAuth provider (see src/server/auth/oauth.js)
  * @param {object} [options.metrics]        — Prometheus registry (see src/observability/metrics.js)
  */
@@ -159,22 +198,44 @@ export async function connectStreamableHttp(server, authManager, logger, options
   if (authManager.isCreatorMode() && !hostIsLoopback) {
     console.error(`WARNING: creator mode is enabled but the server is bound to ${host} (non-loopback) — per-request auth will NOT be bypassed. Bind to 127.0.0.1 to use creator mode.`);
   }
-  const legacy = options.legacy === true;
   const oauthProvider = options.oauth ?? null;
   const metrics = options.metrics ?? null;
 
-  const mode = legacy ? 'legacy-stateless' : 'streamable-stateful';
+  const mode = 'streamable-stateful';
   const toolCount = Object.keys(server._registeredTools ?? {}).length;
 
   // sessionId -> { transport, server }. One StreamableHTTPServerTransport (and
   // therefore one cloned McpServer — see cloneServerForSession) per session.
+  // 2025-era only: the modern era is stateless and holds nothing here.
   const sessions = new Map();
 
+  // 2026-07-28 leg. `legacy: 'reject'` keeps it strict — every 2025-era request
+  // is routed to the sessions Map above by isLegacyRequest before it can reach
+  // this handler, so the modern leg never has to serve one. The SDK owns the
+  // Content-Type gate (415), the Mcp-Method/Mcp-Name cross-checks (-32020 on
+  // 400) and `server/discover`; nothing here re-implements them.
+  // The factory runs once per request, inside the requestContext.run() below,
+  // so the clone it builds can be stamped on the store: that clone — never the
+  // template — is the instance this request is actually served from.
+  const modernHandler = createMcpHandler((ctx) => {
+    const requestServer = cloneServerForSession(server);
+    setServingServer(requestServer, ctx?.era ?? 'modern');
+    return requestServer;
+  }, {
+    legacy: 'reject',
+    onerror: (err) => logger.warn('2026-era MCP request rejected', { error: err?.message })
+  });
+  const serveModern = toNodeHandler(modernHandler, {
+    onerror: (err) => logger.error('2026-era MCP request failed', { error: err?.message })
+  });
+
   const httpServer = createServer(async (req, res) => {
     // CORS — Smithery + browser-based MCP clients
     res.setHeader('Access-Control-Allow-Origin', '*');
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id, mcp-session-id, Authorization, X-API-Key, X-Internal-Secret');
+    // MCP-Protocol-Version / Mcp-Method / Mcp-Name are the 2026-07-28 era's
+    // request headers; the session id headers are the 2025 era's.
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id, mcp-session-id, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Authorization, X-API-Key, X-Internal-Secret');
     res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id, mcp-session-id');
 
     if (req.method === 'OPTIONS') {
@@ -186,7 +247,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
     // Health probe
     if (req.url === '/health') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ status: 'ok', version: SERVER_VERSION, mode }));
+      res.end(JSON.stringify({ status: 'ok', version: SERVER_VERSION, mode, protocolVersions: PROTOCOL_VERSIONS }));
       return;
     }
 
@@ -273,38 +334,45 @@ export async function connectStreamableHttp(server, authManager, logger, options
         internal = authResult.internal === true;
       }
 
-      if (legacy) {
-        // Stateless mode: the SDK forbids reusing a transport (or its connected
-        // Server) across requests, so build a fresh pair per request and always
-        // end the response, even on failure.
-        let sessionServer;
-        let reqTransport;
+      // Era routing. Only a POST can carry the 2026-07-28 per-request envelope;
+      // body-less GET/DELETE are 2025 session operations by construction and
+      // isLegacyRequest classifies them as such, so they skip this entirely and
+      // keep their existing behaviour byte-for-byte.
+      //
+      // Reading the body here drains the Node stream, so the parsed value is
+      // handed to whichever leg serves the request. A body that is not valid
+      // JSON classifies legacy (the SDK's own rule), and the 2025 transport
+      // still writes its own parse error — hence the undefined pass-through
+      // rather than an answer invented here.
+      let parsedBody;
+      if (req.method === 'POST') {
         try {
-          sessionServer = cloneServerForSession(server);
-          reqTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-          await sessionServer.connect(reqTransport);
-          await requestContext.run({ internal }, () => reqTransport.handleRequest(req, res));
-        } catch (err) {
-          logger.error('Legacy Streamable HTTP request failed', { error: err?.message });
-          sendRpcError(res, 500, -32603, 'Internal server error');
-        } finally {
-          res.on('close', () => {
-            safeClose(reqTransport);
-            safeClose(sessionServer);
-          });
+          parsedBody = JSON.parse(await readRequestBody(req));
+        } catch {
+          parsedBody = undefined;
+        }
+
+        if (parsedBody !== undefined) {
+          const probe = await toWebRequest(req, parsedBody);
+          if (!(await isLegacyRequest(probe, parsedBody))) {
+            await requestContext.run({ internal }, () => serveModern(req, res, parsedBody));
+            return;
+          }
         }
-        return;
       }
 
-      // Stateful mode: route by Mcp-Session-Id. A request without the header
-      // must be a fresh initialize, which gets its own transport + server pair
+      // 2025 era: route by Mcp-Session-Id. A request without the header must be
+      // a fresh initialize, which gets its own transport + server pair
       // (independent of any prior session's lifecycle) so reconnects/re-inits
       // never hit a stuck 'already initialized' transport.
       const sessionIdHeader = req.headers['mcp-session-id'];
       const existing = sessionIdHeader ? sessions.get(String(sessionIdHeader)) : undefined;
 
       if (existing) {
-        await requestContext.run({ internal }, () => existing.transport.handleRequest(req, res));
+        await requestContext.run(
+          { internal, servingServer: existing.server, servingEra: 'legacy' },
+          () => existing.transport.handleRequest(req, res, parsedBody)
+        );
         return;
       }
 
@@ -321,7 +389,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
       }
 
       const sessionServer = cloneServerForSession(server);
-      const transport = new StreamableHTTPServerTransport({
+      const transport = new NodeStreamableHTTPServerTransport({
         sessionIdGenerator: () => randomUUID(),
         onsessioninitialized: (sid) => {
           sessions.set(sid, { transport, server: sessionServer });
@@ -337,7 +405,10 @@ export async function connectStreamableHttp(server, authManager, logger, options
 
       try {
         await sessionServer.connect(transport);
-        await requestContext.run({ internal }, () => transport.handleRequest(req, res));
+        await requestContext.run(
+          { internal, servingServer: sessionServer, servingEra: 'legacy' },
+          () => transport.handleRequest(req, res, parsedBody)
+        );
       } catch (err) {
         logger.error('Streamable HTTP session initialization failed', { error: err?.message });
         safeClose(transport);
@@ -355,7 +426,7 @@ export async function connectStreamableHttp(server, authManager, logger, options
     httpServer.listen(port, host, () => {
       const actual = httpServer.address()?.port ?? port;
       console.error(`CrawlForge MCP Server v${SERVER_VERSION} listening on ${host}:${actual} (Streamable HTTP, ${mode})`);
-      console.error(`MCP endpoint:   http://${host}:${actual}/mcp`);
+      console.error(`MCP endpoint:   http://${host}:${actual}/mcp (protocol ${PROTOCOL_VERSIONS.join(', ')})`);
       console.error(`Health check:   http://${host}:${actual}/health`);
       if (metrics) console.error(`Metrics:        http://${host}:${actual}/metrics`);
       if (oauthProvider) console.error(`OAuth discovery: http://${host}:${actual}/.well-known/oauth-authorization-server`);
@@ -366,13 +437,17 @@ export async function connectStreamableHttp(server, authManager, logger, options
   return {
     httpServer,
     sessions,
-    /** Closes every live session's transport + server, then the HTTP server. */
+    /**
+     * Closes every live 2025-era session's transport + server and the modern
+     * leg (aborting in-flight exchanges), then the HTTP server.
+     */
     async close() {
       for (const { transport, server: sessionServer } of sessions.values()) {
         safeClose(transport);
         safeClose(sessionServer);
       }
       sessions.clear();
+      await modernHandler.close().catch(() => {});
       await new Promise((resolve) => httpServer.close(() => resolve()));
     }
   };

package/src/server/withAuth.js

@@ -8,7 +8,11 @@
  *     so a valid API key is required for every invocation
  *   - try/finally guarantees a single `tool invocation` log line per call
  *   - log payload: { toolName, paramHash, durationMs, outcome, creditCost, creatorMode }
- *   - outcome ∈ { 'success' | 'error' | 'insufficient_credits' }
+ *   - outcome ∈ { 'success' | 'error' | 'insufficient_credits' | 'input_required' }
+ *   - an `input_required` return (Phase 4.4) is a round trip, not an answer: the
+ *     handler did no work, so it is billed NOTHING and reports no usage. The
+ *     SDK re-enters the handler with the reply and the terminal entry bills
+ *     once, so a confirmation costs exactly what the call always cost (G4).
  *   - error results get a "Next step:" hint naming the tool to try next
  *     (src/server/fallbackHints.js) so a failure is not followed by a blind retry
  *   - emits an OTel span via src/observability/tracing.js (no-op if disabled)
@@ -16,6 +20,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { isInputRequiredResult } from '@modelcontextprotocol/server';
 import { recordToolInvocation } from '../observability/tracing.js';
 import { isInternalRequest, preflightRefusal, reportedActualCost, requestContext } from './requestContext.js';
 import { appendFallbackHint } from './fallbackHints.js';
@@ -71,7 +76,7 @@ export function hashParams(params) {
  */
 export function makeWithAuth({ authManager, logger, metrics = null, mcpServer = null }) {
   return function withAuth(toolName, handler) {
-    const invoke = async (params) => {
+    const invoke = async (params, ctx) => {
       const startTime = Date.now();
       const paramHash = hashParams(params);
       const creatorMode = authManager.isCreatorMode();
@@ -109,7 +114,14 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
         // end user's credits before forwarding — checking the static key's
         // balance here would gate users on an unrelated account).
         if (!billingExempt) {
-          const hasCredits = await authManager.checkCredits(creditCost);
+          const hasCredits = await authManager.checkCredits(creditCost, ctx);
+          // The low-credit warning asks as a round trip (Phase 4.4). Nothing has
+          // run, so this costs nothing and reports no usage; the SDK re-enters
+          // with the answer.
+          if (isInputRequiredResult(hasCredits)) {
+            outcome = 'input_required';
+            return hasCredits;
+          }
           if (!hasCredits) {
             outcome = 'insufficient_credits';
             return {
@@ -127,7 +139,21 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
         }
 
         handlerStarted = true;
-        const result = await handler(params);
+        const result = await handler(params, ctx);
+
+        // Phase 4.4: a multi-round-trip handler answers `input_required` when it
+        // needs the user before it can start. Nothing was fetched, so nothing is
+        // owed: no charge, no usage report, and none of the result stages below
+        // (there is no result yet to redact, shape or price). The SDK gathers the
+        // answer and re-enters this same wrapper; whichever entry finally returns
+        // a real result is the one that bills, exactly once. Without this branch
+        // an `input_required` is not `isError`, so it books as a success and
+        // bills in full on every round — up to eight — for a call that did no
+        // work, and a declined confirmation bills too (G4).
+        if (isInputRequiredResult(result)) {
+          outcome = 'input_required';
+          return result;
+        }
 
         // Tools catch their own failures and return { isError:true } rather than
         // throwing (the shared pattern in server.js). That is still an ERROR
@@ -275,11 +301,23 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
 
     // Every invocation runs in its own context so the compliance gate can stamp
     // a refusal where the billing decision can see it. Any outer store (the
-    // HTTP transport's `internal` flag) is spread in, not replaced — and stdio
-    // callers, who have no transport-provided store, get one here.
-    return async (params) => requestContext.run(
-      { ...(requestContext.getStore() ?? {}), preflightRefusal: null, actualCost: null },
-      () => invoke(params)
+    // HTTP transport's `internal` flag, the serving McpServer) is spread in,
+    // not replaced — and stdio callers, who have no transport-provided store,
+    // get one here.
+    //
+    // `ctx` is the SDK's per-request context (v2 calls a tool callback with
+    // `(args, ctx)`). It is passed straight through to the handler; existing
+    // 1-arity handlers ignore it. Its request id is stamped on the context so a
+    // server-to-client request sent from inside the tool can ride the same
+    // stream as this call — see servingRequestId() in requestContext.js.
+    return async (params, ctx) => requestContext.run(
+      {
+        ...(requestContext.getStore() ?? {}),
+        preflightRefusal: null,
+        actualCost: null,
+        servingRequestId: ctx?.mcpReq?.id
+      },
+      () => invoke(params, ctx)
     );
   };
 }