fastmcp 4.3.1 → 4.4.0

package/README.md

@@ -139,6 +139,8 @@ This will start the server and listen for HTTP streaming connections on `http://
 
 > **Note:** You can also customize the endpoint path using the `httpStream.endpoint` option (default is `/mcp`).
 
+> **Note:** To serve HTTP streaming and built-in OAuth routes under an issuer path, set `httpStream.basePath` (for example, `/issuer1`). This exposes authorization server metadata at `/.well-known/oauth-authorization-server/issuer1` per RFC 8414.
+
 > **Note:** This also starts an SSE server on `http://localhost:8080/sse`.
 
 You can connect to these servers using the appropriate client transport.
@@ -1923,9 +1925,29 @@ const server = new FastMCP({
 });
 ```
 
+If your MCP server is published below an issuer path, configure the HTTP
+stream base path as well:
+
+```ts
+server.start({
+  transportType: "httpStream",
+  httpStream: {
+    basePath: "/issuer1",
+    endpoint: "/mcp",
+    port: 8080,
+  },
+});
+```
+
+With this configuration, FastMCP serves the issuer-path authorization server
+metadata at `/.well-known/oauth-authorization-server/issuer1`, while protected
+resource metadata remains available for the MCP endpoint at
+`/.well-known/oauth-protected-resource/issuer1/mcp`.
+
 This configuration automatically exposes OAuth discovery endpoints:
 
 - `/.well-known/oauth-authorization-server` - Authorization server metadata (RFC 8414)
+- `/.well-known/oauth-authorization-server<basePath>` - Authorization server metadata when `httpStream.basePath` is set (RFC 8414 Section 3)
 - `/.well-known/oauth-protected-resource` - Protected resource metadata (RFC 9728)
 - `/.well-known/oauth-protected-resource<endpoint>` - Protected resource metadata at sub-path (MCP 2025-11-25)
 

package/dist/FastMCP.cjs

@@ -7,7 +7,7 @@
 
 
 
-var _chunkRPY6M6HDcjs = require('./chunk-RPY6M6HD.cjs');
+var _chunk3YTRRGCEcjs = require('./chunk-3YTRRGCE.cjs');
 
 
 
@@ -41,5 +41,5 @@ var _chunkIX3HKAX4cjs = require('./chunk-IX3HKAX4.cjs');
 
 
 
-exports.AuthProvider = _chunkIX3HKAX4cjs.AuthProvider; exports.AzureProvider = _chunkIX3HKAX4cjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkRPY6M6HDcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkRPY6M6HDcjs.FastMCP; exports.FastMCPSession = _chunkRPY6M6HDcjs.FastMCPSession; exports.GitHubProvider = _chunkIX3HKAX4cjs.GitHubProvider; exports.GoogleProvider = _chunkIX3HKAX4cjs.GoogleProvider; exports.OAuthProvider = _chunkIX3HKAX4cjs.OAuthProvider; exports.ServerState = _chunkRPY6M6HDcjs.ServerState; exports.UnexpectedStateError = _chunkRPY6M6HDcjs.UnexpectedStateError; exports.UserError = _chunkRPY6M6HDcjs.UserError; exports.audioContent = _chunkRPY6M6HDcjs.audioContent; exports.getAuthSession = _chunkIX3HKAX4cjs.getAuthSession; exports.imageContent = _chunkRPY6M6HDcjs.imageContent; exports.requireAll = _chunkIX3HKAX4cjs.requireAll; exports.requireAny = _chunkIX3HKAX4cjs.requireAny; exports.requireAuth = _chunkIX3HKAX4cjs.requireAuth; exports.requireRole = _chunkIX3HKAX4cjs.requireRole; exports.requireScopes = _chunkIX3HKAX4cjs.requireScopes;
+exports.AuthProvider = _chunkIX3HKAX4cjs.AuthProvider; exports.AzureProvider = _chunkIX3HKAX4cjs.AzureProvider; exports.DiscoveryDocumentCache = _chunk3YTRRGCEcjs.DiscoveryDocumentCache; exports.FastMCP = _chunk3YTRRGCEcjs.FastMCP; exports.FastMCPSession = _chunk3YTRRGCEcjs.FastMCPSession; exports.GitHubProvider = _chunkIX3HKAX4cjs.GitHubProvider; exports.GoogleProvider = _chunkIX3HKAX4cjs.GoogleProvider; exports.OAuthProvider = _chunkIX3HKAX4cjs.OAuthProvider; exports.ServerState = _chunk3YTRRGCEcjs.ServerState; exports.UnexpectedStateError = _chunk3YTRRGCEcjs.UnexpectedStateError; exports.UserError = _chunk3YTRRGCEcjs.UserError; exports.audioContent = _chunk3YTRRGCEcjs.audioContent; exports.getAuthSession = _chunkIX3HKAX4cjs.getAuthSession; exports.imageContent = _chunk3YTRRGCEcjs.imageContent; exports.requireAll = _chunkIX3HKAX4cjs.requireAll; exports.requireAny = _chunkIX3HKAX4cjs.requireAny; exports.requireAuth = _chunkIX3HKAX4cjs.requireAuth; exports.requireRole = _chunkIX3HKAX4cjs.requireRole; exports.requireScopes = _chunkIX3HKAX4cjs.requireScopes;
 //# sourceMappingURL=FastMCP.cjs.map

package/dist/FastMCP.d.cts

@@ -861,6 +861,7 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
      */
     start(options?: Partial<{
         httpStream: {
+            basePath?: `/${string}`;
             cors?: boolean | CorsOptions;
             enableJsonResponse?: boolean;
             endpoint?: `/${string}`;

package/dist/FastMCP.d.ts

@@ -861,6 +861,7 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
      */
     start(options?: Partial<{
         httpStream: {
+            basePath?: `/${string}`;
             cors?: boolean | CorsOptions;
             enableJsonResponse?: boolean;
             endpoint?: `/${string}`;

package/dist/FastMCP.js

@@ -7,7 +7,7 @@ import {
   UserError,
   audioContent,
   imageContent
-} from "./chunk-KFZGSERX.js";
+} from "./chunk-MDIESGNI.js";
 import {
   AuthProvider,
   AzureProvider,

package/dist/{chunk-RPY6M6HD.cjs → chunk-3YTRRGCE.cjs}

@@ -1044,6 +1044,9 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
       let result;
       try {
         const reportProgress = async (progress) => {
+          if (progressToken === void 0) {
+            return;
+          }
           try {
             await this.#server.notification({
               method: "notifications/progress",
@@ -1227,6 +1230,20 @@ function convertObjectToSnakeCase(obj) {
   }
   return result;
 }
+function joinPaths(basePath, path) {
+  return `${basePath}${normalizePath(path)}`;
+}
+function normalizeBasePath(path) {
+  if (!path || path === "/") {
+    return "";
+  }
+  const withLeadingSlash = path.startsWith("/") ? path : `/${path}`;
+  const withoutTrailingSlash = withLeadingSlash.replace(/\/+$/, "");
+  return withoutTrailingSlash ? withoutTrailingSlash : "";
+}
+function normalizePath(path) {
+  return path.startsWith("/") ? path : `/${path}`;
+}
 function parseBasicAuthHeader(authHeader) {
   const basicMatch = _optionalChain([authHeader, 'optionalAccess', _25 => _25.match, 'call', _26 => _26(/^Basic\s+(.+)$/)]);
   if (!basicMatch) return null;
@@ -1239,6 +1256,18 @@ function parseBasicAuthHeader(authHeader) {
     return null;
   }
 }
+function stripBasePath(path, basePath) {
+  if (!basePath) {
+    return path;
+  }
+  if (path === basePath) {
+    return "/";
+  }
+  if (path.startsWith(`${basePath}/`)) {
+    return path.slice(basePath.length);
+  }
+  return null;
+}
 var FastMCPEventEmitterBase = _events.EventEmitter;
 var FastMCPEventEmitter = class extends FastMCPEventEmitterBase {
 };
@@ -1593,9 +1622,13 @@ var FastMCP = class extends FastMCPEventEmitter {
     } else if (config.transportType === "httpStream") {
       const httpConfig = config.httpStream;
       const protocol = httpConfig.sslCert || httpConfig.sslKey ? "https" : "http";
+      const streamEndpoint = joinPaths(
+        httpConfig.basePath,
+        httpConfig.endpoint
+      );
       if (httpConfig.stateless) {
         this.#logger.info(
-          `[FastMCP info] Starting server in stateless mode on HTTP Stream at ${protocol}://${httpConfig.host}:${httpConfig.port}${httpConfig.endpoint}`
+          `[FastMCP info] Starting server in stateless mode on HTTP Stream at ${protocol}://${httpConfig.host}:${httpConfig.port}${streamEndpoint}`
         );
         this.#httpStreamServer = await _mcpproxy.startHTTPServer.call(void 0, {
           ...this.#authenticate ? { authenticate: this.#authenticate } : {},
@@ -1635,7 +1668,8 @@ var FastMCP = class extends FastMCPEventEmitter {
               res,
               true,
               httpConfig.host,
-              httpConfig.endpoint
+              streamEndpoint,
+              httpConfig.basePath
             );
           },
           port: httpConfig.port,
@@ -1643,7 +1677,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           sslCert: httpConfig.sslCert,
           sslKey: httpConfig.sslKey,
           stateless: true,
-          streamEndpoint: httpConfig.endpoint
+          streamEndpoint
         });
       } else {
         this.#httpStreamServer = await _mcpproxy.startHTTPServer.call(void 0, {
@@ -1687,7 +1721,8 @@ var FastMCP = class extends FastMCPEventEmitter {
               res,
               false,
               httpConfig.host,
-              httpConfig.endpoint
+              streamEndpoint,
+              httpConfig.basePath
             );
           },
           port: httpConfig.port,
@@ -1695,10 +1730,10 @@ var FastMCP = class extends FastMCPEventEmitter {
           sslCert: httpConfig.sslCert,
           sslKey: httpConfig.sslKey,
           stateless: httpConfig.stateless,
-          streamEndpoint: httpConfig.endpoint
+          streamEndpoint
         });
         this.#logger.info(
-          `[FastMCP info] server is running on HTTP Stream at ${protocol}://${httpConfig.host}:${httpConfig.port}${httpConfig.endpoint}`
+          `[FastMCP info] server is running on HTTP Stream at ${protocol}://${httpConfig.host}:${httpConfig.port}${streamEndpoint}`
         );
       }
       this.#serverState = "running" /* Running */;
@@ -1748,8 +1783,9 @@ var FastMCP = class extends FastMCPEventEmitter {
   /**
    * Handles unhandled HTTP requests with health, readiness, OAuth endpoints, and custom routes
    */
-  #handleUnhandledRequest = async (req, res, isStateless = false, host, streamEndpoint) => {
+  #handleUnhandledRequest = async (req, res, isStateless = false, host, streamEndpoint, basePath = "") => {
     const url = new URL(req.url || "", `http://${host}`);
+    const basePathRelativePath = stripBasePath(url.pathname, basePath);
     try {
       const webRequest = this.#nodeRequestToWebRequest(req, url);
       const honoResponse = await this.#honoApp.fetch(webRequest, {
@@ -1785,9 +1821,8 @@ var FastMCP = class extends FastMCPEventEmitter {
     const enabled = healthConfig.enabled === void 0 ? true : healthConfig.enabled;
     if (enabled) {
       const path = _nullishCoalesce(healthConfig.path, () => ( "/health"));
-      const url2 = new URL(req.url || "", `http://${host}`);
       try {
-        if ((req.method === "GET" || req.method === "HEAD") && url2.pathname === path) {
+        if ((req.method === "GET" || req.method === "HEAD") && url.pathname === joinPaths(basePath, path)) {
           res.writeHead(_nullishCoalesce(healthConfig.status, () => ( 200)), {
             "Content-Type": "text/plain"
           }).end(
@@ -1795,7 +1830,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           );
           return;
         }
-        if ((req.method === "GET" || req.method === "HEAD") && url2.pathname === "/ready") {
+        if ((req.method === "GET" || req.method === "HEAD") && url.pathname === joinPaths(basePath, "/ready")) {
           if (isStateless) {
             const response = {
               mode: "stateless",
@@ -1834,7 +1869,11 @@ var FastMCP = class extends FastMCPEventEmitter {
     const oauthConfig = this.#options.oauth;
     if (_optionalChain([oauthConfig, 'optionalAccess', _41 => _41.enabled]) && req.method === "GET") {
       const url2 = new URL(req.url || "", `http://${host}`);
-      if (url2.pathname === "/.well-known/oauth-authorization-server" && oauthConfig.authorizationServer) {
+      const authorizationServerMetadataPath = joinPaths(
+        "",
+        `/.well-known/oauth-authorization-server${basePath}`
+      );
+      if (url2.pathname === authorizationServerMetadataPath && oauthConfig.authorizationServer) {
         const metadata = convertObjectToSnakeCase(
           oauthConfig.authorizationServer
         );
@@ -1865,8 +1904,9 @@ var FastMCP = class extends FastMCPEventEmitter {
     const oauthProxy = _optionalChain([oauthConfig, 'optionalAccess', _42 => _42.proxy]);
     if (oauthProxy && _optionalChain([oauthConfig, 'optionalAccess', _43 => _43.enabled])) {
       const url2 = new URL(req.url || "", `http://${host}`);
+      const oauthPath = basePathRelativePath;
       try {
-        if (req.method === "POST" && url2.pathname === "/oauth/register") {
+        if (req.method === "POST" && oauthPath === "/oauth/register") {
           await new Promise((resolve) => {
             let body = "";
             req.on("data", (chunk) => body += chunk);
@@ -1890,7 +1930,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           });
           return;
         }
-        if (req.method === "GET" && url2.pathname === "/oauth/authorize") {
+        if (req.method === "GET" && oauthPath === "/oauth/authorize") {
           try {
             const params = Object.fromEntries(url2.searchParams.entries());
             const response = await oauthProxy.authorize(
@@ -1914,7 +1954,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           }
           return;
         }
-        if (req.method === "GET" && url2.pathname === "/oauth/callback") {
+        if (req.method === "GET" && oauthPath === "/oauth/callback") {
           try {
             const mockRequest = new Request(`http://${host}${req.url}`);
             const response = await oauthProxy.handleCallback(mockRequest);
@@ -1936,14 +1976,14 @@ var FastMCP = class extends FastMCPEventEmitter {
           }
           return;
         }
-        if (req.method === "POST" && url2.pathname === "/oauth/consent") {
+        if (req.method === "POST" && oauthPath === "/oauth/consent") {
           await new Promise((resolve) => {
             let body = "";
             req.on("data", (chunk) => body += chunk);
             req.on("end", async () => {
               try {
                 const mockRequest = new Request(
-                  `http://${host}/oauth/consent`,
+                  `http://${host}${url2.pathname}${url2.search}`,
                   {
                     body,
                     headers: {
@@ -1974,7 +2014,7 @@ var FastMCP = class extends FastMCPEventEmitter {
           });
           return;
         }
-        if (req.method === "POST" && url2.pathname === "/oauth/token") {
+        if (req.method === "POST" && oauthPath === "/oauth/token") {
           await new Promise((resolve) => {
             let body = "";
             req.on("data", (chunk) => body += chunk);
@@ -2078,11 +2118,13 @@ var FastMCP = class extends FastMCPEventEmitter {
     const transportArg = getArg("transport");
     const portArg = getArg("port");
     const endpointArg = getArg("endpoint");
+    const basePathArg = getArg("base-path");
     const statelessArg = getArg("stateless");
     const hostArg = getArg("host");
     const envTransport = process.env.FASTMCP_TRANSPORT;
     const envPort = process.env.FASTMCP_PORT;
     const envEndpoint = process.env.FASTMCP_ENDPOINT;
+    const envBasePath = process.env.FASTMCP_BASE_PATH;
     const envStateless = process.env.FASTMCP_STATELESS;
     const envHost = process.env.FASTMCP_HOST;
     const transportType = _optionalChain([overrides, 'optionalAccess', _56 => _56.transportType]) || (transportArg === "http-stream" ? "httpStream" : transportArg) || envTransport || "stdio";
@@ -2092,15 +2134,19 @@ var FastMCP = class extends FastMCPEventEmitter {
       );
       const host = _optionalChain([overrides, 'optionalAccess', _61 => _61.httpStream, 'optionalAccess', _62 => _62.host]) || hostArg || envHost || "localhost";
       const endpoint = _optionalChain([overrides, 'optionalAccess', _63 => _63.httpStream, 'optionalAccess', _64 => _64.endpoint]) || endpointArg || envEndpoint || "/mcp";
-      const enableJsonResponse = _optionalChain([overrides, 'optionalAccess', _65 => _65.httpStream, 'optionalAccess', _66 => _66.enableJsonResponse]) || false;
-      const stateless = _optionalChain([overrides, 'optionalAccess', _67 => _67.httpStream, 'optionalAccess', _68 => _68.stateless]) || statelessArg === "true" || envStateless === "true" || false;
-      const cors = _optionalChain([overrides, 'optionalAccess', _69 => _69.httpStream, 'optionalAccess', _70 => _70.cors]);
-      const eventStore = _optionalChain([overrides, 'optionalAccess', _71 => _71.httpStream, 'optionalAccess', _72 => _72.eventStore]);
-      const sslCa = _optionalChain([overrides, 'optionalAccess', _73 => _73.httpStream, 'optionalAccess', _74 => _74.sslCa]);
-      const sslCert = _optionalChain([overrides, 'optionalAccess', _75 => _75.httpStream, 'optionalAccess', _76 => _76.sslCert]);
-      const sslKey = _optionalChain([overrides, 'optionalAccess', _77 => _77.httpStream, 'optionalAccess', _78 => _78.sslKey]);
+      const basePath = normalizeBasePath(
+        _optionalChain([overrides, 'optionalAccess', _65 => _65.httpStream, 'optionalAccess', _66 => _66.basePath]) || basePathArg || envBasePath
+      );
+      const enableJsonResponse = _optionalChain([overrides, 'optionalAccess', _67 => _67.httpStream, 'optionalAccess', _68 => _68.enableJsonResponse]) || false;
+      const stateless = _optionalChain([overrides, 'optionalAccess', _69 => _69.httpStream, 'optionalAccess', _70 => _70.stateless]) || statelessArg === "true" || envStateless === "true" || false;
+      const cors = _optionalChain([overrides, 'optionalAccess', _71 => _71.httpStream, 'optionalAccess', _72 => _72.cors]);
+      const eventStore = _optionalChain([overrides, 'optionalAccess', _73 => _73.httpStream, 'optionalAccess', _74 => _74.eventStore]);
+      const sslCa = _optionalChain([overrides, 'optionalAccess', _75 => _75.httpStream, 'optionalAccess', _76 => _76.sslCa]);
+      const sslCert = _optionalChain([overrides, 'optionalAccess', _77 => _77.httpStream, 'optionalAccess', _78 => _78.sslCert]);
+      const sslKey = _optionalChain([overrides, 'optionalAccess', _79 => _79.httpStream, 'optionalAccess', _80 => _80.sslKey]);
       return {
         httpStream: {
+          basePath,
           cors,
           enableJsonResponse,
           endpoint,
@@ -2170,4 +2216,4 @@ var FastMCP = class extends FastMCPEventEmitter {
 
 
 exports.DiscoveryDocumentCache = DiscoveryDocumentCache; exports.imageContent = imageContent; exports.audioContent = audioContent; exports.UnexpectedStateError = UnexpectedStateError; exports.UserError = UserError; exports.ServerState = ServerState; exports.FastMCPSession = FastMCPSession; exports.FastMCP = FastMCP;
-//# sourceMappingURL=chunk-RPY6M6HD.cjs.map
+//# sourceMappingURL=chunk-3YTRRGCE.cjs.map