fastmcp 3.19.2 → 3.20.0

package/src/FastMCP.test.ts

@@ -2416,7 +2416,9 @@ test("provides auth to tools", async () => {
         warn: expect.any(Function),
       },
       reportProgress: expect.any(Function),
+      requestId: undefined,
       session: { id: 1 },
+      sessionId: expect.any(String),
       streamContent: expect.any(Function),
     },
   );
@@ -3783,7 +3785,8 @@ test("stateless mode handles authentication function throwing errors", async ()
     expect(response.status).toBe(401);
 
     const body = (await response.json()) as { error?: { message?: string } };
-    expect(body.error?.message).toContain("Unauthorized");
+    // The actual error message should be passed through
+    expect(body.error?.message).toContain("JWT validation service is down");
   } finally {
     await server.stop();
   }
@@ -3878,6 +3881,451 @@ test("stateless mode handles concurrent requests with authentication", async ()
   }
 });
 
+// Tests for GitHub Issue: FastMCP authentication fix
+// Testing the fix for session creation despite authentication failure
+
+test("authentication failure handling: should throw error when auth.authenticated is false", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP<{ authenticated: boolean; error?: string }>({
+    authenticate: async () => {
+      // Simulate authentication failure with { authenticated: false }
+      return { authenticated: false, error: "Invalid JWT token" };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async () => {
+      return "pong";
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    // Send a raw HTTP request that should be rejected
+    const response = await fetch(`http://localhost:${port}/mcp`, {
+      body: JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "initialize",
+        params: {
+          capabilities: {},
+          clientInfo: { name: "test", version: "1.0" },
+          protocolVersion: "2024-11-05",
+        },
+      }),
+      headers: {
+        Accept: "application/json, text/event-stream",
+        Authorization: "Bearer invalid.jwt.token",
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    });
+
+    // Should return 401 Unauthorized (handled by mcp-proxy)
+    expect(response.status).toBe(401);
+
+    const body = (await response.json()) as {
+      error?: { code?: number; message?: string };
+    };
+    expect(body.error?.message).toContain("Invalid JWT token");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("authentication failure handling: should create session when auth.authenticated is true", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP<{
+    authenticated: boolean;
+    session?: { userId: string };
+  }>({
+    authenticate: async () => {
+      // Simulate successful authentication
+      return { authenticated: true, session: { userId: "123" } };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async (_args, context) => {
+      return `User: ${context.session?.session?.userId}`;
+    },
+    name: "whoami",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    const client = new Client(
+      {
+        name: "Test client",
+        version: "1.0.0",
+      },
+      {
+        capabilities: {},
+      },
+    );
+
+    const transport = new StreamableHTTPClientTransport(
+      new URL(`http://localhost:${port}/mcp`),
+    );
+
+    await client.connect(transport);
+
+    const result = await client.callTool({
+      arguments: {},
+      name: "whoami",
+    });
+
+    expect(result.content).toEqual([
+      {
+        text: "User: 123",
+        type: "text",
+      },
+    ]);
+
+    await client.close();
+  } finally {
+    await server.stop();
+  }
+});
+
+test("authentication failure handling: should create session when auth is null/undefined (anonymous)", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP({
+    // No authenticate function - anonymous access
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async (_args, context) => {
+      return `Anonymous: ${context.session === undefined}`;
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    const client = new Client(
+      {
+        name: "Test client",
+        version: "1.0.0",
+      },
+      {
+        capabilities: {},
+      },
+    );
+
+    const transport = new StreamableHTTPClientTransport(
+      new URL(`http://localhost:${port}/mcp`),
+    );
+
+    await client.connect(transport);
+
+    const result = await client.callTool({
+      arguments: {},
+      name: "ping",
+    });
+
+    expect(result.content).toEqual([
+      {
+        text: "Anonymous: true",
+        type: "text",
+      },
+    ]);
+
+    await client.close();
+  } finally {
+    await server.stop();
+  }
+});
+
+test("authentication failure handling: should use default error message when auth.error is not provided", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP<{ authenticated: boolean }>({
+    authenticate: async () => {
+      // Return authenticated: false without custom error message
+      return { authenticated: false };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async () => {
+      return "pong";
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    const response = await fetch(`http://localhost:${port}/mcp`, {
+      body: JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "initialize",
+        params: {
+          capabilities: {},
+          clientInfo: { name: "test", version: "1.0" },
+          protocolVersion: "2024-11-05",
+        },
+      }),
+      headers: {
+        Accept: "application/json, text/event-stream",
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    });
+
+    expect(response.status).toBe(401);
+
+    const body = (await response.json()) as {
+      error?: { message?: string };
+    };
+    expect(body.error?.message).toContain("Authentication failed");
+  } finally {
+    await server.stop();
+  }
+});
+
+test("authentication failure handling: should preserve existing behavior for truthy auth results", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP<{ role: string; userId: string }>({
+    authenticate: async () => {
+      // Return a truthy object without 'authenticated' field (legacy pattern)
+      return { role: "admin", userId: "456" };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async (_args, context) => {
+      return `User: ${context.session?.userId}, Role: ${context.session?.role}`;
+    },
+    name: "whoami",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    const client = new Client(
+      {
+        name: "Test client",
+        version: "1.0.0",
+      },
+      {
+        capabilities: {},
+      },
+    );
+
+    const transport = new StreamableHTTPClientTransport(
+      new URL(`http://localhost:${port}/mcp`),
+    );
+
+    await client.connect(transport);
+
+    const result = await client.callTool({
+      arguments: {},
+      name: "whoami",
+    });
+
+    expect(result.content).toEqual([
+      {
+        text: "User: 456, Role: admin",
+        type: "text",
+      },
+    ]);
+
+    await client.close();
+  } finally {
+    await server.stop();
+  }
+});
+
+test("authentication failure handling: should handle authentication with custom error messages", async () => {
+  const port = await getRandomPort();
+  const CUSTOM_ERROR_MSG = "Token expired at 2025-10-07T12:00:00Z";
+
+  const server = new FastMCP<{ authenticated: boolean; error?: string }>({
+    authenticate: async () => {
+      return { authenticated: false, error: CUSTOM_ERROR_MSG };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async () => {
+      return "pong";
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    const response = await fetch(`http://localhost:${port}/mcp`, {
+      body: JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "initialize",
+        params: {
+          capabilities: {},
+          clientInfo: { name: "test", version: "1.0" },
+          protocolVersion: "2024-11-05",
+        },
+      }),
+      headers: {
+        Accept: "application/json, text/event-stream",
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    });
+
+    expect(response.status).toBe(401);
+
+    const body = (await response.json()) as {
+      error?: { message?: string };
+    };
+    expect(body.error?.message).toBe(CUSTOM_ERROR_MSG);
+  } finally {
+    await server.stop();
+  }
+});
+
+test("authentication failure handling: should not create session for authenticated=false even with session data", async () => {
+  const port = await getRandomPort();
+
+  const server = new FastMCP<{
+    authenticated: boolean;
+    error?: string;
+    session?: { userId: string };
+  }>({
+    authenticate: async () => {
+      // Even if session data is present, authenticated: false should reject
+      return {
+        authenticated: false,
+        error: "Insufficient permissions",
+        session: { userId: "hacker" },
+      };
+    },
+    name: "Test server",
+    version: "1.0.0",
+  });
+
+  server.addTool({
+    description: "Test tool",
+    execute: async () => {
+      return "pong";
+    },
+    name: "ping",
+    parameters: z.object({}),
+  });
+
+  await server.start({
+    httpStream: {
+      port,
+      stateless: true,
+    },
+    transportType: "httpStream",
+  });
+
+  try {
+    const response = await fetch(`http://localhost:${port}/mcp`, {
+      body: JSON.stringify({
+        id: 1,
+        jsonrpc: "2.0",
+        method: "initialize",
+        params: {
+          capabilities: {},
+          clientInfo: { name: "test", version: "1.0" },
+          protocolVersion: "2024-11-05",
+        },
+      }),
+      headers: {
+        Accept: "application/json, text/event-stream",
+        "Content-Type": "application/json",
+      },
+      method: "POST",
+    });
+
+    expect(response.status).toBe(401);
+
+    const body = (await response.json()) as {
+      error?: { message?: string };
+    };
+    expect(body.error?.message).toContain("Insufficient permissions");
+
+    // Verify session was never created
+    expect(server.sessions.length).toBe(0);
+  } finally {
+    await server.stop();
+  }
+});
+
 test("host configuration works with 0.0.0.0", async () => {
   const port = await getRandomPort();
 

package/src/FastMCP.ts

@@ -210,7 +210,19 @@ type Context<T extends FastMCPSessionAuth> = {
     warn: (message: string, data?: SerializableValue) => void;
   };
   reportProgress: (progress: Progress) => Promise<void>;
+  /**
+   * Request ID from the current MCP request.
+   * Available for all transports when the client provides it.
+   */
+  requestId?: string;
   session: T | undefined;
+  /**
+   * Session ID from the Mcp-Session-Id header.
+   * Only available for HTTP-based transports (SSE, HTTP Stream).
+   * Can be used to track per-session state, implement session-specific
+   * counters, or maintain user-specific data across multiple requests.
+   */
+  sessionId?: string;
   streamContent: (content: Content | Content[]) => Promise<void>;
 };
 
@@ -936,6 +948,12 @@ export class FastMCPSession<
   public get server(): Server {
     return this.#server;
   }
+  public get sessionId(): string | undefined {
+    return this.#sessionId;
+  }
+  public set sessionId(value: string | undefined) {
+    this.#sessionId = value;
+  }
   #auth: T | undefined;
   #capabilities: ServerCapabilities = {};
   #clientCapabilities?: ClientCapabilities;
@@ -959,6 +977,12 @@ export class FastMCPSession<
 
   #server: Server;
 
+  /**
+   * Session ID from the Mcp-Session-Id header (HTTP transports only).
+   * Used to track per-session state across multiple requests.
+   */
+  #sessionId?: string;
+
   #utils?: ServerOptions<T>["utils"];
 
   constructor({
@@ -971,6 +995,7 @@ export class FastMCPSession<
     resources,
     resourcesTemplates,
     roots,
+    sessionId,
     tools,
     transportType,
     utils,
@@ -985,6 +1010,7 @@ export class FastMCPSession<
     resources: Resource<T>[];
     resourcesTemplates: InputResourceTemplate<T>[];
     roots?: ServerOptions<T>["roots"];
+    sessionId?: string;
     tools: Tool<T>[];
     transportType?: "httpStream" | "stdio";
     utils?: ServerOptions<T>["utils"];
@@ -996,6 +1022,7 @@ export class FastMCPSession<
     this.#logger = logger;
     this.#pingConfig = ping;
     this.#rootsConfig = roots;
+    this.#sessionId = sessionId;
     this.#needsEventLoopFlush = transportType === "httpStream";
 
     if (tools.length) {
@@ -1077,6 +1104,16 @@ export class FastMCPSession<
     try {
       await this.#server.connect(transport);
 
+      // Extract session ID from transport if available (HTTP transports only)
+      if ("sessionId" in transport) {
+        const transportWithSessionId = transport as {
+          sessionId?: string;
+        } & Transport;
+        if (typeof transportWithSessionId.sessionId === "string") {
+          this.#sessionId = transportWithSessionId.sessionId;
+        }
+      }
+
       let attempt = 0;
       const maxAttempts = 10;
       const retryDelay = 100;
@@ -1789,7 +1826,12 @@ export class FastMCPSession<
           },
           log,
           reportProgress,
+          requestId:
+            typeof request.params?._meta?.requestId === "string"
+              ? request.params._meta.requestId
+              : undefined,
           session: this.#auth,
+          sessionId: this.#sessionId,
           streamContent,
         });
 
@@ -2110,7 +2152,7 @@ export class FastMCP<
         );
 
         this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
-          authenticate: this.#authenticate,
+          ...(this.#authenticate ? { authenticate: this.#authenticate } : {}),
           createServer: async (request) => {
             let auth: T | undefined;
 
@@ -2124,9 +2166,14 @@ export class FastMCP<
               }
             }
 
+            // Extract session ID from headers
+            const sessionId = Array.isArray(request.headers["mcp-session-id"])
+              ? request.headers["mcp-session-id"][0]
+              : request.headers["mcp-session-id"];
+
             // In stateless mode, create a new session for each request
             // without persisting it in the sessions array
-            return this.#createSession(auth);
+            return this.#createSession(auth, sessionId);
           },
           enableJsonResponse: httpConfig.enableJsonResponse,
           eventStore: httpConfig.eventStore,
@@ -2151,7 +2198,7 @@ export class FastMCP<
       } else {
         // Regular mode with session management
         this.#httpStreamServer = await startHTTPServer<FastMCPSession<T>>({
-          authenticate: this.#authenticate,
+          ...(this.#authenticate ? { authenticate: this.#authenticate } : {}),
           createServer: async (request) => {
             let auth: T | undefined;
 
@@ -2159,7 +2206,12 @@ export class FastMCP<
               auth = await this.#authenticate(request);
             }
 
-            return this.#createSession(auth);
+            // Extract session ID from headers
+            const sessionId = Array.isArray(request.headers["mcp-session-id"])
+              ? request.headers["mcp-session-id"][0]
+              : request.headers["mcp-session-id"];
+
+            return this.#createSession(auth, sessionId);
           },
           enableJsonResponse: httpConfig.enableJsonResponse,
           eventStore: httpConfig.eventStore,
@@ -2218,7 +2270,22 @@ 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> {
+  #createSession(auth?: T, sessionId?: string): FastMCPSession<T> {
+    // Check if authentication failed
+    if (
+      auth &&
+      typeof auth === "object" &&
+      "authenticated" in auth &&
+      !(auth as { authenticated: unknown }).authenticated
+    ) {
+      const errorMessage =
+        "error" in auth &&
+        typeof (auth as { error: unknown }).error === "string"
+          ? (auth as { error: string }).error
+          : "Authentication failed";
+      throw new Error(errorMessage);
+    }
+
     const allowedTools = auth
       ? this.#tools.filter((tool) =>
           tool.canAccess ? tool.canAccess(auth) : true,
@@ -2234,6 +2301,7 @@ export class FastMCP<
       resources: this.#resources,
       resourcesTemplates: this.#resourcesTemplates,
       roots: this.#options.roots,
+      sessionId,
       tools: allowedTools,
       transportType: "httpStream",
       utils: this.#options.utils,