@ultimatelemon-eu/mcp-http 2.3.1 → 2.4.0

package/README.md

@@ -42,7 +42,7 @@ process.once('SIGTERM', () => {
 | `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                  |
+| `apiKey`          | off         | Require the caller's key; `hint` is added to the 401, `verify` checks it      |
 | `oauth`           | off         | Let callers sign in with the upstream service; see [OAuth](#oauth)            |
 | `logger`          | silent      | Anything with `error(obj, msg)`, such as pino                                 |
 
@@ -57,6 +57,15 @@ before building an MCP server. The key reaches `createMcpServer` as
 `apiKey`; it is never logged or stored. Other per-caller settings can travel
 as headers of their own, read from `headers` in the same context.
 
+When the server hands out keys itself, `verify` checks one before any MCP
+work: return `false` and the caller gets a 401 with `error="invalid_token"`.
+
+```ts
+apiKey: {
+  verify: (key) => findUserByToken(key) !== undefined;
+}
+```
+
 This suits public servers where each user brings their own credentials: no
 sessions, no database. In claude.ai, add the connector with
 "No sign-in" and the key as a request header.

package/dist/oauth.js

@@ -9,7 +9,7 @@ const UPSTREAM_LEEWAY_MS = 5 * 60 * 1000;
 const COOKIE = 'mcp_oauth_state';
 function sealer(issuer) {
     return {
-        seal(value, ttlMs) {
+        seal: (value, ttlMs) => {
             const sealed = {
                 ...value,
                 i: issuer,
@@ -17,7 +17,7 @@ function sealer(issuer) {
             };
             return encrypt(JSON.stringify(sealed));
         },
-        open(value, type) {
+        open: (value, type) => {
             if (!value || !isEncrypted(value))
                 return undefined;
             try {

package/dist/server.d.ts

@@ -17,6 +17,8 @@ export interface RequestContext {
 export interface ApiKeyOptions {
     /** Added to the 401 message, e.g. where to get a key. */
     hint?: string;
+    /** For keys this server issued itself: return false to answer 401 before building a server. */
+    verify?: (key: string) => boolean | Promise<boolean>;
 }
 export interface McpHttpOptions {
     /** Builds a fresh server per request; the transport is stateless. */

package/dist/server.js

@@ -175,14 +175,19 @@ export async function startMcpHttpServer(options) {
             return;
         }
         const apiKey = options.apiKey ? (headerKey(req) ?? bearer) : undefined;
+        const hint = options.apiKey?.hint ? ` ${options.apiKey.hint}` : '';
         if (!apiKey) {
-            const hint = options.apiKey?.hint ? ` ${options.apiKey.hint}` : '';
             res.setHeader('www-authenticate', oauth ? oauth.challenge() : 'Bearer');
             jsonRpcError(res, 401, options.apiKey
                 ? `Missing API key: send it in the X-Api-Key header or as Authorization: Bearer <key>.${hint}`
                 : 'Sign in to use this server.');
             return;
         }
+        if (options.apiKey?.verify && !(await options.apiKey.verify(apiKey))) {
+            res.setHeader('www-authenticate', 'Bearer error="invalid_token"');
+            jsonRpcError(res, 401, `The API key is not valid.${hint}`);
+            return;
+        }
         await nodeHandler(Object.assign(req, {
             auth: { token: apiKey, clientId: 'api-key', scopes: [] }
         }), res);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimatelemon-eu/mcp-http",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Run an MCP server over stateless Streamable HTTP: /mcp, /healthz, a base path for proxies, the caller's own API key or a stateless OAuth sign-in, and errors that never leak a stack trace.",
   "license": "MIT",
   "repository": {