fastmcp 3.11.0 → 3.13.0

package/src/FastMCP.ts

@@ -624,20 +624,162 @@ 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;
     };
   };
 
@@ -1451,7 +1593,11 @@ export class FastMCPSession<
                   "[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.\n\n${
+                    error instanceof Error ? error.stack : JSON.stringify(error)
+                  }`,
+                );
               }
             });
         },
@@ -1872,6 +2018,7 @@ export class FastMCP<
         endpoint?: `/${string}`;
         eventStore?: EventStore;
         port: number;
+        stateless?: boolean;
       };
       transportType: "httpStream" | "stdio";
     }>,
@@ -1904,151 +2051,86 @@ export class FastMCP<
     } else if (config.transportType === "httpStream") {
       const httpConfig = config.httpStream;
 
-      this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
-        createServer: async (request) => {
-          let auth: T | undefined;
-
-          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<T>({
-            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: session as FastMCPSession<FastMCPSessionAuth>,
-          });
-        },
-        onConnect: async (session) => {
-          this.#sessions.push(session);
-
-          console.info(`[FastMCP info] HTTP Stream session established`);
-
-          this.emit("connect", {
-            session: session as FastMCPSession<FastMCPSessionAuth>,
-          });
-        },
-
-        onUnhandledRequest: async (req, res) => {
-          const healthConfig = this.#options.health ?? {};
+      if (httpConfig.stateless) {
+        // Stateless mode - create new server instance for each request
+        console.info(
+          `[FastMCP info] Starting server in stateless mode on HTTP Stream at http://localhost:${httpConfig.port}${httpConfig.endpoint}`,
+        );
 
-          const enabled =
-            healthConfig.enabled === undefined ? true : healthConfig.enabled;
+        this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
+          createServer: async (request) => {
+            let auth: T | undefined;
 
-          if (enabled) {
-            const path = healthConfig.path ?? "/health";
-            const url = new URL(req.url || "", "http://localhost");
+            if (this.#authenticate) {
+              auth = await this.#authenticate(request);
+            }
 
-            try {
-              if (req.method === "GET" && url.pathname === path) {
-                res
-                  .writeHead(healthConfig.status ?? 200, {
-                    "Content-Type": "text/plain",
-                  })
-                  .end(healthConfig.message ?? "✓ Ok");
-
-                return;
-              }
+            // In stateless mode, create a new session for each request
+            // without persisting it in the sessions array
+            return this.#createSession(auth);
+          },
+          enableJsonResponse: httpConfig.enableJsonResponse,
+          eventStore: httpConfig.eventStore,
+          // In stateless mode, we don't track sessions
+          onClose: async () => {
+            // No session tracking in stateless mode
+          },
+          onConnect: async () => {
+            // No persistent session tracking in stateless mode
+            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 {
+        // Regular mode with session management
+        this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
+          createServer: async (request) => {
+            let auth: T | undefined;
 
-              // Enhanced readiness check endpoint
-              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);
+            if (this.#authenticate) {
+              auth = await this.#authenticate(request);
             }
-          }
 
-          // Handle OAuth well-known endpoints
-          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;
-            }
+            return this.#createSession(auth);
+          },
+          enableJsonResponse: httpConfig.enableJsonResponse,
+          eventStore: httpConfig.eventStore,
+          onClose: async (session) => {
+            this.emit("disconnect", {
+              session: session as FastMCPSession<FastMCPSessionAuth>,
+            });
+          },
+          onConnect: async (session) => {
+            this.#sessions.push(session);
 
-            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;
-            }
-          }
+            console.info(`[FastMCP info] HTTP Stream session established`);
 
-          // If the request was not handled above, return 404
-          res.writeHead(404).end();
-        },
-        port: httpConfig.port,
-        streamEndpoint: httpConfig.endpoint,
-      });
+            this.emit("connect", {
+              session: session as FastMCPSession<FastMCPSessionAuth>,
+            });
+          },
 
-      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)`,
-      );
+          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");
     }
@@ -2063,12 +2145,153 @@ export class FastMCP<
     }
   }
 
+  /**
+   * Creates a new FastMCPSession instance with the current configuration.
+   * Used both for regular sessions and stateless requests.
+   */
+  #createSession(auth?: T): FastMCPSession<T> {
+    const allowedTools = auth
+      ? this.#tools.filter((tool) =>
+          tool.canAccess ? tool.canAccess(auth) : true,
+        )
+      : this.#tools;
+    return new FastMCPSession<T>({
+      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: http.IncomingMessage,
+    res: http.ServerResponse,
+    isStateless = false,
+  ) => {
+    const healthConfig = this.#options.health ?? {};
+
+    const enabled =
+      healthConfig.enabled === undefined ? 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 ?? "✓ Ok");
+
+          return;
+        }
+
+        // Enhanced readiness check endpoint
+        if (req.method === "GET" && url.pathname === "/ready") {
+          if (isStateless) {
+            // In stateless mode, we're always ready if the server is running
+            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);
+      }
+    }
+
+    // Handle OAuth well-known endpoints
+    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;
+      }
+    }
+
+    // If the request was not handled above, return 404
+    res.writeHead(404).end();
+  };
   #parseRuntimeConfig(
     overrides?: Partial<{
       httpStream: {
         enableJsonResponse?: boolean;
         endpoint?: `/${string}`;
         port: number;
+        stateless?: boolean;
       };
       transportType: "httpStream" | "stdio";
     }>,
@@ -2079,6 +2302,7 @@ export class FastMCP<
           endpoint: `/${string}`;
           eventStore?: EventStore;
           port: number;
+          stateless?: boolean;
         };
         transportType: "httpStream";
       }
@@ -2095,10 +2319,12 @@ export class FastMCP<
     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;
 
     // Overrides > CLI > env > defaults
     const transportType =
@@ -2115,12 +2341,18 @@ export class FastMCP<
         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: endpoint as `/${string}`,
           port,
+          stateless,
         },
         transportType: "httpStream" as const,
       };

package/src/examples/oauth-server.ts

@@ -46,12 +46,24 @@ const server = new FastMCP({
     },
     enabled: true,
     protectedResource: {
+      authorizationDetailsTypesSupported: [
+        "payment_initiation",
+        "account_access",
+      ],
       authorizationServers: ["https://auth.example.com"],
       bearerMethodsSupported: ["header"],
+      dpopBoundAccessTokensRequired: false,
+      dpopSigningAlgValuesSupported: ["ES256", "RS256"],
       jwksUri: "https://oauth-example-server.example.com/.well-known/jwks.json",
       resource: "mcp://oauth-example-server",
       resourceDocumentation: "https://docs.example.com/mcp-api",
+      resourceName: "OAuth Example API",
       resourcePolicyUri: "https://example.com/resource-policy",
+      resourceSigningAlgValuesSupported: ["RS256", "ES256"],
+      resourceTosUri: "https://example.com/terms-of-service",
+      scopesSupported: ["read", "write", "admin"],
+      serviceDocumentation: "https://developer.example.com/api-docs",
+      tlsClientCertificateBoundAccessTokens: false,
     },
   },
   version: "1.0.0",