fastmcp 4.3.2 → 4.5.0

package/README.md

@@ -139,6 +139,8 @@ This will start the server and listen for HTTP streaming connections on `http://
 
 > **Note:** You can also customize the endpoint path using the `httpStream.endpoint` option (default is `/mcp`).
 
+> **Note:** To serve HTTP streaming and built-in OAuth routes under an issuer path, set `httpStream.basePath` (for example, `/issuer1`). This exposes authorization server metadata at `/.well-known/oauth-authorization-server/issuer1` per RFC 8414.
+
 > **Note:** This also starts an SSE server on `http://localhost:8080/sse`.
 
 You can connect to these servers using the appropriate client transport.
@@ -1327,6 +1329,23 @@ async load() {
 }
 ```
 
+`load` also receives `auth` (the value returned by your `authenticate` function, if any) and a `context` object as its second and third arguments. `context` mirrors the `client`, `log`, `session`, and `sessionId` fields available to `tool.execute` (see [Session ID and Request ID Tracking](#session-id-and-request-id-tracking)); `reportProgress` and `streamContent` are not included since they are tied to a tool call's progress token:
+
+```ts
+server.addResource({
+  uri: "file:///logs/app.log",
+  name: "Application Logs",
+  mimeType: "text/plain",
+  async load(auth, context) {
+    context.log.info("loading application logs", { requestedBy: auth?.userId });
+
+    return {
+      text: await readLogFile(),
+    };
+  },
+});
+```
+
 ### Resource templates
 
 You can also define resource templates:
@@ -1351,6 +1370,8 @@ server.addResourceTemplate({
 });
 ```
 
+Like plain resources, `load` also receives `auth` and `context` as its second and third arguments (see [Resources](#resources)).
+
 #### Resource template argument auto-completion
 
 Provide `complete` functions for resource template arguments to enable automatic completion:
@@ -1515,6 +1536,27 @@ server.addPrompt({
 });
 ```
 
+Like resources, `load` also receives `auth` and `context` as its second and third arguments (see [Resources](#resources)):
+
+```ts
+server.addPrompt({
+  name: "git-commit",
+  description: "Generate a Git commit message",
+  arguments: [
+    {
+      name: "changes",
+      description: "Git diff or description of changes",
+      required: true,
+    },
+  ],
+  load: async (args, auth, context) => {
+    context.log.debug("generating git commit prompt", { user: auth?.userId });
+
+    return `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`;
+  },
+});
+```
+
 #### Prompt argument auto-completion
 
 Prompts can provide auto-completion for their arguments:
@@ -1923,9 +1965,29 @@ const server = new FastMCP({
 });
 ```
 
+If your MCP server is published below an issuer path, configure the HTTP
+stream base path as well:
+
+```ts
+server.start({
+  transportType: "httpStream",
+  httpStream: {
+    basePath: "/issuer1",
+    endpoint: "/mcp",
+    port: 8080,
+  },
+});
+```
+
+With this configuration, FastMCP serves the issuer-path authorization server
+metadata at `/.well-known/oauth-authorization-server/issuer1`, while protected
+resource metadata remains available for the MCP endpoint at
+`/.well-known/oauth-protected-resource/issuer1/mcp`.
+
 This configuration automatically exposes OAuth discovery endpoints:
 
 - `/.well-known/oauth-authorization-server` - Authorization server metadata (RFC 8414)
+- `/.well-known/oauth-authorization-server<basePath>` - Authorization server metadata when `httpStream.basePath` is set (RFC 8414 Section 3)
 - `/.well-known/oauth-protected-resource` - Protected resource metadata (RFC 9728)
 - `/.well-known/oauth-protected-resource<endpoint>` - Protected resource metadata at sub-path (MCP 2025-11-25)
 

package/dist/FastMCP.cjs

@@ -7,7 +7,7 @@
 
 
 
-var _chunkUYG7NPM6cjs = require('./chunk-UYG7NPM6.cjs');
+var _chunkBJF2JTTEcjs = require('./chunk-BJF2JTTE.cjs');
 
 
 
@@ -41,5 +41,5 @@ var _chunkIX3HKAX4cjs = require('./chunk-IX3HKAX4.cjs');
 
 
 
-exports.AuthProvider = _chunkIX3HKAX4cjs.AuthProvider; exports.AzureProvider = _chunkIX3HKAX4cjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkUYG7NPM6cjs.DiscoveryDocumentCache; exports.FastMCP = _chunkUYG7NPM6cjs.FastMCP; exports.FastMCPSession = _chunkUYG7NPM6cjs.FastMCPSession; exports.GitHubProvider = _chunkIX3HKAX4cjs.GitHubProvider; exports.GoogleProvider = _chunkIX3HKAX4cjs.GoogleProvider; exports.OAuthProvider = _chunkIX3HKAX4cjs.OAuthProvider; exports.ServerState = _chunkUYG7NPM6cjs.ServerState; exports.UnexpectedStateError = _chunkUYG7NPM6cjs.UnexpectedStateError; exports.UserError = _chunkUYG7NPM6cjs.UserError; exports.audioContent = _chunkUYG7NPM6cjs.audioContent; exports.getAuthSession = _chunkIX3HKAX4cjs.getAuthSession; exports.imageContent = _chunkUYG7NPM6cjs.imageContent; exports.requireAll = _chunkIX3HKAX4cjs.requireAll; exports.requireAny = _chunkIX3HKAX4cjs.requireAny; exports.requireAuth = _chunkIX3HKAX4cjs.requireAuth; exports.requireRole = _chunkIX3HKAX4cjs.requireRole; exports.requireScopes = _chunkIX3HKAX4cjs.requireScopes;
+exports.AuthProvider = _chunkIX3HKAX4cjs.AuthProvider; exports.AzureProvider = _chunkIX3HKAX4cjs.AzureProvider; exports.DiscoveryDocumentCache = _chunkBJF2JTTEcjs.DiscoveryDocumentCache; exports.FastMCP = _chunkBJF2JTTEcjs.FastMCP; exports.FastMCPSession = _chunkBJF2JTTEcjs.FastMCPSession; exports.GitHubProvider = _chunkIX3HKAX4cjs.GitHubProvider; exports.GoogleProvider = _chunkIX3HKAX4cjs.GoogleProvider; exports.OAuthProvider = _chunkIX3HKAX4cjs.OAuthProvider; exports.ServerState = _chunkBJF2JTTEcjs.ServerState; exports.UnexpectedStateError = _chunkBJF2JTTEcjs.UnexpectedStateError; exports.UserError = _chunkBJF2JTTEcjs.UserError; exports.audioContent = _chunkBJF2JTTEcjs.audioContent; exports.getAuthSession = _chunkIX3HKAX4cjs.getAuthSession; exports.imageContent = _chunkBJF2JTTEcjs.imageContent; exports.requireAll = _chunkIX3HKAX4cjs.requireAll; exports.requireAny = _chunkIX3HKAX4cjs.requireAny; exports.requireAuth = _chunkIX3HKAX4cjs.requireAuth; exports.requireRole = _chunkIX3HKAX4cjs.requireRole; exports.requireScopes = _chunkIX3HKAX4cjs.requireScopes;
 //# sourceMappingURL=FastMCP.cjs.map

package/dist/FastMCP.d.cts

@@ -117,6 +117,14 @@ type Context<T extends FastMCPSessionAuth> = {
 type Extra = unknown;
 type Extras = Record<string, Extra>;
 type Literal = boolean | null | number | string | undefined;
+/**
+ * Context passed to `load` for resources, resource templates, and prompts.
+ *
+ * This is a subset of the tool execution {@link Context}. `reportProgress`
+ * and `streamContent` are tied to a tool call's progress token / streaming
+ * notification and are not available outside of `tool.execute`.
+ */
+type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "streamContent">;
 type Progress = {
     /**
      * The progress thus far. This should increase every time progress is made, even if the total is unknown.
@@ -182,7 +190,7 @@ type InputPrompt<T extends FastMCPSessionAuth = FastMCPSessionAuth, Arguments ex
     arguments?: InputPromptArgument<T>[];
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: Args, auth?: T) => Promise<PromptResult>;
+    load: (args: Args, auth?: T, context?: LoadContext<T>) => Promise<PromptResult>;
     name: string;
 };
 type InputPromptArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> = Readonly<{
@@ -196,7 +204,7 @@ type InputResourceTemplate<T extends FastMCPSessionAuth, Arguments extends Input
     arguments: Arguments;
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T) => Promise<ResourceResult | ResourceResult[]>;
+    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T, context?: LoadContext<T>) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uriTemplate: string;
@@ -212,7 +220,7 @@ type Prompt<T extends FastMCPSessionAuth = FastMCPSessionAuth, Arguments extends
     arguments?: PromptArgument<T>[];
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: Args, auth?: T) => Promise<PromptResult>;
+    load: (args: Args, auth?: T, context?: LoadContext<T>) => Promise<PromptResult>;
     name: string;
 };
 type PromptArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> = Readonly<{
@@ -234,7 +242,7 @@ type PromptResult = Pick<GetPromptResult, "messages"> | string;
 type Resource<T extends FastMCPSessionAuth> = {
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (auth?: T) => Promise<ResourceResult | ResourceResult[]>;
+    load: (auth?: T, context?: LoadContext<T>) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uri: string;
@@ -252,7 +260,7 @@ type ResourceTemplate<T extends FastMCPSessionAuth, Arguments extends ResourceTe
     arguments: Arguments;
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T) => Promise<ResourceResult | ResourceResult[]>;
+    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T, context?: LoadContext<T>) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uriTemplate: string;
@@ -861,6 +869,7 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
      */
     start(options?: Partial<{
         httpStream: {
+            basePath?: `/${string}`;
             cors?: boolean | CorsOptions;
             enableJsonResponse?: boolean;
             endpoint?: `/${string}`;
@@ -880,4 +889,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
     stop(): Promise<void>;
 }
 
-export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };
+export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };

package/dist/FastMCP.d.ts

@@ -117,6 +117,14 @@ type Context<T extends FastMCPSessionAuth> = {
 type Extra = unknown;
 type Extras = Record<string, Extra>;
 type Literal = boolean | null | number | string | undefined;
+/**
+ * Context passed to `load` for resources, resource templates, and prompts.
+ *
+ * This is a subset of the tool execution {@link Context}. `reportProgress`
+ * and `streamContent` are tied to a tool call's progress token / streaming
+ * notification and are not available outside of `tool.execute`.
+ */
+type LoadContext<T extends FastMCPSessionAuth> = Omit<Context<T>, "reportProgress" | "streamContent">;
 type Progress = {
     /**
      * The progress thus far. This should increase every time progress is made, even if the total is unknown.
@@ -182,7 +190,7 @@ type InputPrompt<T extends FastMCPSessionAuth = FastMCPSessionAuth, Arguments ex
     arguments?: InputPromptArgument<T>[];
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: Args, auth?: T) => Promise<PromptResult>;
+    load: (args: Args, auth?: T, context?: LoadContext<T>) => Promise<PromptResult>;
     name: string;
 };
 type InputPromptArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> = Readonly<{
@@ -196,7 +204,7 @@ type InputResourceTemplate<T extends FastMCPSessionAuth, Arguments extends Input
     arguments: Arguments;
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T) => Promise<ResourceResult | ResourceResult[]>;
+    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T, context?: LoadContext<T>) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uriTemplate: string;
@@ -212,7 +220,7 @@ type Prompt<T extends FastMCPSessionAuth = FastMCPSessionAuth, Arguments extends
     arguments?: PromptArgument<T>[];
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: Args, auth?: T) => Promise<PromptResult>;
+    load: (args: Args, auth?: T, context?: LoadContext<T>) => Promise<PromptResult>;
     name: string;
 };
 type PromptArgument<T extends FastMCPSessionAuth = FastMCPSessionAuth> = Readonly<{
@@ -234,7 +242,7 @@ type PromptResult = Pick<GetPromptResult, "messages"> | string;
 type Resource<T extends FastMCPSessionAuth> = {
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (auth?: T) => Promise<ResourceResult | ResourceResult[]>;
+    load: (auth?: T, context?: LoadContext<T>) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uri: string;
@@ -252,7 +260,7 @@ type ResourceTemplate<T extends FastMCPSessionAuth, Arguments extends ResourceTe
     arguments: Arguments;
     complete?: (name: string, value: string, auth?: T) => Promise<Completion>;
     description?: string;
-    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T) => Promise<ResourceResult | ResourceResult[]>;
+    load: (args: ResourceTemplateArgumentsToObject<Arguments>, auth?: T, context?: LoadContext<T>) => Promise<ResourceResult | ResourceResult[]>;
     mimeType?: string;
     name: string;
     uriTemplate: string;
@@ -861,6 +869,7 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
      */
     start(options?: Partial<{
         httpStream: {
+            basePath?: `/${string}`;
             cors?: boolean | CorsOptions;
             enableJsonResponse?: boolean;
             endpoint?: `/${string}`;
@@ -880,4 +889,4 @@ declare class FastMCP<T extends FastMCPSessionAuth = FastMCPSessionAuth> extends
     stop(): Promise<void>;
 }
 
-export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };
+export { type AudioContent, AuthProvider, type Content, type ContentResult, type Context, DiscoveryDocumentCache, FastMCP, type FastMCPEvents, type FastMCPRequest, type FastMCPResponse, FastMCPSession, type FastMCPSessionAuth, type FastMCPSessionEvents, type HTTPMethod, type ImageContent, type InputPrompt, type InputPromptArgument, type LoadContext, type Logger, type LoggingLevel, OAuthSession, type Progress, type Prompt, type PromptArgument, type Resource, type ResourceContent, type ResourceResult, type ResourceTemplate, type ResourceTemplateArgument, type RouteHandler, type RouteOptions, type SSEServer, type SerializableValue, type ServerOptions, ServerState, type TextContent, type Tool, type ToolParameters, UnexpectedStateError, UserError, audioContent, imageContent };

package/dist/FastMCP.js

@@ -7,7 +7,7 @@ import {
   UserError,
   audioContent,
   imageContent
-} from "./chunk-LWU5CQGW.js";
+} from "./chunk-BTMLQWIR.js";
 import {
   AuthProvider,
   AzureProvider,