@prefecthq/fastmcp-ts 1.0.0-rc.0 → 1.0.0-rc.1

package/dist/cli/index.cjs

@@ -1172,7 +1172,7 @@ var init_version = __esm({
       async run({ args }) {
         if (args.json) setJsonMode(true);
         const data = {
-          fastmcp: "1.0.0-rc.0",
+          fastmcp: "1.0.0-rc.1",
           "mcp-sdk": "2.0.0-beta.5",
           node: process.version,
           platform: `${process.platform} ${process.arch}`
@@ -46213,7 +46213,7 @@ init_format();
 var main = defineCommand({
   meta: {
     name: "fastmcp",
-    version: "1.0.0-rc.0",
+    version: "1.0.0-rc.1",
     description: "FastMCP CLI \u2014 build, run, and manage MCP servers"
   },
   args: {

package/dist/server.d.ts

@@ -796,6 +796,18 @@ interface RunOptions {
     port?: number;
     host?: string;
     path?: string;
+    /**
+     * Serve the legacy (2025-era) HTTP transport statelessly: a fresh server and
+     * transport per request, no session registry, incoming `mcp-session-id`
+     * ignored, and no session id issued. Use this behind a load balancer or on
+     * serverless compute where consecutive requests reach different instances.
+     *
+     * Falls back to the `FASTMCP_STATELESS_HTTP` environment variable, then to
+     * `false`. A valid value is ignored for the stdio transport, but a malformed
+     * one still aborts stdio startup, deliberately. The modern (2026-07-28) era
+     * is already stateless and is unaffected.
+     */
+    stateless?: boolean;
     /** Custom stdin stream for the stdio transport. Defaults to process.stdin. */
     stdin?: Readable;
     /** Custom stdout stream for the stdio transport. Defaults to process.stdout. */
@@ -862,11 +874,13 @@ declare class FastMCP {
     private _address;
     private _isRunning;
     private _sessions;
+    private _stateless;
     private _primaryServer;
     private _stdioServer;
     private _stdioState;
     private _stdioHandle;
     private _modernHandler;
+    private _statelessLegacyHandler;
     private _toolRegisteredCallbacks;
     private _resourceRegisteredCallbacks;
     private _promptRegisteredCallbacks;
@@ -898,6 +912,11 @@ declare class FastMCP {
      * client here, so nothing needs the era fork the way `subscribe` does. The
      * SDK also requires this capability to be present to register the
      * `completion/complete` handler (`assertRequestHandlerCapability`).
+     *
+     * `stateless` withdraws the same capability for a different reason. A
+     * stateless server has no session for a subscription to live in and no
+     * channel to deliver `notifications/resources/updated` on, so it must not
+     * claim the capability.
      */
     private _makeServer;
     private _resolveToken;
@@ -961,7 +980,7 @@ declare class FastMCP {
      * Dispatch a tool call through this server's middleware chain using an inherited context.
      * Used by parent servers to honour child-level middleware when routing mounted tool calls.
      */
-    _dispatchTool(name: string, rawArgs: unknown, ctx: McpContext): Promise<{
+    _dispatchTool(name: string, rawArgs: unknown, ctx: McpContext): Promise<_modelcontextprotocol_server.InputRequiredResult | {
         [x: string]: unknown;
         content: ({
             type: "text";
@@ -1064,7 +1083,7 @@ declare class FastMCP {
         } | undefined;
         structuredContent?: unknown;
         isError?: boolean | undefined;
-    } | _modelcontextprotocol_server.InputRequiredResult>;
+    }>;
     /**
      * Run a resource read through this server's middleware chain using an inherited context.
      * Returns the raw handler result so the parent can apply convertResourceResult with the
@@ -1139,6 +1158,16 @@ declare class FastMCP {
      * of createMcpHandler's own stateless legacy fallback, so session state and the
      * legacy server-initiated-request shim keep working for 2025-era clients. */
     private _getModernHandler;
+    /** Lazily builds the stateless legacy (2025-era) HTTP handler. One per FastMCP
+     * instance, mirroring _getModernHandler's per-instance, per-request-factory model.
+     *
+     * The SDK serves each POST from a fresh instance of the factory over a transport
+     * built with `sessionIdGenerator: undefined`, and answers GET and DELETE with 405
+     * because both are session operations that mean nothing per request.
+     *
+     * Only reachable when `_stateless` is on. The sessionful transport in
+     * _dispatchLegacyHttp is untouched and still serves every other deployment. */
+    private _getStatelessLegacyHandler;
     /**
      * Dual-era HTTP dispatch shared by the OAuth and non-OAuth serve paths. Assumes CORS
      * and auth have already been handled by the caller (req.auth already set, if any —

package/dist/server.js

@@ -4,7 +4,7 @@ import {
 
 // src/server/FastMCP.ts
 import { hostHeaderValidation, originValidation } from "@modelcontextprotocol/node";
-import { ProtocolError as ProtocolError3, ProtocolErrorCode as ProtocolErrorCode3, ResourceNotFoundError, Server as Server2, createMcpHandler, isLegacyRequest, isJsonContentType, createRequestStateCodec, localhostAllowedHostnames, localhostAllowedOrigins, assertCompleteRequestPrompt, assertCompleteRequestResourceTemplate } from "@modelcontextprotocol/server";
+import { ProtocolError as ProtocolError3, ProtocolErrorCode as ProtocolErrorCode3, ResourceNotFoundError, Server as Server2, createMcpHandler, legacyStatelessFallback, isLegacyRequest, isJsonContentType, createRequestStateCodec, localhostAllowedHostnames, localhostAllowedOrigins, assertCompleteRequestPrompt, assertCompleteRequestResourceTemplate } from "@modelcontextprotocol/server";
 import { randomUUID as randomUUID2 } from "crypto";
 
 // src/server/auth/types.ts
@@ -60,11 +60,17 @@ import { AsyncLocalStorage } from "async_hooks";
 var contextStore = new AsyncLocalStorage();
 var SESSION_CLOSE_CALLBACKS_KEY = "__fastmcp_session_close_callbacks";
 var SESSION_STATE_MODERN_HTTP_ERROR = "[fastmcp] Session state is not available on modern HTTP requests (protocol revision 2026-07-28). Each request runs statelessly with no shared session store. Use ctx.requestState() to read per-request state. Use ctx.mintRequestState() to carry state across a multi-round-trip flow.";
-function createContext(server, sdkCtx, auth, sessionState, requestStateCodec) {
+var SESSION_STATE_STATELESS_HTTP_ERROR = "[fastmcp] Session state is not available on a stateless HTTP server (RunOptions.stateless or FASTMCP_STATELESS_HTTP). Each request runs against a fresh store that is discarded when the request ends. Use ctx.requestState() to read per-request state. Use ctx.mintRequestState() to carry state across a multi-round-trip flow. Turn stateless off to use session state, or keep state in your own external store.";
+var SERVER_INITIATED_STATELESS_HTTP_ERROR = "[fastmcp] Server-initiated requests (ctx.elicit, ctx.sample, ctx.listRoots) are not available on a stateless HTTP server (RunOptions.stateless or FASTMCP_STATELESS_HTTP). They need a session: client capabilities are negotiated once at initialize, and the client replies on a separate request. Return inputRequired({ requestState }) to carry a multi-round-trip flow without a session; the embedded-request form of inputRequired needs a session too. Turn stateless off to use server-initiated requests.";
+function createContext(server, sdkCtx, auth, sessionState, requestStateCodec, stateless) {
   const requestId = String(sdkCtx.mcpReq.id);
   const progressToken = sdkCtx.mcpReq._meta?.progressToken;
   const isModernEra = sdkCtx.mcpReq.envelope !== void 0;
   const isModernHttpRequest = isModernEra && sdkCtx.http !== void 0;
+  const sessionlessReason = isModernHttpRequest ? "modern-http" : stateless && sdkCtx.http !== void 0 ? "stateless-http" : null;
+  const sessionStateError = () => new Error(
+    sessionlessReason === "modern-http" ? SESSION_STATE_MODERN_HTTP_ERROR : SESSION_STATE_STATELESS_HTTP_ERROR
+  );
   const serverRequestOptions = { relatedRequestId: sdkCtx.mcpReq.id };
   async function log(level, message, loggerName) {
     await sdkCtx.mcpReq.log(level, message, loggerName);
@@ -94,6 +100,7 @@ function createContext(server, sdkCtx, auth, sessionState, requestStateCodec) {
       });
     },
     async sample(params) {
+      if (sessionlessReason === "stateless-http") throw new Error(SERVER_INITIATED_STATELESS_HTTP_ERROR);
       if (!isModernEra) {
         const caps = server.getClientCapabilities();
         if (!caps?.sampling) {
@@ -121,6 +128,7 @@ function createContext(server, sdkCtx, auth, sessionState, requestStateCodec) {
       };
     },
     async elicit(message, schema) {
+      if (sessionlessReason === "stateless-http") throw new Error(SERVER_INITIATED_STATELESS_HTTP_ERROR);
       if (!isModernEra) {
         const caps = server.getClientCapabilities();
         if (!caps?.elicitation) {
@@ -144,6 +152,7 @@ function createContext(server, sdkCtx, auth, sessionState, requestStateCodec) {
       };
     },
     async listRoots() {
+      if (sessionlessReason === "stateless-http") throw new Error(SERVER_INITIATED_STATELESS_HTTP_ERROR);
       if (!isModernEra) {
         const caps = server.getClientCapabilities();
         if (!caps?.roots) {
@@ -165,15 +174,15 @@ function createContext(server, sdkCtx, auth, sessionState, requestStateCodec) {
       return JSON.stringify(payload);
     },
     getState: (key) => {
-      if (isModernHttpRequest) throw new Error(SESSION_STATE_MODERN_HTTP_ERROR);
+      if (sessionlessReason) throw sessionStateError();
       return sessionState.get(key);
     },
     setState: (key, value) => {
-      if (isModernHttpRequest) throw new Error(SESSION_STATE_MODERN_HTTP_ERROR);
+      if (sessionlessReason) throw sessionStateError();
       sessionState.set(key, value);
     },
     deleteState: (key) => {
-      if (isModernHttpRequest) throw new Error(SESSION_STATE_MODERN_HTTP_ERROR);
+      if (sessionlessReason) throw sessionStateError();
       sessionState.delete(key);
     },
     resolveToolName: (name) => name,
@@ -184,6 +193,20 @@ function createContext(server, sdkCtx, auth, sessionState, requestStateCodec) {
   };
 }
 
+// src/server/env.ts
+var TRUE_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on"]);
+var FALSE_VALUES = /* @__PURE__ */ new Set(["0", "false", "no", "off"]);
+function envBool(name) {
+  const raw = process.env[name];
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  const normalized = raw.trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) return true;
+  if (FALSE_VALUES.has(normalized)) return false;
+  throw new Error(
+    `[fastmcp] ${name} must be one of 1/true/yes/on or 0/false/no/off (case-insensitive). Received: ${JSON.stringify(raw)}`
+  );
+}
+
 // src/server/middleware.ts
 import { ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";
 import { createHash } from "crypto";
@@ -500,6 +523,13 @@ import { ProtocolError as ProtocolError2, ProtocolErrorCode as ProtocolErrorCode
 
 // src/server/mrtr.ts
 import { inputRequired, acceptedContent, inputResponse, isInputRequiredResult } from "@modelcontextprotocol/server";
+var INPUT_REQUESTS_STATELESS_HTTP_ERROR = "[fastmcp] inputRequired({ inputRequests }) is not available on a stateless HTTP server (RunOptions.stateless or FASTMCP_STATELESS_HTTP). Fulfilling inputRequests needs a session: the client's reply to each embedded request arrives on a separate request, and a stateless server discards its per-request Server before that reply could arrive \u2014 the same reason ctx.elicit/ctx.sample/ctx.listRoots are unavailable here. inputRequired({ requestState }), with no inputRequests, remains available \u2014 it carries state across rounds without needing a session. Turn stateless off to use inputRequests.";
+function assertInputRequestsAllowedStateless(value, stateless) {
+  const hasInputRequests = value.inputRequests !== void 0 && Object.keys(value.inputRequests).length > 0;
+  if (stateless && hasInputRequests) {
+    throw new Error(INPUT_REQUESTS_STATELESS_HTTP_ERROR);
+  }
+}
 
 // src/server/tool.ts
 var Image = class {
@@ -526,8 +556,9 @@ var ToolResult = class {
   }
   result;
 };
-function convertResult(value) {
+function convertResult(value, stateless) {
   if (isInputRequiredResult(value)) {
+    assertInputRequestsAllowedStateless(value, stateless);
     return value;
   }
   if (value instanceof ToolResult) {
@@ -623,8 +654,9 @@ var ResourceResult = class {
   }
   contents;
 };
-function convertResourceResult(value, uri, mimeType) {
+function convertResourceResult(value, uri, mimeType, stateless) {
   if (isInputRequiredResult(value)) {
+    assertInputRequestsAllowedStateless(value, stateless);
     return value;
   }
   if (value instanceof ResourceResult) {
@@ -721,8 +753,9 @@ function isPromptMessage(value) {
   if (!v.content || typeof v.content !== "object") return false;
   return typeof v.content.type === "string";
 }
-function convertPromptResult(value) {
+function convertPromptResult(value, stateless) {
   if (isInputRequiredResult(value)) {
+    assertInputRequestsAllowedStateless(value, stateless);
     return value;
   }
   if (value instanceof PromptResult) {
@@ -766,6 +799,7 @@ function prefixResourceUri(uri, prefix) {
   return `${uri.slice(0, idx + 3)}${prefix}/${uri.slice(idx + 3)}`;
 }
 var RESOURCE_SUBSCRIPTIONS_KEY = "__fastmcp_resource_subscriptions";
+var STATELESS_SUBSCRIBE_ERROR = "[fastmcp] resources/subscribe and resources/unsubscribe are unavailable on a stateless HTTP server. A stateless server keeps no session, so a subscription has nowhere to live and no channel to deliver on. The server does not advertise the resources.subscribe capability; a compliant client will not call this.";
 function inferDescription(name) {
   return name.replace(/([A-Z])/g, " $1").replace(/[-_]+/g, " ").trim().toLowerCase();
 }
@@ -841,6 +875,7 @@ var FastMCP = class {
   _address = null;
   _isRunning = false;
   _sessions = /* @__PURE__ */ new Map();
+  _stateless = false;
   // Primary server used by connect() (in-process transports — always 2025-era)
   _primaryServer;
   // The pinned Server instance for a run({transport:'stdio'}) connection (2025- or
@@ -854,6 +889,7 @@ var FastMCP = class {
   // Modern (2026-07-28) HTTP handler — one per FastMCP instance, lazily created.
   // Builds a fresh Server (via _makeServer) per request; see createMcpHandler.
   _modernHandler = null;
+  _statelessLegacyHandler = null;
   _toolRegisteredCallbacks = [];
   _resourceRegisteredCallbacks = [];
   _promptRegisteredCallbacks = [];
@@ -912,6 +948,11 @@ var FastMCP = class {
    * client here, so nothing needs the era fork the way `subscribe` does. The
    * SDK also requires this capability to be present to register the
    * `completion/complete` handler (`assertRequestHandlerCapability`).
+   *
+   * `stateless` withdraws the same capability for a different reason. A
+   * stateless server has no session for a subscription to live in and no
+   * channel to deliver `notifications/resources/updated` on, so it must not
+   * claim the capability.
    */
   _makeServer(sessionState, opts) {
     const state = sessionState ?? this._primaryState;
@@ -919,23 +960,23 @@ var FastMCP = class {
     const server = new Server2(
       { name: this.name, version: this.version },
       {
-        capabilities: { tools: { listChanged: true }, resources: { listChanged: true, ...opts?.modern ? {} : { subscribe: true } }, prompts: { listChanged: true }, logging: {}, completions: {}, ...extensions ? { extensions } : {} },
+        capabilities: { tools: { listChanged: true }, resources: { listChanged: true, ...opts?.modern || opts?.stateless ? {} : { subscribe: true } }, prompts: { listChanged: true }, logging: {}, completions: {}, ...extensions ? { extensions } : {} },
         ...this._cacheHints ? { cacheHints: this._cacheHints } : {},
         ...this._requestStateCodec ? { requestState: { verify: this._requestStateCodec.verify.bind(this._requestStateCodec) } } : {},
         ...this._inputRequiredOptions ? { inputRequired: this._inputRequiredOptions } : {}
       }
     );
     for (const mw of this._middleware) mw.setup?.(server);
-    this._setupHandlers(server, state);
+    this._setupHandlers(server, state, opts);
     return server;
   }
   async _resolveToken(authInfo) {
     return toAccessToken(authInfo) ?? await resolveCliEnvToken(this._auth);
   }
-  _setupHandlers(server, sessionState) {
+  _setupHandlers(server, sessionState, opts) {
     server.setRequestHandler("tools/list", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "tools/list", req.params, ctx, async () => {
@@ -1014,7 +1055,7 @@ var FastMCP = class {
       const synthTool = synthesizedList.find((s) => s.name === requestedName);
       if (synthTool) {
         if (synthTool.auth) await runAuthCheck(synthTool.auth, token);
-        const ctx2 = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+        const ctx2 = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
         try {
           return await contextStore.run(
             ctx2,
@@ -1035,7 +1076,7 @@ var FastMCP = class {
                   () => clearTimeout(timer)
                 );
               }
-              return convertResult(await executePromise);
+              return convertResult(await executePromise, opts?.stateless);
             })
           );
         } catch (err) {
@@ -1067,7 +1108,7 @@ var FastMCP = class {
       if (tool.config.auth) await runAuthCheck(tool.config.auth, token);
       const resolvedTool = tool;
       const rawArgs = req.params.arguments ?? {};
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       try {
         return await contextStore.run(
           ctx,
@@ -1089,7 +1130,7 @@ var FastMCP = class {
             }
             let resultValue = await executePromise;
             if (resolvedTool.config.output) resultValue = await validateInput(resolvedTool.config.output, resultValue);
-            const callResult = convertResult(resultValue);
+            const callResult = convertResult(resultValue, opts?.stateless);
             if (resolvedTool.config.ui) {
               const clientIsUi = isUiCapable(server.getClientCapabilities());
               if (!clientIsUi && callResult.structuredContent !== void 0) {
@@ -1109,7 +1150,7 @@ var FastMCP = class {
     });
     server.setRequestHandler("resources/list", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/list", req.params, ctx, async () => {
@@ -1156,7 +1197,7 @@ var FastMCP = class {
     });
     server.setRequestHandler("resources/templates/list", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/templates/list", req.params, ctx, async () => {
@@ -1208,7 +1249,7 @@ var FastMCP = class {
       const resource = resolved.resource;
       const templateParams = resolved.templateParams;
       if (resource.config.auth) await runAuthCheck(resource.config.auth, token);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/read", req.params, ctx, async () => {
@@ -1227,11 +1268,12 @@ var FastMCP = class {
             );
           }
           const result = await executePromise;
-          return convertResourceResult(result, requestedUri, resource.config.mimeType);
+          return convertResourceResult(result, requestedUri, resource.config.mimeType, opts?.stateless);
         })
       );
     });
     server.setRequestHandler("resources/subscribe", async (req, sdkCtx) => {
+      if (opts?.stateless) throw new ProtocolError3(ProtocolErrorCode3.MethodNotFound, STATELESS_SUBSCRIBE_ERROR);
       const uri = req.params.uri;
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
       const resolved = this._resolveResource(uri);
@@ -1240,7 +1282,7 @@ var FastMCP = class {
       }
       const resource = resolved.resource;
       if (resource.config.auth) await runAuthCheck(resource.config.auth, token);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/subscribe", req.params, ctx, async () => {
@@ -1255,9 +1297,10 @@ var FastMCP = class {
       );
     });
     server.setRequestHandler("resources/unsubscribe", async (req, sdkCtx) => {
+      if (opts?.stateless) throw new ProtocolError3(ProtocolErrorCode3.MethodNotFound, STATELESS_SUBSCRIBE_ERROR);
       const uri = req.params.uri;
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "resources/unsubscribe", req.params, ctx, async () => {
@@ -1269,7 +1312,7 @@ var FastMCP = class {
     });
     server.setRequestHandler("prompts/list", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "prompts/list", req.params, ctx, async () => {
@@ -1349,7 +1392,7 @@ var FastMCP = class {
           );
         }
       }
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "prompts/get", req.params, ctx, async () => {
@@ -1367,13 +1410,13 @@ var FastMCP = class {
               () => clearTimeout(timer)
             );
           }
-          return convertPromptResult(await executePromise);
+          return convertPromptResult(await executePromise, opts?.stateless);
         })
       );
     });
     server.setRequestHandler("completion/complete", async (req, sdkCtx) => {
       const token = await this._resolveToken(sdkCtx.http?.authInfo);
-      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec);
+      const ctx = createContext(server, sdkCtx, token, sessionState, this._requestStateCodec, opts?.stateless);
       return contextStore.run(
         ctx,
         () => runMiddlewareChain(this._middleware, "completion/complete", req.params, ctx, async () => {
@@ -1995,6 +2038,7 @@ var FastMCP = class {
     const port = options?.port ?? parseInt(process.env.MCP_PORT ?? process.env.PORT ?? "3000", 10);
     const host = options?.host ?? process.env.MCP_HOST ?? "127.0.0.1";
     const path = options?.path ?? process.env.MCP_PATH ?? "/mcp";
+    this._stateless = options?.stateless ?? envBool("FASTMCP_STATELESS_HTTP") ?? false;
     if (transport === "stdio") {
       const { StdioServerTransport, serveStdio } = await import("@modelcontextprotocol/server/stdio");
       const stdioTransport = new StdioServerTransport(options?.stdin, options?.stdout);
@@ -2028,6 +2072,24 @@ var FastMCP = class {
     }
     return this._modernHandler;
   }
+  /** Lazily builds the stateless legacy (2025-era) HTTP handler. One per FastMCP
+   * instance, mirroring _getModernHandler's per-instance, per-request-factory model.
+   *
+   * The SDK serves each POST from a fresh instance of the factory over a transport
+   * built with `sessionIdGenerator: undefined`, and answers GET and DELETE with 405
+   * because both are session operations that mean nothing per request.
+   *
+   * Only reachable when `_stateless` is on. The sessionful transport in
+   * _dispatchLegacyHttp is untouched and still serves every other deployment. */
+  _getStatelessLegacyHandler() {
+    if (!this._statelessLegacyHandler) {
+      this._statelessLegacyHandler = legacyStatelessFallback(
+        () => this._makeServer(/* @__PURE__ */ new Map(), { stateless: true }),
+        (error) => console.error("[fastmcp] stateless legacy serving failed:", error)
+      );
+    }
+    return this._statelessLegacyHandler;
+  }
   /**
    * Dual-era HTTP dispatch shared by the OAuth and non-OAuth serve paths. Assumes CORS
    * and auth have already been handled by the caller (req.auth already set, if any —
@@ -2045,7 +2107,11 @@ var FastMCP = class {
     const legacy = await isLegacyRequest(request);
     const parsedBody = req.method === "POST" ? await request.json().catch(() => void 0) : void 0;
     if (legacy) {
-      await this._dispatchLegacyHttp(req, res, parsedBody);
+      if (this._stateless) {
+        await toNodeHandler({ fetch: this._getStatelessLegacyHandler() })(req, res, parsedBody);
+      } else {
+        await this._dispatchLegacyHttp(req, res, parsedBody);
+      }
     } else {
       await toNodeHandler(this._getModernHandler())(req, res, parsedBody);
     }
@@ -2218,6 +2284,7 @@ var FastMCP = class {
       await this._modernHandler.close();
       this._modernHandler = null;
     }
+    this._statelessLegacyHandler = null;
     if (this._stdioHandle) {
       await this._stdioHandle.close();
       this._stdioHandle = null;