@ultimatelemon-eu/mcp-http 1.0.0 → 2.1.0

package/README.md

@@ -2,58 +2,77 @@
 
 Runs an [MCP](https://modelcontextprotocol.io) server over Streamable HTTP in
 stateless mode: `POST /mcp`, `GET /healthz`, an optional base path for a proxy,
-and a JSON-RPC 500 instead of a stack trace when a handler throws. Everything
-else is your tools.
+an optional API key the caller brings, and a JSON-RPC 500 instead of a stack
+trace when a handler throws. Everything else is your tools.
 
 ```bash
-npm install @ultimatelemon-eu/mcp-http @modelcontextprotocol/sdk
+npm install @ultimatelemon-eu/mcp-http @modelcontextprotocol/server @modelcontextprotocol/node
 ```
 
 ```ts
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer } from '@modelcontextprotocol/server';
 import { startMcpHttpServer } from '@ultimatelemon-eu/mcp-http';
 
-function createMcpServer() {
-  const server = new McpServer({ name: 'my-mcp', version: '1.0.0' });
-  server.registerTool('ping', { description: 'Replies pong' }, () => ({
-    content: [{ type: 'text', text: 'pong' }]
-  }));
-  return server;
-}
-
 const http = await startMcpHttpServer({
-  createMcpServer,
-  port: Number(process.env.PORT ?? 3000)
+  createMcpServer: ({ apiKey }) => {
+    const server = new McpServer({ name: 'my-mcp', version: '1.0.0' });
+    server.registerTool('ping', { description: 'Replies pong' }, () => ({
+      content: [{ type: 'text', text: `pong for ${apiKey}` }]
+    }));
+    return server;
+  },
+  port: Number(process.env.PORT ?? 3000),
+  apiKey: { hint: 'Create one at https://example.com/keys.' }
 });
 
-process.once('SIGTERM', () => void http.close().then(() => process.exit(0)));
+process.once('SIGTERM', () => {
+  void http.close().then(
+    () => process.exit(0),
+    () => process.exit(0)
+  );
+});
 ```
 
 ## Options
 
-| Option            | Default     | Does                                                 |
-| ----------------- | ----------- | ---------------------------------------------------- |
-| `createMcpServer` | required    | Returns a new `McpServer`; called once per request   |
-| `port`            | required    | `0` picks a free port; read it back from `.port`     |
-| `host`            | `'0.0.0.0'` | `'127.0.0.1'` keeps it local                         |
-| `basePath`        | `''`        | Also serve `<basePath>/mcp` and `<basePath>/healthz` |
-| `health`          | always ok   | Return `false` for a 503 on `/healthz`               |
-| `logger`          | silent      | Anything with `error(obj, msg)`, such as pino        |
+| Option            | Default     | Does                                                                          |
+| ----------------- | ----------- | ----------------------------------------------------------------------------- |
+| `createMcpServer` | required    | Returns a new `McpServer` per request, given `{ apiKey }`                     |
+| `port`            | required    | `0` picks a free port; read it back from `.port`                              |
+| `host`            | `'0.0.0.0'` | `'127.0.0.1'` keeps it local                                                  |
+| `basePath`        | `''`        | Also serve MCP on `<basePath>` and `<basePath>/mcp`, and `<basePath>/healthz` |
+| `health`          | always ok   | Return `false` for a 503 on `/healthz`                                        |
+| `apiKey`          | off         | Require the caller's key; `hint` is added to the 401 message                  |
+| `logger`          | silent      | Anything with `error(obj, msg)`, such as pino                                 |
 
 It returns `{ url, port, close() }`.
 
+## API key
+
+With `apiKey` set, every request to `/mcp` must carry the caller's own key for
+the upstream API, in `X-Api-Key` or as `Authorization: Bearer <key>`
+(`X-Api-Key` wins when both are present). Without one the server answers 401
+before building an MCP server. The key reaches `createMcpServer` as
+`apiKey`; it is never logged or stored.
+
+This suits public servers where each user brings their own credentials: no
+OAuth, no sessions, no database. In claude.ai, add the connector with
+"No sign-in" and the key as a request header.
+
 ## Why stateless
 
-A new server and transport per request means no session table, so it does not
-matter which replica a request lands on and a restart loses nothing. The
-price: no server-initiated messages and no `GET` stream, which is why `GET` and
-`DELETE` on `/mcp` answer 405. Tools that read and return data do not need
-either.
+A new server per request means no session table, so it does not matter which
+replica a request lands on and a restart loses nothing. The price: no
+server-initiated messages outside a request and no `GET` stream, which is why
+`GET` and `DELETE` on `/mcp` answer 405. Tools that read and return data do not
+need either.
 
-Keep shared state, such as an API client, a cache or a loaded list, outside
-`createMcpServer` and close over it, so a request only builds the thin server.
+Keep shared state, such as a cache or a loaded list, outside `createMcpServer`
+and close over it, so a request only builds the thin server.
 
-## Auth
+## Upgrading from 1.x
 
-There is none. Put the server behind an authenticating proxy (Airlock, for the
-UltimateLemon MCPs) or keep it on localhost.
+- The MCP SDK moved to v2: replace `@modelcontextprotocol/sdk` with
+  `@modelcontextprotocol/server` and `@modelcontextprotocol/node`, and import
+  `McpServer` from `@modelcontextprotocol/server`.
+- `createMcpServer` receives a context object and may return a promise.

package/dist/index.d.ts

@@ -1 +1 @@
-export { startMcpHttpServer, type Logger, type McpHttpOptions, type McpHttpServer } from './server.js';
+export { startMcpHttpServer, type ApiKeyOptions, type Logger, type McpHttpOptions, type McpHttpServer, type RequestContext } from './server.js';

package/dist/server.d.ts

@@ -1,18 +1,28 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type McpServer } from '@modelcontextprotocol/server';
 /** The slice of a pino-style logger this package calls. */
 export interface Logger {
     error(obj: object, msg?: string): void;
 }
+export interface RequestContext {
+    /** The caller's own key for the upstream API. Set when `apiKey` is configured. */
+    apiKey?: string;
+}
+export interface ApiKeyOptions {
+    /** Added to the 401 message, e.g. where to get a key. */
+    hint?: string;
+}
 export interface McpHttpOptions {
     /** Builds a fresh server per request; the transport is stateless. */
-    createMcpServer: () => McpServer;
+    createMcpServer: (context: RequestContext) => McpServer | Promise<McpServer>;
     port: number;
     /** Interface to listen on. Default `0.0.0.0`. */
     host?: string;
-    /** Prefix a proxy leaves on the path, e.g. `/ns`. Both `/mcp` and `<basePath>/mcp` are served. */
+    /** Prefix a proxy leaves on the path, e.g. `/ns`. MCP is served on `/mcp`, `<basePath>/mcp` and `<basePath>` itself. */
     basePath?: string;
     /** Readiness for `/healthz`; return false for a 503. Default: always ready. */
     health?: () => boolean | Promise<boolean>;
+    /** Require every MCP request to carry the caller's key in `X-Api-Key` or `Authorization: Bearer`. */
+    apiKey?: ApiKeyOptions;
     logger?: Logger;
 }
 export interface McpHttpServer {

package/dist/server.js

@@ -1,6 +1,23 @@
 import { createServer } from 'node:http';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import { createMcpHandler } from '@modelcontextprotocol/server';
 const silent = { error: () => { } };
+// PKG-10: Node's `Server.close()` waits for every still-open connection to go
+// idle on its own; a keep-alive client that goes idle (or stays busy) *after*
+// close() has already fired its one-off `closeIdleConnections()` call is
+// never swept again, so the returned promise would never settle. We sweep
+// idle connections repeatedly and, as a last resort, force every remaining
+// connection closed after a fixed grace period - allowing in-flight requests
+// a chance to finish first. 5000ms mirrors `DEFAULT_CONNECTION_TIMEOUT_MS` in
+// packages/drizzle/src/client.ts and stays well under the grace period an
+// orchestrator (Dokploy/k8s) gives a process before SIGKILL (typically
+// 10-30s). packages/drizzle/src/client.ts's closeDb() has its own, longer
+// CLOSE_TIMEOUT_MS backstop for the same class of problem (PKG-18); the two
+// are chosen independently, since a stuck DB client and a stuck HTTP
+// keep-alive socket have different acceptable wait times. This is
+// intentionally internal and not exposed on `McpHttpOptions`.
+const FORCE_CLOSE_TIMEOUT_MS = 5000;
+const IDLE_SWEEP_INTERVAL_MS = 250;
 function normalizeBasePath(basePath = '') {
     const trimmed = basePath.replace(/\/+$/, '');
     if (!trimmed)
@@ -18,29 +35,84 @@ function jsonRpcError(res, status, message) {
         id: null
     });
 }
+function apiKeyFrom(req) {
+    const header = req.headers['x-api-key'];
+    const direct = (Array.isArray(header) ? header[0] : header)?.trim();
+    if (direct)
+        return direct;
+    const bearer = /^Bearer\s+(.+)$/i.exec(req.headers.authorization ?? '');
+    return bearer?.[1]?.trim() || undefined;
+}
+// PKG-10: closes `http`, letting in-flight requests finish normally. A
+// one-off `closeIdleConnections()` call only catches connections that are
+// already idle at the exact moment close() runs; any connection that is
+// still mid-request at that moment, and only goes idle afterwards, would
+// otherwise never be swept, so we repeat the sweep on an interval instead. If
+// connections are still open once FORCE_CLOSE_TIMEOUT_MS has passed - e.g. a
+// keep-alive client that never goes idle - `closeAllConnections()`
+// force-closes whatever remains so the returned promise always settles and
+// the port is always released. Both timers are unref'd and are always
+// cleared once `http`'s own close callback fires, on every path (success,
+// forced, or error).
+function closeHttpServer(http) {
+    return new Promise((resolve, reject) => {
+        const sweep = setInterval(() => {
+            http.closeIdleConnections();
+        }, IDLE_SWEEP_INTERVAL_MS).unref();
+        const forceExit = setTimeout(() => {
+            http.closeAllConnections();
+        }, FORCE_CLOSE_TIMEOUT_MS).unref();
+        http.close((error) => {
+            clearInterval(sweep);
+            clearTimeout(forceExit);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+        http.closeIdleConnections();
+    });
+}
 export async function startMcpHttpServer(options) {
     const logger = options.logger ?? silent;
     const base = normalizeBasePath(options.basePath);
     const mcpPaths = new Set([`${base}/mcp`, '/mcp']);
+    if (base)
+        mcpPaths.add(base);
     const healthPaths = new Set([`${base}/healthz`, '/healthz']);
+    // The key travels as pass-through authInfo, the SDK's channel from the
+    // HTTP request to the per-request factory.
+    const mcpHandler = createMcpHandler(({ authInfo }) => options.createMcpServer(authInfo ? { apiKey: authInfo.token } : {}), {
+        onerror: (error) => {
+            logger.error({ err: String(error) }, 'mcp request failed');
+        }
+    });
+    const nodeHandler = toNodeHandler(mcpHandler, {
+        onerror: (error) => {
+            logger.error({ err: String(error) }, 'mcp request failed');
+        }
+    });
     async function handleMcp(req, res) {
-        // Stateless mode has no session to attach a GET stream or a DELETE to.
+        // Stateless serving has no session to attach a GET stream or a DELETE to.
         if (req.method !== 'POST') {
             res.setHeader('allow', 'POST');
             jsonRpcError(res, 405, 'Method not allowed');
             return;
         }
-        const server = options.createMcpServer();
-        const transport = new StreamableHTTPServerTransport({
-            sessionIdGenerator: undefined,
-            enableJsonResponse: true
-        });
-        res.on('close', () => {
-            void transport.close();
-            void server.close();
-        });
-        await server.connect(transport);
-        await transport.handleRequest(req, res);
+        if (!options.apiKey) {
+            await nodeHandler(req, res);
+            return;
+        }
+        const apiKey = apiKeyFrom(req);
+        if (!apiKey) {
+            const hint = options.apiKey.hint ? ` ${options.apiKey.hint}` : '';
+            res.setHeader('www-authenticate', 'Bearer');
+            jsonRpcError(res, 401, `Missing API key: send it in the X-Api-Key header or as Authorization: Bearer <key>.${hint}`);
+            return;
+        }
+        await nodeHandler(Object.assign(req, {
+            auth: { token: apiKey, clientId: 'api-key', scopes: [] }
+        }), res);
     }
     async function handle(req, res) {
         const path = new URL(req.url ?? '/', 'http://localhost').pathname;
@@ -78,9 +150,9 @@ export async function startMcpHttpServer(options) {
     return {
         url: `http://${shownHost}:${String(port)}${base}/mcp`,
         port,
-        close: () => new Promise((resolve, reject) => {
-            http.close((error) => (error ? reject(error) : resolve()));
-            http.closeIdleConnections();
-        })
+        close: async () => {
+            await closeHttpServer(http);
+            await mcpHandler.close();
+        }
     };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ultimatelemon-eu/mcp-http",
-  "version": "1.0.0",
-  "description": "Run an MCP server over stateless Streamable HTTP: /mcp, /healthz, a base path for proxies, and errors that never leak a stack trace.",
+  "version": "2.1.0",
+  "description": "Run an MCP server over stateless Streamable HTTP: /mcp, /healthz, a base path for proxies, the caller's own API key per request, and errors that never leak a stack trace.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,16 +26,20 @@
     "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
-  "peerDependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.0"
-  },
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@modelcontextprotocol/node": "^2.1.1",
+    "@modelcontextprotocol/server": "^2.3.1",
     "@types/node": "^24.19.1",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.1",
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/node": "^2.1.0",
+    "@modelcontextprotocol/server": "^2.3.0"
   }
 }