fastmcp 3.12.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

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

@@ -1091,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");
     }
@@ -1206,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) => {
@@ -1215,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(
@@ -1225,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"
       };