@ttoss/http-server-mcp 0.17.1 → 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

@@ -190,6 +190,7 @@ var checkScopes = required => {
 var createMcpRouter = (server, options = {}) => {
   const {
     path = "/mcp",
+    aliases = [],
     sessionIdGenerator,
     apiBaseUrl,
     getApiHeaders,
@@ -214,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);
@@ -227,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) : {};
@@ -276,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) {
@@ -287,8 +293,8 @@ var createMcpRouter = (server, options = {}) => {
         };
       }
     }
-  });
-  router.delete(path, async ctx => {
+  };
+  const deleteHandler = async ctx => {
     try {
       await handleWithContext(ctx);
     } catch (error) {
@@ -299,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

@@ -819,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

@@ -819,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

@@ -187,6 +187,7 @@ var checkScopes = required => {
 var createMcpRouter = (server, options = {}) => {
   const {
     path = "/mcp",
+    aliases = [],
     sessionIdGenerator,
     apiBaseUrl,
     getApiHeaders,
@@ -211,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);
@@ -224,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) : {};
@@ -273,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) {
@@ -284,8 +290,8 @@ var createMcpRouter = (server, options = {}) => {
         };
       }
     }
-  });
-  router.delete(path, async ctx => {
+  };
+  const deleteHandler = async ctx => {
     try {
       await handleWithContext(ctx);
     } catch (error) {
@@ -296,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.1",
+  "version": "0.18.0",
   "description": "Model Context Protocol (MCP) server integration for @ttoss/http-server",
   "keywords": [
     "ai",