fastmcp 3.6.2 → 3.8.0

package/README.md

@@ -1164,6 +1164,110 @@ server.addTool({
 });
 ```
 
+#### OAuth Support
+
+FastMCP includes built-in support for OAuth discovery endpoints, supporting both **MCP Specification 2025-03-26** and **MCP Specification 2025-06-18** for OAuth integration. This makes it easy to integrate with OAuth authorization flows by providing standard discovery endpoints that comply with RFC 8414 (OAuth 2.0 Authorization Server Metadata) and RFC 9470 (OAuth 2.0 Protected Resource Metadata):
+
+```ts
+import { FastMCP } from "fastmcp";
+import { buildGetJwks } from "get-jwks";
+import fastJwt from "fast-jwt";
+
+const server = new FastMCP({
+  name: "My Server",
+  version: "1.0.0",
+  oauth: {
+    enabled: true,
+    authorizationServer: {
+      issuer: "https://auth.example.com",
+      authorizationEndpoint: "https://auth.example.com/oauth/authorize",
+      tokenEndpoint: "https://auth.example.com/oauth/token",
+      jwksUri: "https://auth.example.com/.well-known/jwks.json",
+      responseTypesSupported: ["code"],
+    },
+    protectedResource: {
+      resource: "mcp://my-server",
+      authorizationServers: ["https://auth.example.com"],
+    },
+  },
+  authenticate: async (request) => {
+    const authHeader = request.headers.authorization;
+
+    if (!authHeader?.startsWith("Bearer ")) {
+      throw new Response(null, {
+        status: 401,
+        statusText: "Missing or invalid authorization header",
+      });
+    }
+
+    const token = authHeader.slice(7); // Remove 'Bearer ' prefix
+
+    // Validate OAuth JWT access token using OpenID Connect discovery
+    try {
+      // TODO: Cache the discovery document to avoid repeated requests
+      // Discover OAuth/OpenID configuration from well-known endpoint
+      const discoveryUrl =
+        "https://auth.example.com/.well-known/openid-configuration";
+      // Alternative: Use OAuth authorization server metadata endpoint
+      // const discoveryUrl = 'https://auth.example.com/.well-known/oauth-authorization-server';
+
+      const discoveryResponse = await fetch(discoveryUrl);
+      if (!discoveryResponse.ok) {
+        throw new Error("Failed to fetch OAuth discovery document");
+      }
+
+      const config = await discoveryResponse.json();
+      const jwksUri = config.jwks_uri;
+      const issuer = config.issuer;
+
+      // Create JWKS client for token verification using discovered endpoint
+      const getJwks = buildGetJwks({
+        jwksUrl: jwksUri,
+        cache: true,
+        rateLimit: true,
+      });
+
+      // Create JWT verifier with JWKS and discovered issuer
+      const verify = fastJwt.createVerifier({
+        key: async (token) => {
+          const { header } = fastJwt.decode(token, { complete: true });
+          const jwk = await getJwks.getJwk({
+            kid: header.kid,
+            alg: header.alg,
+          });
+          return jwk;
+        },
+        algorithms: ["RS256", "ES256"],
+        issuer: issuer,
+        audience: "mcp://my-server",
+      });
+
+      // Verify the JWT token
+      const payload = await verify(token);
+
+      return {
+        userId: payload.sub,
+        scope: payload.scope,
+        email: payload.email,
+        // Include other claims as needed
+      };
+    } catch (error) {
+      throw new Response(null, {
+        status: 401,
+        statusText: "Invalid OAuth token",
+      });
+    }
+  },
+});
+```
+
+This configuration automatically exposes OAuth discovery endpoints:
+
+- `/.well-known/oauth-authorization-server` - Authorization server metadata (RFC 8414)
+- `/.well-known/oauth-protected-resource` - Protected resource metadata (RFC 9470)
+
+For JWT token validation, you can use libraries like [`get-jwks`](https://github.com/nearform/get-jwks) and [`@fastify/jwt`](https://github.com/fastify/fastify-jwt) for OAuth JWT tokens.
+
 #### Passing Headers Through Context
 
 If you are exposing your MCP server via HTTP, you may wish to allow clients to supply sensitive keys via headers, which can then be passed along to APIs that your tools interact with, allowing each client to supply their own API keys. This can be done by capturing the HTTP headers in the `authenticate` section and storing them in the session to be referenced by the tools later.

package/dist/FastMCP.d.ts

@@ -1,4 +1,5 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { EventStore } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { ResourceLink, Root, ClientCapabilities, GetPromptResult, CreateMessageRequestSchema } from '@modelcontextprotocol/sdk/types.js';
@@ -116,44 +117,44 @@ type Completion = {
     total?: number;
     values: string[];
 };
-type ArgumentValueCompleter = (value: string) => Promise<Completion>;
-type InputPrompt<Arguments extends InputPromptArgument[] = InputPromptArgument[], Args = PromptArgumentsToObject<Arguments>> = {
-    arguments?: InputPromptArgument[];
+type ArgumentValueCompleter<T extends FastMCPSessionAuth = FastMCPSessionAuth> = (value: string, auth?: T) => Promise<Completion>;
+type InputPrompt<T extends FastMCPSessionAuth = FastMCPSessionAuth, Arguments extends InputPromptArgument<T>[] = InputPromptArgument<T>[], Args = PromptArgumentsToObject<Arguments>> = {
+    arguments?: InputPromptArgument<T>[];
     description?: string;
-    load: (args: Args) => Promise<PromptResult>;
+    load: (args: Args, auth?: T) => Promise<PromptResult>;
     name: string;
 };
-type InputPromptArgument = Readonly<{
-    complete?: ArgumentValueCompleter;
+type InputPromptArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> = Readonly<{
+    complete?: ArgumentValueCompleter<T>;
     description?: string;
     enum?: string[];
     name: string;
     required?: boolean;
 }>;
-type InputResourceTemplate<Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[]> = {
+type InputResourceTemplate<T extends FastMCPSessionAuth, Arguments extends InputResourceTemplateArgument<T>[] = InputResourceTemplateArgument<T>[]> = {
     arguments: Arguments;
     description?: string;
-    load: (args: ResourceTemplateArgumentsToObject<Arguments>) => Promise<ResourceResult | ResourceResult[]>;
+    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uriTemplate: string;
 };
-type InputResourceTemplateArgument = Readonly<{
-    complete?: ArgumentValueCompleter;
+type InputResourceTemplateArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> = Readonly<{
+    complete?: ArgumentValueCompleter<T>;
     description?: string;
     name: string;
     required?: boolean;
 }>;
 type LoggingLevel = "alert" | "critical" | "debug" | "emergency" | "error" | "info" | "notice" | "warning";
-type Prompt<Arguments extends PromptArgument[] = PromptArgument[], Args = PromptArgumentsToObject<Arguments>> = {
-    arguments?: PromptArgument[];
-    complete?: (name: string, value: string) => Promise<Completion>;
+type Prompt<T extends FastMCPSessionAuth = FastMCPSessionAuth, Arguments extends PromptArgument<T>[] = PromptArgument<T>[], Args = PromptArgumentsToObject<Arguments>> = {
+    arguments?: PromptArgument<T>[];
+    complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: Args) => Promise<PromptResult>;
+    load: (args: Args, auth?: T) => Promise<PromptResult>;
     name: string;
 };
-type PromptArgument = Readonly<{
-    complete?: ArgumentValueCompleter;
+type PromptArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> = Readonly<{
+    complete?: ArgumentValueCompleter<T>;
     description?: string;
     enum?: string[];
     name: string;
@@ -168,10 +169,10 @@ type PromptArgumentsToObject<T extends {
     }>["required"] extends true ? string : string | undefined;
 };
 type PromptResult = Pick<GetPromptResult, "messages"> | string;
-type Resource = {
-    complete?: (name: string, value: string) => Promise<Completion>;
+type Resource<T extends FastMCPSessionAuth> = {
+    complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: () => Promise<ResourceResult | ResourceResult[]>;
+    load: (auth?: T) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uri: string;
@@ -185,17 +186,17 @@ type ResourceResult = {
     text: string;
     uri?: string;
 };
-type ResourceTemplate<Arguments extends ResourceTemplateArgument[] = ResourceTemplateArgument[]> = {
+type ResourceTemplate<T extends FastMCPSessionAuth, Arguments extends ResourceTemplateArgument<T>[] = ResourceTemplateArgument<T>[]> = {
     arguments: Arguments;
-    complete?: (name: string, value: string) => Promise<Completion>;
+    complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: ResourceTemplateArgumentsToObject<Arguments>) => Promise<ResourceResult | ResourceResult[]>;
+    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uriTemplate: string;
 };
-type ResourceTemplateArgument = Readonly<{
-    complete?: ArgumentValueCompleter;
+type ResourceTemplateArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> = Readonly<{
+    complete?: ArgumentValueCompleter<T>;
     description?: string;
     name: string;
     required?: boolean;
@@ -247,6 +248,67 @@ type ServerOptions<T extends FastMCPSessionAuth> = {
     };
     instructions?: string;
     name: string;
+    /**
+     * Configuration for OAuth well-known discovery endpoints that can be exposed
+     * when the server is running using HTTP-based transports (SSE or HTTP Stream).
+     * When enabled, the server will respond to requests for OAuth discovery endpoints
+     * with the configured metadata.
+     *
+     * The endpoints are only added when the server is started with
+     * `transportType: "httpStream"` – they are ignored for the stdio transport.
+     * Both SSE and HTTP Stream transports support OAuth endpoints.
+     */
+    oauth?: {
+        /**
+         * OAuth Authorization Server metadata for /.well-known/oauth-authorization-server
+         *
+         * This endpoint follows RFC 8414 (OAuth 2.0 Authorization Server Metadata)
+         * and provides metadata about the OAuth 2.0 authorization server.
+         *
+         * Required by MCP Specification 2025-03-26
+         */
+        authorizationServer?: {
+            authorizationEndpoint: string;
+            codeChallengeMethodsSupported?: string[];
+            dpopSigningAlgValuesSupported?: string[];
+            grantTypesSupported?: string[];
+            introspectionEndpoint?: string;
+            issuer: string;
+            jwksUri?: string;
+            opPolicyUri?: string;
+            opTosUri?: string;
+            registrationEndpoint?: string;
+            responseModesSupported?: string[];
+            responseTypesSupported: string[];
+            revocationEndpoint?: string;
+            scopesSupported?: string[];
+            serviceDocumentation?: string;
+            tokenEndpoint: string;
+            tokenEndpointAuthMethodsSupported?: string[];
+            tokenEndpointAuthSigningAlgValuesSupported?: string[];
+            uiLocalesSupported?: string[];
+        };
+        /**
+         * Whether OAuth discovery endpoints should be enabled.
+         */
+        enabled: boolean;
+        /**
+         * 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.
+         *
+         * Required by MCP Specification 2025-06-18
+         */
+        protectedResource?: {
+            authorizationServers: string[];
+            bearerMethodsSupported?: string[];
+            jwksUri?: string;
+            resource: string;
+            resourceDocumentation?: string;
+            resourcePolicyUri?: string;
+        };
+    };
     ping?: {
         /**
          * Whether ping should be enabled by default.
@@ -327,6 +389,7 @@ type ToolAnnotations = {
 declare const FastMCPSessionEventEmitterBase: {
     new (): StrictEventEmitter<EventEmitter, FastMCPSessionEvents>;
 };
+type Authenticate<T> = (request: http.IncomingMessage) => Promise<T>;
 type FastMCPSessionAuth = Record<string, unknown> | undefined;
 declare class FastMCPSessionEventEmitter extends FastMCPSessionEventEmitterBase {
 }
@@ -342,9 +405,9 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
         instructions?: string;
         name: string;
         ping?: ServerOptions<T>["ping"];
-        prompts: Prompt[];
-        resources: Resource[];
-        resourcesTemplates: InputResourceTemplate[];
+        prompts: Prompt<T>[];
+        resources: Resource<T>[];
+        resourcesTemplates: InputResourceTemplate<T>[];
         roots?: ServerOptions<T>["roots"];
         tools: Tool<T>[];
         transportType?: "httpStream" | "stdio";
@@ -369,10 +432,9 @@ declare class FastMCPSession<T extends FastMCPSessionAuth = FastMCPSessionAuth>
 declare const FastMCPEventEmitterBase: {
     new (): StrictEventEmitter<EventEmitter, FastMCPEvents<FastMCPSessionAuth>>;
 };
-type Authenticate<T> = (request: http.IncomingMessage) => Promise<T>;
 declare class FastMCPEventEmitter extends FastMCPEventEmitterBase {
 }
-declare class FastMCP<T extends Record<string, unknown> | undefined = undefined> extends FastMCPEventEmitter {
+declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends FastMCPEventEmitter {
     #private;
     options: ServerOptions<T>;
     get sessions(): FastMCPSession<T>[];
@@ -380,15 +442,15 @@ declare class FastMCP<T extends Record<string, unknown> | undefined = undefined>
     /**
      * Adds a prompt to the server.
      */
-    addPrompt<const Args extends InputPromptArgument[]>(prompt: InputPrompt<Args>): void;
+    addPrompt<const Args extends InputPromptArgument<T>[]>(prompt: InputPrompt<T, Args>): void;
     /**
      * Adds a resource to the server.
      */
-    addResource(resource: Resource): void;
+    addResource(resource: Resource<T>): void;
     /**
      * Adds a resource template to the server.
      */
-    addResourceTemplate<const Args extends InputResourceTemplateArgument[]>(resource: InputResourceTemplate<Args>): void;
+    addResourceTemplate<const Args extends InputResourceTemplateArgument[]>(resource: InputResourceTemplate<T, Args>): void;
     /**
      * Adds a tool to the server.
      */
@@ -406,6 +468,7 @@ declare class FastMCP<T extends Record<string, unknown> | undefined = undefined>
     start(options?: Partial<{
         httpStream: {
             endpoint?: `/${string}`;
+            eventStore?: EventStore;
             port: number;
         };
         transportType: "httpStream" | "stdio";

package/dist/FastMCP.js

@@ -456,9 +456,9 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
     }
     const prompt = {
       ...inputPrompt,
-      complete: async (name, value) => {
+      complete: async (name, value, auth) => {
         if (completers[name]) {
-          return await completers[name](value);
+          return await completers[name](value, auth);
         }
         if (fuseInstances[name]) {
           const result = fuseInstances[name].search(value);
@@ -486,9 +486,9 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
     }
     const resourceTemplate = {
       ...inputResourceTemplate,
-      complete: async (name, value) => {
+      complete: async (name, value, auth) => {
         if (completers[name]) {
-          return await completers[name](value);
+          return await completers[name](value, auth);
         }
         return {
           values: []
@@ -516,7 +516,8 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
         const completion = CompletionZodSchema.parse(
           await prompt.complete(
             request.params.argument.name,
-            request.params.argument.value
+            request.params.argument.value,
+            this.#auth
           )
         );
         return {
@@ -546,7 +547,8 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
         const completion = CompletionZodSchema.parse(
           await resource.complete(
             request.params.argument.name,
-            request.params.argument.value
+            request.params.argument.value,
+            this.#auth
           )
         );
         return {
@@ -603,7 +605,10 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
       }
       let result;
       try {
-        result = await prompt.load(args);
+        result = await prompt.load(
+          args,
+          this.#auth
+        );
       } catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
         throw new McpError(
@@ -657,7 +662,7 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
                 continue;
               }
               const uri = uriTemplate.fill(match);
-              const result = await resourceTemplate.load(match);
+              const result = await resourceTemplate.load(match, this.#auth);
               const resources2 = Array.isArray(result) ? result : [result];
               return {
                 contents: resources2.map((resource2) => ({
@@ -679,7 +684,7 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
           }
           let maybeArrayResult;
           try {
-            maybeArrayResult = await resource.load();
+            maybeArrayResult = await resource.load(this.#auth);
           } catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
             throw new McpError(
@@ -935,6 +940,17 @@ ${e instanceof Error ? e.stack : JSON.stringify(e)}`
     });
   }
 };
+function camelToSnakeCase(str) {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+function convertObjectToSnakeCase(obj) {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const snakeKey = camelToSnakeCase(key);
+    result[snakeKey] = value;
+  }
+  return result;
+}
 var FastMCPEventEmitterBase = EventEmitter;
 var FastMCPEventEmitter = class extends FastMCPEventEmitterBase {
 };
@@ -1085,6 +1101,7 @@ var FastMCP = class extends FastMCPEventEmitter {
             version: this.#options.version
           });
         },
+        eventStore: httpConfig.eventStore,
         onClose: async (session) => {
           this.emit("disconnect", {
             session
@@ -1130,6 +1147,28 @@ var FastMCP = class extends FastMCPEventEmitter {
               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();
         },
         port: httpConfig.port,