@ttoss/http-server-mcp 0.17.0 → 0.18.0

package/README.md

@@ -279,6 +279,8 @@ createMcpRouter(mcpServer, {
 });
 ```
 
+The `resource` field in the metadata document is automatically set to `resourceServerUrl + path` (e.g. `https://mcp.example.com/mcp` for the default path). This means MCP clients that follow `resource` to connect will land on the actual MCP endpoint rather than the bare origin.
+
 **With your own auth middleware** — use `createProtectedResourceMetadataMiddleware` as a standalone middleware, mounted _before_ your auth layer so discovery stays unauthenticated:
 
 ```typescript
@@ -340,6 +342,26 @@ createMcpRouter(mcpServer, {
 
 Both fields are optional. Omitting `resourceMetadataUrl` keeps the bare `Bearer` header, and the `publicMethods` default matches what MCP clients expect for discovery.
 
+### Supporting clients that connect to the bare origin
+
+Some MCP clients always POST to the bare origin (`/`) regardless of the `resource` value in the metadata. To serve both behaviors from the same router, use the `aliases` option:
+
+```typescript
+createMcpRouter(mcpServer, {
+  // The primary endpoint — also the value advertised as `resource` in metadata.
+  path: '/mcp',
+  // Additionally handle requests at the bare root for clients that ignore `resource`.
+  aliases: ['/'],
+  auth: {
+    verifyToken: async (token) => myVerify(token),
+    resourceServerUrl: 'https://mcp.example.com',
+    authorizationServerUrl: 'https://auth.example.com',
+  },
+});
+```
+
+The discovery endpoint (`/.well-known/oauth-protected-resource`) remains publicly accessible even when `aliases` includes `'/'`.
+
 ## Issuing tokens for MCP clients
 
 The `auth` option above covers the **resource-server** half of MCP authorization — it verifies tokens issued by an external authorization server (Cognito, Auth0, …). To make your own first-party server _issue_ the tokens an MCP client runs the full OAuth flow against, add the [`@ttoss/http-server-auth`](https://ttoss.dev/docs/modules/packages/http-server-auth) plugin's `oauthServer()` and pair it with `createMcpRouter({ auth: { verifyToken } })` so one deployment both issues and verifies tokens. See the [OAuth Authorization Server](https://ttoss.dev/docs/engineering/guidelines/oauth-authorization-server) guideline.
@@ -355,6 +377,7 @@ Creates a Koa router configured to handle MCP protocol requests.
 - `server` (`McpServer`) — MCP server instance with registered tools and resources
 - `options` (`McpRouterOptions`) — Optional configuration
   - `path` (`string`) — HTTP path for MCP endpoint (default: `'/mcp'`)
+  - `aliases` (`string[]`) — Additional paths where the MCP handler is also mounted; use `['/']` to also handle requests at the bare root (default: `[]`)
   - `sessionIdGenerator` (`() => string`) — Session ID generator for stateful servers (default: `undefined` for stateless)
   - `apiBaseUrl` (`string`) — Base URL prepended to relative paths in `apiCall`
   - `getApiHeaders` (`(ctx: Context) => Record<string, string>`) — Return headers to inject into every `apiCall` for this request
@@ -362,7 +385,7 @@ Creates a Koa router configured to handle MCP protocol requests.
     - `auth.cognitoUserPool` — Cognito user pool config (`userPoolId`, `clientId`, `tokenUse`)
     - `auth.verifyToken` — Custom async token verifier `(token: string) => Promise<unknown>`
     - `auth.requiredScopes` — Router-level scope guard; returns 403 if any scope is missing
-    - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable `/.well-known/oauth-protected-resource`
+    - `auth.resourceServerUrl` + `auth.authorizationServerUrl` — Enable `/.well-known/oauth-protected-resource`; the metadata `resource` is set to `resourceServerUrl + path` so clients following `resource` land on the actual MCP endpoint
     - `auth.publicMethods` — JSON-RPC methods that bypass verification (default `['initialize', 'tools/list']`)
     - `auth.resourceMetadataUrl` — Emit RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` on 401
 

package/dist/index.cjs

@@ -126,7 +126,9 @@ var getIdentity = () => {
 * Throws if any scope is missing — the MCP SDK catches this and returns a
 * tool error to the client. Use inside tool handlers for per-tool authorization.
 *
-* Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+* Accepts either `scope: string` (space-separated, standard JWT claim) or
+* `scopes: string[]` from `verifyToken`. If neither is present and `required`
+* is non-empty, throws with a descriptive message instead of a silent 403.
 *
 * @example
 * ```typescript
@@ -137,7 +139,13 @@ var getIdentity = () => {
 * ```
 */
 var checkScopes = required => {
-  const tokenScopes = (getIdentity()?.scope ?? "").split(" ");
+  const identity = getIdentity();
+  let scopeString = null;
+  if (typeof identity?.scope === "string") scopeString = identity.scope;else if (Array.isArray(identity?.scopes) && identity.scopes.every(s => {
+    return typeof s === "string";
+  })) scopeString = identity.scopes.join(" ");
+  if (scopeString === null && required.length > 0) throw new Error(`verifyToken returned no scope/scopes but requiredScopes is set (${required.join(", ")}). Return either scope: string or scopes: string[] from verifyToken.`);
+  const tokenScopes = scopeString ? scopeString.split(" ") : [];
   if (required.filter(s => {
     return !tokenScopes.includes(s);
   }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);
@@ -182,6 +190,7 @@ var checkScopes = required => {
 var createMcpRouter = (server, options = {}) => {
   const {
     path = "/mcp",
+    aliases = [],
     sessionIdGenerator,
     apiBaseUrl,
     getApiHeaders,
@@ -206,6 +215,7 @@ var createMcpRouter = (server, options = {}) => {
     return result;
   };
   const router = new _ttoss_http_server.Router();
+  let authCheck;
   if (auth) {
     const verifyToken = buildVerifyToken(auth);
     const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
@@ -219,20 +229,24 @@ var createMcpRouter = (server, options = {}) => {
       },
       resourceMetadataUrl: auth.resourceMetadataUrl
     });
-    router.use(path, async (ctx, next) => {
+    authCheck = async (ctx, next) => {
       const method = ctx.request.body?.method;
       if (publicMethods.has(method ?? "")) {
         await next();
         return;
       }
       await verify(ctx, next);
-    });
-    if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
-      ctx.body = {
-        resource: auth.resourceServerUrl,
-        authorization_servers: [auth.authorizationServerUrl]
-      };
-    });
+    };
+    if (auth.resourceServerUrl && auth.authorizationServerUrl) {
+      const base = auth.resourceServerUrl.replace(/\/$/, "");
+      const resourceUrl = path === "/" ? base : `${base}${path}`;
+      router.get("/.well-known/oauth-protected-resource", ctx => {
+        ctx.body = {
+          resource: resourceUrl,
+          authorization_servers: [auth.authorizationServerUrl]
+        };
+      });
+    }
   }
   const handleWithContext = async (ctx, body) => {
     const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
@@ -268,7 +282,7 @@ var createMcpRouter = (server, options = {}) => {
       }
     });
   };
-  router.post(path, async ctx => {
+  const postHandler = async ctx => {
     try {
       await handleWithContext(ctx, ctx.request.body);
     } catch (error) {
@@ -279,8 +293,8 @@ var createMcpRouter = (server, options = {}) => {
         };
       }
     }
-  });
-  router.delete(path, async ctx => {
+  };
+  const deleteHandler = async ctx => {
     try {
       await handleWithContext(ctx);
     } catch (error) {
@@ -291,7 +305,15 @@ var createMcpRouter = (server, options = {}) => {
         };
       }
     }
-  });
+  };
+  const allPaths = [path, ...aliases];
+  for (const mcpPath of allPaths) if (authCheck) {
+    router.post(mcpPath, authCheck, postHandler);
+    router.delete(mcpPath, authCheck, deleteHandler);
+  } else {
+    router.post(mcpPath, postHandler);
+    router.delete(mcpPath, deleteHandler);
+  }
   return router;
 };
 var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();

package/dist/index.d.cts

@@ -692,7 +692,11 @@ interface McpAuthOptions {
    * JWTs, opaque tokens). Resolve with the verified payload, or throw to reject.
    */
   verifyToken?: (token: string) => Promise<unknown>;
-  /** Scopes that must all be present on the token's `scope` claim, else `403`. */
+  /**
+   * Scopes that must all be present on the token, else `403`.
+   * `verifyToken` may return either `scope: string` (space-separated) or
+   * `scopes: string[]`; both are normalised internally.
+   */
   requiredScopes?: string[];
   /**
    * JSON-RPC methods (read from `body.method`) that bypass verification.
@@ -793,7 +797,9 @@ declare const getIdentity: () => unknown;
  * Throws if any scope is missing — the MCP SDK catches this and returns a
  * tool error to the client. Use inside tool handlers for per-tool authorization.
  *
- * Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+ * Accepts either `scope: string` (space-separated, standard JWT claim) or
+ * `scopes: string[]` from `verifyToken`. If neither is present and `required`
+ * is non-empty, throws with a descriptive message instead of a silent 403.
  *
  * @example
  * ```typescript
@@ -813,6 +819,17 @@ interface McpRouterOptions {
    * @default '/mcp'
    */
   path?: string;
+  /**
+   * Additional HTTP paths where the MCP server is also mounted.
+   *
+   * Useful when MCP clients differ in where they connect after OAuth: some
+   * follow the protected-resource `resource` metadata value as the endpoint,
+   * others always connect to the bare origin (`/`). Setting `aliases: ['/']`
+   * serves both without requiring app-level path rewrites.
+   *
+   * @example ['/'] // also handle MCP requests at the bare root
+   */
+  aliases?: string[];
   /**
    * Optional session ID generator for stateful MCP servers.
    * When provided, a single shared transport is created and sessions are tracked.

package/dist/index.d.mts

@@ -692,7 +692,11 @@ interface McpAuthOptions {
    * JWTs, opaque tokens). Resolve with the verified payload, or throw to reject.
    */
   verifyToken?: (token: string) => Promise<unknown>;
-  /** Scopes that must all be present on the token's `scope` claim, else `403`. */
+  /**
+   * Scopes that must all be present on the token, else `403`.
+   * `verifyToken` may return either `scope: string` (space-separated) or
+   * `scopes: string[]`; both are normalised internally.
+   */
   requiredScopes?: string[];
   /**
    * JSON-RPC methods (read from `body.method`) that bypass verification.
@@ -793,7 +797,9 @@ declare const getIdentity: () => unknown;
  * Throws if any scope is missing — the MCP SDK catches this and returns a
  * tool error to the client. Use inside tool handlers for per-tool authorization.
  *
- * Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+ * Accepts either `scope: string` (space-separated, standard JWT claim) or
+ * `scopes: string[]` from `verifyToken`. If neither is present and `required`
+ * is non-empty, throws with a descriptive message instead of a silent 403.
  *
  * @example
  * ```typescript
@@ -813,6 +819,17 @@ interface McpRouterOptions {
    * @default '/mcp'
    */
   path?: string;
+  /**
+   * Additional HTTP paths where the MCP server is also mounted.
+   *
+   * Useful when MCP clients differ in where they connect after OAuth: some
+   * follow the protected-resource `resource` metadata value as the endpoint,
+   * others always connect to the bare origin (`/`). Setting `aliases: ['/']`
+   * serves both without requiring app-level path rewrites.
+   *
+   * @example ['/'] // also handle MCP requests at the bare root
+   */
+  aliases?: string[];
   /**
    * Optional session ID generator for stateful MCP servers.
    * When provided, a single shared transport is created and sessions are tracked.

package/dist/index.mjs

@@ -123,7 +123,9 @@ var getIdentity = () => {
 * Throws if any scope is missing — the MCP SDK catches this and returns a
 * tool error to the client. Use inside tool handlers for per-tool authorization.
 *
-* Cognito tokens carry scopes as a space-separated string in `payload.scope`.
+* Accepts either `scope: string` (space-separated, standard JWT claim) or
+* `scopes: string[]` from `verifyToken`. If neither is present and `required`
+* is non-empty, throws with a descriptive message instead of a silent 403.
 *
 * @example
 * ```typescript
@@ -134,7 +136,13 @@ var getIdentity = () => {
 * ```
 */
 var checkScopes = required => {
-  const tokenScopes = (getIdentity()?.scope ?? "").split(" ");
+  const identity = getIdentity();
+  let scopeString = null;
+  if (typeof identity?.scope === "string") scopeString = identity.scope;else if (Array.isArray(identity?.scopes) && identity.scopes.every(s => {
+    return typeof s === "string";
+  })) scopeString = identity.scopes.join(" ");
+  if (scopeString === null && required.length > 0) throw new Error(`verifyToken returned no scope/scopes but requiredScopes is set (${required.join(", ")}). Return either scope: string or scopes: string[] from verifyToken.`);
+  const tokenScopes = scopeString ? scopeString.split(" ") : [];
   if (required.filter(s => {
     return !tokenScopes.includes(s);
   }).length > 0) throw new Error(`Insufficient scopes. Required: ${required.join(", ")}`);
@@ -179,6 +187,7 @@ var checkScopes = required => {
 var createMcpRouter = (server, options = {}) => {
   const {
     path = "/mcp",
+    aliases = [],
     sessionIdGenerator,
     apiBaseUrl,
     getApiHeaders,
@@ -203,6 +212,7 @@ var createMcpRouter = (server, options = {}) => {
     return result;
   };
   const router = new Router();
+  let authCheck;
   if (auth) {
     const verifyToken = buildVerifyToken(auth);
     const publicMethods = new Set(auth.publicMethods ?? DEFAULT_PUBLIC_METHODS);
@@ -216,20 +226,24 @@ var createMcpRouter = (server, options = {}) => {
       },
       resourceMetadataUrl: auth.resourceMetadataUrl
     });
-    router.use(path, async (ctx, next) => {
+    authCheck = async (ctx, next) => {
       const method = ctx.request.body?.method;
       if (publicMethods.has(method ?? "")) {
         await next();
         return;
       }
       await verify(ctx, next);
-    });
-    if (auth.resourceServerUrl && auth.authorizationServerUrl) router.get("/.well-known/oauth-protected-resource", ctx => {
-      ctx.body = {
-        resource: auth.resourceServerUrl,
-        authorization_servers: [auth.authorizationServerUrl]
-      };
-    });
+    };
+    if (auth.resourceServerUrl && auth.authorizationServerUrl) {
+      const base = auth.resourceServerUrl.replace(/\/$/, "");
+      const resourceUrl = path === "/" ? base : `${base}${path}`;
+      router.get("/.well-known/oauth-protected-resource", ctx => {
+        ctx.body = {
+          resource: resourceUrl,
+          authorization_servers: [auth.authorizationServerUrl]
+        };
+      });
+    }
   }
   const handleWithContext = async (ctx, body) => {
     const apiHeaders = getApiHeaders ? getApiHeaders(ctx) : {};
@@ -265,7 +279,7 @@ var createMcpRouter = (server, options = {}) => {
       }
     });
   };
-  router.post(path, async ctx => {
+  const postHandler = async ctx => {
     try {
       await handleWithContext(ctx, ctx.request.body);
     } catch (error) {
@@ -276,8 +290,8 @@ var createMcpRouter = (server, options = {}) => {
         };
       }
     }
-  });
-  router.delete(path, async ctx => {
+  };
+  const deleteHandler = async ctx => {
     try {
       await handleWithContext(ctx);
     } catch (error) {
@@ -288,7 +302,15 @@ var createMcpRouter = (server, options = {}) => {
         };
       }
     }
-  });
+  };
+  const allPaths = [path, ...aliases];
+  for (const mcpPath of allPaths) if (authCheck) {
+    router.post(mcpPath, authCheck, postHandler);
+    router.delete(mcpPath, authCheck, deleteHandler);
+  } else {
+    router.post(mcpPath, postHandler);
+    router.delete(mcpPath, deleteHandler);
+  }
   return router;
 };
 var rawSchemaRegistryMap = /* @__PURE__ */new WeakMap();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ttoss/http-server-mcp",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",
@@ -36,8 +36,8 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.4.3",
     "@ttoss/auth-core": "^0.7.0",
-    "@ttoss/http-server": "^0.7.1",
-    "@ttoss/http-server-auth": "^0.3.3"
+    "@ttoss/http-server-auth": "^0.3.4",
+    "@ttoss/http-server": "^0.7.1"
   },
   "devDependencies": {
     "@types/koa": "^3.0.3",