fastmcp 3.11.0 → 3.13.0

package/README.md

@@ -18,6 +18,7 @@ A TypeScript framework for building [MCP](https://glama.ai/mcp) servers capable
 - [Logging](#logging)
 - [Error handling](#errors)
 - [HTTP Streaming](#http-streaming) (with SSE compatibility)
+- [Stateless mode](#stateless-mode) for serverless deployments
 - CORS (enabled by default)
 - [Progress notifications](#progress)
 - [Streaming output](#streaming-output)
@@ -178,6 +179,52 @@ const transport = new SSEClientTransport(new URL(`http://localhost:8080/sse`));
 await client.connect(transport);
 ```
 
+#### Stateless Mode
+
+FastMCP supports stateless operation for HTTP streaming, where each request is handled independently without maintaining persistent sessions. This is ideal for serverless environments, load-balanced deployments, or when session state isn't required.
+
+In stateless mode:
+
+- No sessions are tracked on the server
+- Each request creates a temporary session that's discarded after the response
+- Reduced memory usage and better scalability
+- Perfect for stateless deployment environments
+
+You can enable stateless mode by adding the `stateless: true` option:
+
+```ts
+server.start({
+  transportType: "httpStream",
+  httpStream: {
+    port: 8080,
+    stateless: true,
+  },
+});
+```
+
+> **Note:** Stateless mode is only available with HTTP streaming transport. Features that depend on persistent sessions (like session-specific state) will not be available in stateless mode.
+
+You can also enable stateless mode using CLI arguments or environment variables:
+
+```bash
+# Via CLI argument
+npx fastmcp dev src/server.ts --transport http-stream --port 8080 --stateless true
+
+# Via environment variable
+FASTMCP_STATELESS=true npx fastmcp dev src/server.ts
+```
+
+The `/ready` health check endpoint will indicate when the server is running in stateless mode:
+
+```json
+{
+  "mode": "stateless",
+  "ready": 1,
+  "status": "ready",
+  "total": 1
+}
+```
+
 ## Core Concepts
 
 ### Tools

package/dist/FastMCP.d.ts

@@ -293,20 +293,147 @@ type ServerOptions<T extends FastMCPSessionAuth> = {
          */
         enabled: boolean;
         /**
-         * OAuth Protected Resource metadata for /.well-known/oauth-protected-resource
+         * OAuth Protected Resource metadata for `/.well-known/oauth-protected-resource`
          *
-         * This endpoint follows RFC 9470 (OAuth 2.0 Protected Resource Metadata)
-         * and provides metadata about the OAuth 2.0 protected resource.
+         * This endpoint follows {@link https://www.rfc-editor.org/rfc/rfc9728.html | RFC 9728}
+         * and provides metadata describing how an OAuth 2.0 protected resource (in this case,
+         * an MCP server) expects to be accessed.
          *
-         * Required by MCP Specification 2025-06-18
+         * When configured, FastMCP will automatically serve this metadata at the
+         * `/.well-known/oauth-protected-resource` endpoint. The `authorizationServers` and `resource`
+         * fields are required. All others are optional and will be omitted from the published
+         * metadata if not specified.
+         *
+         * This satisfies the requirements of the MCP Authorization specification's
+         * {@link https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-location | Authorization Server Location section}.
+         *
+         * Clients consuming this metadata MUST validate that any presented values comply with
+         * RFC 9728, including strict validation of the `resource` identifier and intended audience
+         * when access tokens are issued and presented (per RFC 8707 §2).
+         *
+         * @remarks Required by MCP Specification version 2025-06-18
          */
         protectedResource?: {
+            /**
+             * Allows for additional metadata fields beyond those defined in RFC 9728.
+             *
+             * @remarks This supports vendor-specific or experimental extensions.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2.3 | RFC 9728 §2.3}
+             */
+            [key: string]: unknown;
+            /**
+             * Supported values for the `authorization_details` parameter (RFC 9396).
+             *
+             * @remarks Used when fine-grained access control is in play.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.23 | RFC 9728 §2.2.23}
+             */
+            authorizationDetailsTypesSupported?: string[];
+            /**
+             * List of OAuth 2.0 authorization server issuer identifiers.
+             *
+             * These correspond to ASes that can issue access tokens for this protected resource.
+             * MCP clients use these values to locate the relevant `/.well-known/oauth-authorization-server`
+             * metadata for initiating the OAuth flow.
+             *
+             * @remarks Required by the MCP spec. MCP servers MUST provide at least one issuer.
+             * Clients are responsible for choosing among them (see RFC 9728 §7.6).
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.3 | RFC 9728 §2.2.3}
+             */
             authorizationServers: string[];
+            /**
+             * List of supported methods for presenting OAuth 2.0 bearer tokens.
+             *
+             * @remarks Valid values are `header`, `body`, and `query`.
+             * If omitted, clients MAY assume only `header` is supported, per RFC 6750.
+             * This is a client-side interpretation and not a serialization default.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.9 | RFC 9728 §2.2.9}
+             */
             bearerMethodsSupported?: string[];
+            /**
+             * Whether this resource requires all access tokens to be DPoP-bound.
+             *
+             * @remarks If omitted, clients SHOULD assume this is `false`.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.27 | RFC 9728 §2.2.27}
+             */
+            dpopBoundAccessTokensRequired?: boolean;
+            /**
+             * Supported algorithms for verifying DPoP proofs (RFC 9449).
+             *
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.25 | RFC 9728 §2.2.25}
+             */
+            dpopSigningAlgValuesSupported?: string[];
+            /**
+             * JWKS URI of this resource. Used to validate access tokens or sign responses.
+             *
+             * @remarks When present, this MUST be an `https:` URI pointing to a valid JWK Set (RFC 7517).
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.5 | RFC 9728 §2.2.5}
+             */
             jwksUri?: string;
+            /**
+             * Canonical OAuth resource identifier for this protected resource (the MCP server).
+             *
+             * @remarks Typically the base URL of the MCP server. Clients MUST use this as the
+             * `resource` parameter in authorization and token requests (per RFC 8707).
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.1 | RFC 9728 §2.2.1}
+             */
             resource: string;
+            /**
+             * URL to developer-accessible documentation for this resource.
+             *
+             * @remarks This field MAY be localized.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.15 | RFC 9728 §2.2.15}
+             */
             resourceDocumentation?: string;
+            /**
+             * Human-readable name for display purposes (e.g., in UIs).
+             *
+             * @remarks This field MAY be localized using language tags (`resource_name#en`, etc.).
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.13 | RFC 9728 §2.2.13}
+             */
+            resourceName?: string;
+            /**
+             * URL to a human-readable policy page describing acceptable use.
+             *
+             * @remarks This field MAY be localized.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.17 | RFC 9728 §2.2.17}
+             */
             resourcePolicyUri?: string;
+            /**
+             * Supported JWS algorithms for signed responses from this resource (e.g., response signing).
+             *
+             * @remarks MUST NOT include `none`.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.11 | RFC 9728 §2.2.11}
+             */
+            resourceSigningAlgValuesSupported?: string[];
+            /**
+             * URL to the protected resource’s Terms of Service.
+             *
+             * @remarks This field MAY be localized.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.19 | RFC 9728 §2.2.19}
+             */
+            resourceTosUri?: string;
+            /**
+             * Supported OAuth scopes for requesting access to this resource.
+             *
+             * @remarks Useful for discovery, but clients SHOULD still request the minimal scope required.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.7 | RFC 9728 §2.2.7}
+             */
+            scopesSupported?: string[];
+            /**
+             * Developer-accessible documentation for how to use the service (not end-user docs).
+             *
+             * @remarks Semantically equivalent to `resourceDocumentation`, but included under its
+             * alternate name for compatibility with tools or schemas expecting either.
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.15 | RFC 9728 §2.2.15}
+             */
+            serviceDocumentation?: string;
+            /**
+             * Whether mutual-TLS-bound access tokens are required.
+             *
+             * @remarks If omitted, clients SHOULD assume this is `false` (client-side behavior).
+             * @see {@link https://www.rfc-editor.org/rfc/rfc9728.html#section-2-2.21 | RFC 9728 §2.2.21}
+             */
+            tlsClientCertificateBoundAccessTokens?: boolean;
         };
     };
     ping?: {
@@ -479,6 +606,7 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
             endpoint?: `/${string}`;
             eventStore?: EventStore;
             port: number;
+            stateless?: boolean;
         };
         transportType: "httpStream" | "stdio";
     }>): Promise<void>;

package/dist/FastMCP.js

@@ -751,7 +751,11 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
                 "[FastMCP debug] listRoots method not supported by client"
               );
             } else {
-              console.error("[FastMCP error] Error listing roots", error);
+              console.error(
+                `[FastMCP error] received error listing roots.
+
+${error instanceof Error ? error.stack : JSON.stringify(error)}`
+              );
             }
           });
         }
@@ -1087,109 +1091,71 @@ var FastMCP = class extends FastMCPEventEmitter {
       });
     } else if (config.transportType === "httpStream") {
       const httpConfig = config.httpStream;
-      this.#httpStreamServer = await startHTTPServer({
-        createServer: async (request) => {
-          let auth;
-          if (this.#authenticate) {
-            auth = await this.#authenticate(request);
-          }
-          const allowedTools = auth ? this.#tools.filter(
-            (tool) => tool.canAccess ? tool.canAccess(auth) : true
-          ) : this.#tools;
-          return new FastMCPSession({
-            auth,
-            name: this.#options.name,
-            ping: this.#options.ping,
-            prompts: this.#prompts,
-            resources: this.#resources,
-            resourcesTemplates: this.#resourcesTemplates,
-            roots: this.#options.roots,
-            tools: allowedTools,
-            transportType: "httpStream",
-            utils: this.#options.utils,
-            version: this.#options.version
-          });
-        },
-        enableJsonResponse: httpConfig.enableJsonResponse,
-        eventStore: httpConfig.eventStore,
-        onClose: async (session) => {
-          this.emit("disconnect", {
-            session
-          });
-        },
-        onConnect: async (session) => {
-          this.#sessions.push(session);
-          console.info(`[FastMCP info] HTTP Stream session established`);
-          this.emit("connect", {
-            session
-          });
-        },
-        onUnhandledRequest: async (req, res) => {
-          const healthConfig = this.#options.health ?? {};
-          const enabled = healthConfig.enabled === void 0 ? true : healthConfig.enabled;
-          if (enabled) {
-            const path = healthConfig.path ?? "/health";
-            const url = new URL(req.url || "", "http://localhost");
-            try {
-              if (req.method === "GET" && url.pathname === path) {
-                res.writeHead(healthConfig.status ?? 200, {
-                  "Content-Type": "text/plain"
-                }).end(healthConfig.message ?? "\u2713 Ok");
-                return;
-              }
-              if (req.method === "GET" && url.pathname === "/ready") {
-                const readySessions = this.#sessions.filter(
-                  (s) => s.isReady
-                ).length;
-                const totalSessions = this.#sessions.length;
-                const allReady = readySessions === totalSessions && totalSessions > 0;
-                const response = {
-                  ready: readySessions,
-                  status: allReady ? "ready" : totalSessions === 0 ? "no_sessions" : "initializing",
-                  total: totalSessions
-                };
-                res.writeHead(allReady ? 200 : 503, {
-                  "Content-Type": "application/json"
-                }).end(JSON.stringify(response));
-                return;
-              }
-            } catch (error) {
-              console.error("[FastMCP error] health endpoint error", error);
-            }
-          }
-          const oauthConfig = this.#options.oauth;
-          if (oauthConfig?.enabled && req.method === "GET") {
-            const url = new URL(req.url || "", "http://localhost");
-            if (url.pathname === "/.well-known/oauth-authorization-server" && oauthConfig.authorizationServer) {
-              const metadata = convertObjectToSnakeCase(
-                oauthConfig.authorizationServer
-              );
-              res.writeHead(200, {
-                "Content-Type": "application/json"
-              }).end(JSON.stringify(metadata));
-              return;
+      if (httpConfig.stateless) {
+        console.info(
+          `[FastMCP info] Starting server in stateless mode on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`
+        );
+        this.#httpStreamServer = await startHTTPServer({
+          createServer: async (request) => {
+            let auth;
+            if (this.#authenticate) {
+              auth = await this.#authenticate(request);
             }
-            if (url.pathname === "/.well-known/oauth-protected-resource" && oauthConfig.protectedResource) {
-              const metadata = convertObjectToSnakeCase(
-                oauthConfig.protectedResource
-              );
-              res.writeHead(200, {
-                "Content-Type": "application/json"
-              }).end(JSON.stringify(metadata));
-              return;
+            return this.#createSession(auth);
+          },
+          enableJsonResponse: httpConfig.enableJsonResponse,
+          eventStore: httpConfig.eventStore,
+          // In stateless mode, we don't track sessions
+          onClose: async () => {
+          },
+          onConnect: async () => {
+            console.debug(
+              `[FastMCP debug] Stateless HTTP Stream request handled`
+            );
+          },
+          onUnhandledRequest: async (req, res) => {
+            await this.#handleUnhandledRequest(req, res, true);
+          },
+          port: httpConfig.port,
+          stateless: true,
+          streamEndpoint: httpConfig.endpoint
+        });
+      } else {
+        this.#httpStreamServer = await startHTTPServer({
+          createServer: async (request) => {
+            let auth;
+            if (this.#authenticate) {
+              auth = await this.#authenticate(request);
             }
-          }
-          res.writeHead(404).end();
-        },
-        port: httpConfig.port,
-        streamEndpoint: httpConfig.endpoint
-      });
-      console.info(
-        `[FastMCP info] server is running on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`
-      );
-      console.info(
-        `[FastMCP info] Transport type: httpStream (Streamable HTTP, not SSE)`
-      );
+            return this.#createSession(auth);
+          },
+          enableJsonResponse: httpConfig.enableJsonResponse,
+          eventStore: httpConfig.eventStore,
+          onClose: async (session) => {
+            this.emit("disconnect", {
+              session
+            });
+          },
+          onConnect: async (session) => {
+            this.#sessions.push(session);
+            console.info(`[FastMCP info] HTTP Stream session established`);
+            this.emit("connect", {
+              session
+            });
+          },
+          onUnhandledRequest: async (req, res) => {
+            await this.#handleUnhandledRequest(req, res, false);
+          },
+          port: httpConfig.port,
+          streamEndpoint: httpConfig.endpoint
+        });
+        console.info(
+          `[FastMCP info] server is running on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`
+        );
+        console.info(
+          `[FastMCP info] Transport type: httpStream (Streamable HTTP, not SSE)`
+        );
+      }
     } else {
       throw new Error("Invalid transport type");
     }
@@ -1202,6 +1168,100 @@ var FastMCP = class extends FastMCPEventEmitter {
       await this.#httpStreamServer.close();
     }
   }
+  /**
+   * Creates a new FastMCPSession instance with the current configuration.
+   * Used both for regular sessions and stateless requests.
+   */
+  #createSession(auth) {
+    const allowedTools = auth ? this.#tools.filter(
+      (tool) => tool.canAccess ? tool.canAccess(auth) : true
+    ) : this.#tools;
+    return new FastMCPSession({
+      auth,
+      name: this.#options.name,
+      ping: this.#options.ping,
+      prompts: this.#prompts,
+      resources: this.#resources,
+      resourcesTemplates: this.#resourcesTemplates,
+      roots: this.#options.roots,
+      tools: allowedTools,
+      transportType: "httpStream",
+      utils: this.#options.utils,
+      version: this.#options.version
+    });
+  }
+  /**
+   * Handles unhandled HTTP requests with health, readiness, and OAuth endpoints
+   */
+  #handleUnhandledRequest = async (req, res, isStateless = false) => {
+    const healthConfig = this.#options.health ?? {};
+    const enabled = healthConfig.enabled === void 0 ? true : healthConfig.enabled;
+    if (enabled) {
+      const path = healthConfig.path ?? "/health";
+      const url = new URL(req.url || "", "http://localhost");
+      try {
+        if (req.method === "GET" && url.pathname === path) {
+          res.writeHead(healthConfig.status ?? 200, {
+            "Content-Type": "text/plain"
+          }).end(healthConfig.message ?? "\u2713 Ok");
+          return;
+        }
+        if (req.method === "GET" && url.pathname === "/ready") {
+          if (isStateless) {
+            const response = {
+              mode: "stateless",
+              ready: 1,
+              status: "ready",
+              total: 1
+            };
+            res.writeHead(200, {
+              "Content-Type": "application/json"
+            }).end(JSON.stringify(response));
+          } else {
+            const readySessions = this.#sessions.filter(
+              (s) => s.isReady
+            ).length;
+            const totalSessions = this.#sessions.length;
+            const allReady = readySessions === totalSessions && totalSessions > 0;
+            const response = {
+              ready: readySessions,
+              status: allReady ? "ready" : totalSessions === 0 ? "no_sessions" : "initializing",
+              total: totalSessions
+            };
+            res.writeHead(allReady ? 200 : 503, {
+              "Content-Type": "application/json"
+            }).end(JSON.stringify(response));
+          }
+          return;
+        }
+      } catch (error) {
+        console.error("[FastMCP error] health endpoint error", error);
+      }
+    }
+    const oauthConfig = this.#options.oauth;
+    if (oauthConfig?.enabled && req.method === "GET") {
+      const url = new URL(req.url || "", "http://localhost");
+      if (url.pathname === "/.well-known/oauth-authorization-server" && oauthConfig.authorizationServer) {
+        const metadata = convertObjectToSnakeCase(
+          oauthConfig.authorizationServer
+        );
+        res.writeHead(200, {
+          "Content-Type": "application/json"
+        }).end(JSON.stringify(metadata));
+        return;
+      }
+      if (url.pathname === "/.well-known/oauth-protected-resource" && oauthConfig.protectedResource) {
+        const metadata = convertObjectToSnakeCase(
+          oauthConfig.protectedResource
+        );
+        res.writeHead(200, {
+          "Content-Type": "application/json"
+        }).end(JSON.stringify(metadata));
+        return;
+      }
+    }
+    res.writeHead(404).end();
+  };
   #parseRuntimeConfig(overrides) {
     const args = process.argv.slice(2);
     const getArg = (name) => {
@@ -1211,9 +1271,11 @@ var FastMCP = class extends FastMCPEventEmitter {
     const transportArg = getArg("transport");
     const portArg = getArg("port");
     const endpointArg = getArg("endpoint");
+    const statelessArg = getArg("stateless");
     const envTransport = process.env.FASTMCP_TRANSPORT;
     const envPort = process.env.FASTMCP_PORT;
     const envEndpoint = process.env.FASTMCP_ENDPOINT;
+    const envStateless = process.env.FASTMCP_STATELESS;
     const transportType = overrides?.transportType || (transportArg === "http-stream" ? "httpStream" : transportArg) || envTransport || "stdio";
     if (transportType === "httpStream") {
       const port = parseInt(
@@ -1221,11 +1283,13 @@ var FastMCP = class extends FastMCPEventEmitter {
       );
       const endpoint = overrides?.httpStream?.endpoint || endpointArg || envEndpoint || "/mcp";
       const enableJsonResponse = overrides?.httpStream?.enableJsonResponse || false;
+      const stateless = overrides?.httpStream?.stateless || statelessArg === "true" || envStateless === "true" || false;
       return {
         httpStream: {
           enableJsonResponse,
           endpoint,
-          port
+          port,
+          stateless
         },
         transportType: "httpStream"
       };