fastmcp 3.28.0 → 3.30.0

package/README.md

@@ -1230,90 +1230,193 @@ server.addPrompt({
 
 ### Authentication
 
-FastMCP supports session-based authentication, allowing you to secure your server and control access to its features.
+FastMCP supports OAuth 2.1 authentication with pre-configured providers, allowing you to secure your server with minimal setup.
 
-> [!NOTE]
-> For more granular control over which tools are available to authenticated users, see the [Tool Authorization](#tool-authorization) section.
-
-To enable authentication, provide an `authenticate` function in the server options. This function receives the incoming HTTP request and should return a promise that resolves with the authentication context.
+#### OAuth with Pre-configured Providers
 
-If authentication fails, the function should throw a `Response` object, which will be sent to the client.
+Use the `auth` option with a provider to enable OAuth authentication:
 
 ```ts
+import { FastMCP, getAuthSession, GoogleProvider, requireAuth } from "fastmcp";
+
 const server = new FastMCP({
+  auth: new GoogleProvider({
+    baseUrl: "https://your-server.com",
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  }),
   name: "My Server",
   version: "1.0.0",
-  authenticate: (request) => {
-    const apiKey = request.headers["x-api-key"];
-
-    if (apiKey !== "123") {
-      throw new Response(null, {
-        status: 401,
-        statusText: "Unauthorized",
-      });
-    }
+});
 
-    // Whatever you return here will be accessible in the `context.session` object.
-    return {
-      id: 1,
-    };
+server.addTool({
+  canAccess: requireAuth,
+  description: "Get user profile",
+  execute: async (_args, { session }) => {
+    const { accessToken } = getAuthSession(session);
+    const response = await fetch(
+      "https://www.googleapis.com/oauth2/v2/userinfo",
+      {
+        headers: { Authorization: `Bearer ${accessToken}` },
+      },
+    );
+    return JSON.stringify(await response.json());
   },
+  name: "get-profile",
 });
 ```
 
-Now you can access the authenticated session data in your tools:
+**Available Providers:**
+
+| Provider         | Import    | Use Case               |
+| :--------------- | :-------- | :--------------------- |
+| `GoogleProvider` | `fastmcp` | Google OAuth           |
+| `GitHubProvider` | `fastmcp` | GitHub OAuth           |
+| `AzureProvider`  | `fastmcp` | Azure/Entra ID         |
+| `OAuthProvider`  | `fastmcp` | Any OAuth 2.0 provider |
+
+**Generic OAuth Provider** (for SAP, Auth0, Okta, etc.):
 
 ```ts
-server.addTool({
-  name: "sayHello",
-  execute: async (args, { session }) => {
-    return `Hello, ${session.id}!`;
-  },
+import { FastMCP, OAuthProvider } from "fastmcp";
+
+const server = new FastMCP({
+  auth: new OAuthProvider({
+    authorizationEndpoint: process.env.OAUTH_AUTH_ENDPOINT!,
+    baseUrl: "https://your-server.com",
+    clientId: process.env.OAUTH_CLIENT_ID!,
+    clientSecret: process.env.OAUTH_CLIENT_SECRET!,
+    scopes: ["openid", "profile"],
+    tokenEndpoint: process.env.OAUTH_TOKEN_ENDPOINT!,
+  }),
+  name: "My Server",
+  version: "1.0.0",
 });
 ```
 
 #### Tool Authorization
 
-You can control which tools are available to authenticated users by adding an optional `canAccess` function to a tool's definition. This function receives the authentication context and should return `true` if the user is allowed to access the tool.
+Control tool access using the `canAccess` property with built-in helper functions:
 
-If `canAccess` is not provided, the tool is accessible to all authenticated users by default. If no authentication is configured on the server, all tools are available to all clients.
+```ts
+import {
+  requireAuth,
+  requireScopes,
+  requireRole,
+  requireAll,
+  requireAny,
+  getAuthSession,
+} from "fastmcp";
+
+// Require any authenticated user
+server.addTool({
+  canAccess: requireAuth,
+  name: "user-tool",
+  // ...
+});
 
-**Example:**
+// Require specific OAuth scopes
+server.addTool({
+  canAccess: requireScopes("read:user", "write:data"),
+  name: "scoped-tool",
+  // ...
+});
+
+// Require specific role
+server.addTool({
+  canAccess: requireRole("admin"),
+  name: "admin-tool",
+  // ...
+});
+
+// Combine with AND logic
+server.addTool({
+  canAccess: requireAll(requireAuth, requireRole("admin")),
+  name: "admin-only",
+  // ...
+});
+
+// Combine with OR logic
+server.addTool({
+  canAccess: requireAny(requireRole("admin"), requireRole("moderator")),
+  name: "staff-tool",
+  // ...
+});
+```
+
+**Custom Authorization:**
+
+For custom logic, pass a function directly:
 
 ```typescript
-const server = new FastMCP<{ role: "admin" | "user" }>({
-  authenticate: async (request) => {
-    const role = request.headers["x-role"] as string;
-    return { role: role === "admin" ? "admin" : "user" };
+server.addTool({
+  name: "custom-auth-tool",
+  canAccess: (auth) =>
+    auth?.role === "admin" && auth?.department === "engineering",
+  execute: async () => "Access granted!",
+});
+```
+
+**Extracting Session Data:**
+
+Use `getAuthSession` for type-safe access to the OAuth session in your tool execute functions:
+
+```typescript
+import { getAuthSession, GoogleSession } from "fastmcp";
+
+server.addTool({
+  canAccess: requireAuth,
+  name: "get-profile",
+  execute: async (_args, { session }) => {
+    // Type-safe destructuring (throws if not authenticated)
+    const { accessToken } = getAuthSession(session);
+
+    // Or with provider-specific typing:
+    // const { accessToken } = getAuthSession<GoogleSession>(session);
+
+    const response = await fetch("https://api.example.com/user", {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    return JSON.stringify(await response.json());
   },
+});
+```
+
+> **Note:** You can also access `session.accessToken` directly, but you must handle the case where `session` is undefined. The `getAuthSession` helper throws a clear error if the session is not authenticated, making it safer when used with `canAccess: requireAuth`.
+
+#### Custom Authentication
+
+For non-OAuth scenarios (API keys, custom tokens), use the `authenticate` option:
+
+```ts
+const server = new FastMCP({
   name: "My Server",
   version: "1.0.0",
-});
+  authenticate: (request) => {
+    const apiKey = request.headers["x-api-key"];
 
-server.addTool({
-  name: "admin-dashboard",
-  description: "An admin-only tool",
-  // Only users with the 'admin' role can see and execute this tool
-  canAccess: (auth) => auth?.role === "admin",
-  execute: async () => {
-    return "Welcome to the admin dashboard!";
+    if (apiKey !== "123") {
+      throw new Response(null, {
+        status: 401,
+        statusText: "Unauthorized",
+      });
+    }
+
+    return { id: 1, role: "user" };
   },
 });
 
 server.addTool({
-  name: "public-info",
-  description: "A tool available to everyone",
-  execute: async () => {
-    return "This is public information.";
+  name: "sayHello",
+  execute: async (args, { session }) => {
+    return `Hello, ${session.id}!`;
   },
 });
 ```
 
-In this example, only clients authenticating with the `admin` role will be able to list or call the `admin-dashboard` tool. The `public-info` tool will be available to all authenticated users.
-
 #### OAuth Proxy
 
-FastMCP includes a built-in **OAuth Proxy** that acts as a secure intermediary between MCP clients and upstream OAuth providers. The proxy handles the complete OAuth 2.1 authorization flow, including Dynamic Client Registration (DCR), PKCE, consent management, and token management with encryption and token swap patterns enabled by default.
+The `auth` option uses FastMCP's built-in **OAuth Proxy** that acts as a secure intermediary between MCP clients and upstream OAuth providers. The proxy handles the complete OAuth 2.1 authorization flow, including Dynamic Client Registration (DCR), PKCE, consent management, and token management with encryption and token swap patterns enabled by default.
 
 **Key Features:**
 
@@ -1325,6 +1428,34 @@ FastMCP includes a built-in **OAuth Proxy** that acts as a secure intermediary b
 
 **Quick Start:**
 
+```ts
+import { FastMCP, getAuthSession, GoogleProvider, requireAuth } from "fastmcp";
+
+const server = new FastMCP({
+  auth: new GoogleProvider({
+    baseUrl: "https://your-server.com",
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  }),
+  name: "My Server",
+  version: "1.0.0",
+});
+
+server.addTool({
+  canAccess: requireAuth,
+  name: "protected-tool",
+  execute: async (_args, { session }) => {
+    const { accessToken } = getAuthSession(session);
+    // Use accessToken to call upstream APIs
+    return "Authenticated!";
+  },
+});
+```
+
+**Advanced Configuration:**
+
+For more control over OAuth behavior, you can use the `oauth` option directly:
+
 ```ts
 import { FastMCP } from "fastmcp";
 import { GoogleProvider } from "fastmcp/auth";
@@ -1341,7 +1472,7 @@ const server = new FastMCP({
   oauth: {
     enabled: true,
     authorizationServer: authProxy.getAuthorizationServerMetadata(),
-    proxy: authProxy, // Routes automatically registered!
+    proxy: authProxy,
   },
 });
 ```

package/dist/FastMCP.cjs

@@ -1,4 +1,18 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/FastMCP.ts
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } } function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; } function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+
+
+
+
+
+
+
+
+
+var _chunk3MN6Z6V4cjs = require('./chunk-3MN6Z6V4.cjs');
+
+// src/FastMCP.ts
 var _indexjs = require('@modelcontextprotocol/sdk/server/index.js');
 var _stdiojs = require('@modelcontextprotocol/sdk/server/stdio.js');
 
@@ -560,6 +574,13 @@ ${error instanceof Error ? error.stack : JSON.stringify(error)}`
       );
     }
   }
+  /**
+   * Update the session's authentication context.
+   * Called by mcp-proxy when a new token is validated on subsequent requests.
+   */
+  updateAuth(auth) {
+    this.#auth = auth;
+  }
   waitForReady() {
     if (this.isReady) {
       return Promise.resolve();
@@ -1183,8 +1204,22 @@ var FastMCP = class extends FastMCPEventEmitter {
     super();
     this.options = options;
     this.#options = options;
-    this.#authenticate = options.authenticate;
     this.#logger = options.logger || console;
+    if (options.auth) {
+      if (!options.authenticate) {
+        this.#authenticate = ((request) => options.auth.authenticate(request));
+      } else {
+        this.#authenticate = options.authenticate;
+      }
+      if (!options.oauth) {
+        this.#options = {
+          ...options,
+          oauth: options.auth.getOAuthConfig()
+        };
+      }
+    } else {
+      this.#authenticate = options.authenticate;
+    }
   }
   get serverState() {
     return this.#serverState;
@@ -1958,5 +1993,16 @@ var FastMCP = class extends FastMCPEventEmitter {
 
 
 
-exports.DiscoveryDocumentCache = DiscoveryDocumentCache; exports.FastMCP = FastMCP; exports.FastMCPSession = FastMCPSession; exports.ServerState = ServerState; exports.UnexpectedStateError = UnexpectedStateError; exports.UserError = UserError; exports.audioContent = audioContent; exports.imageContent = imageContent;
+
+
+
+
+
+
+
+
+
+
+
+exports.AuthProvider = _chunk3MN6Z6V4cjs.AuthProvider; exports.AzureProvider = _chunk3MN6Z6V4cjs.AzureProvider; exports.DiscoveryDocumentCache = DiscoveryDocumentCache; exports.FastMCP = FastMCP; exports.FastMCPSession = FastMCPSession; exports.GitHubProvider = _chunk3MN6Z6V4cjs.GitHubProvider; exports.GoogleProvider = _chunk3MN6Z6V4cjs.GoogleProvider; exports.OAuthProvider = _chunk3MN6Z6V4cjs.OAuthProvider; exports.ServerState = ServerState; exports.UnexpectedStateError = UnexpectedStateError; exports.UserError = UserError; exports.audioContent = audioContent; exports.getAuthSession = _chunk3MN6Z6V4cjs.getAuthSession; exports.imageContent = imageContent; exports.requireAll = _chunk3MN6Z6V4cjs.requireAll; exports.requireAny = _chunk3MN6Z6V4cjs.requireAny; exports.requireAuth = _chunk3MN6Z6V4cjs.requireAuth; exports.requireRole = _chunk3MN6Z6V4cjs.requireRole; exports.requireScopes = _chunk3MN6Z6V4cjs.requireScopes;
 //# sourceMappingURL=FastMCP.cjs.map