fastmcp 3.19.3 → 3.20.1

package/src/FastMCP.session-id.test.ts

@@ -0,0 +1,359 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { FastMCP } from "./FastMCP.js";
+
+interface TestAuth {
+  [key: string]: unknown;
+  userId: string;
+}
+
+describe("FastMCP Session ID Support", () => {
+  describe("HTTP Stream transport", () => {
+    it("should expose sessionId to tool handlers from Mcp-Session-Id header", async () => {
+      const server = new FastMCP<TestAuth>({
+        authenticate: async () => ({
+          userId: "test-user",
+        }),
+        name: "test-server",
+        version: "1.0.0",
+      });
+
+      let capturedSessionId: string | undefined;
+      let capturedRequestId: string | undefined;
+
+      server.addTool({
+        description: "Test tool that captures session and request IDs",
+        execute: async (_args, context) => {
+          capturedSessionId = context.sessionId;
+          capturedRequestId = context.requestId;
+          return `Session ID: ${context.sessionId || "none"}, Request ID: ${context.requestId || "none"}`;
+        },
+        name: "capture-ids",
+        parameters: z.object({}),
+      });
+
+      const port = 3000 + Math.floor(Math.random() * 1000);
+
+      await server.start({
+        httpStream: {
+          port,
+        },
+        transportType: "httpStream",
+      });
+
+      try {
+        const transport = new StreamableHTTPClientTransport(
+          new URL(`http://localhost:${port}/mcp`),
+        );
+
+        const client = new Client(
+          {
+            name: "test-client",
+            version: "1.0.0",
+          },
+          {
+            capabilities: {},
+          },
+        );
+
+        await client.connect(transport);
+
+        const result = await client.callTool({
+          arguments: {},
+          name: "capture-ids",
+        });
+
+        expect(result).toBeDefined();
+        expect(capturedSessionId).toBeDefined();
+        expect(typeof capturedSessionId).toBe("string");
+        expect(capturedSessionId).toMatch(/^[0-9a-f-]+$/); // UUID format
+
+        // Request ID may or may not be provided by the client
+        // If provided, it should be a string
+        if (capturedRequestId !== undefined) {
+          expect(typeof capturedRequestId).toBe("string");
+        }
+
+        await client.close();
+      } finally {
+        await server.stop();
+      }
+    });
+
+    it("should maintain the same sessionId across multiple requests", async () => {
+      const server = new FastMCP<TestAuth>({
+        authenticate: async () => ({
+          userId: "test-user",
+        }),
+        name: "test-server",
+        version: "1.0.0",
+      });
+
+      const capturedSessionIds: (string | undefined)[] = [];
+
+      server.addTool({
+        description: "Test tool that captures session ID",
+        execute: async (_args, context) => {
+          capturedSessionIds.push(context.sessionId);
+          return `Session ID: ${context.sessionId}`;
+        },
+        name: "capture-session",
+        parameters: z.object({}),
+      });
+
+      const port = 3000 + Math.floor(Math.random() * 1000);
+
+      await server.start({
+        httpStream: {
+          port,
+        },
+        transportType: "httpStream",
+      });
+
+      try {
+        const transport = new StreamableHTTPClientTransport(
+          new URL(`http://localhost:${port}/mcp`),
+        );
+
+        const client = new Client(
+          {
+            name: "test-client",
+            version: "1.0.0",
+          },
+          {
+            capabilities: {},
+          },
+        );
+
+        await client.connect(transport);
+
+        // Make multiple requests
+        await client.callTool({
+          arguments: {},
+          name: "capture-session",
+        });
+
+        await client.callTool({
+          arguments: {},
+          name: "capture-session",
+        });
+
+        await client.callTool({
+          arguments: {},
+          name: "capture-session",
+        });
+
+        // All requests should have the same session ID
+        expect(capturedSessionIds).toHaveLength(3);
+        expect(capturedSessionIds[0]).toBeDefined();
+        expect(capturedSessionIds[0]).toBe(capturedSessionIds[1]);
+        expect(capturedSessionIds[1]).toBe(capturedSessionIds[2]);
+
+        await client.close();
+      } finally {
+        await server.stop();
+      }
+    });
+
+    it("should support per-session state management using sessionId", async () => {
+      const server = new FastMCP<TestAuth>({
+        authenticate: async () => ({
+          userId: "test-user",
+        }),
+        name: "test-server",
+        version: "1.0.0",
+      });
+
+      // Per-session counter storage
+      const sessionCounters = new Map<string, number>();
+
+      server.addTool({
+        description: "Increment a per-session counter",
+        execute: async (_args, context) => {
+          if (!context.sessionId) {
+            return "No session ID available";
+          }
+
+          const currentCount = sessionCounters.get(context.sessionId) || 0;
+          const newCount = currentCount + 1;
+          sessionCounters.set(context.sessionId, newCount);
+
+          return `Counter for session ${context.sessionId}: ${newCount}`;
+        },
+        name: "increment-counter",
+        parameters: z.object({}),
+      });
+
+      const port = 3000 + Math.floor(Math.random() * 1000);
+
+      await server.start({
+        httpStream: {
+          port,
+        },
+        transportType: "httpStream",
+      });
+
+      try {
+        // Create two separate clients with different sessions
+        const transport1 = new StreamableHTTPClientTransport(
+          new URL(`http://localhost:${port}/mcp`),
+        );
+
+        const client1 = new Client(
+          {
+            name: "test-client-1",
+            version: "1.0.0",
+          },
+          {
+            capabilities: {},
+          },
+        );
+
+        await client1.connect(transport1);
+
+        const transport2 = new StreamableHTTPClientTransport(
+          new URL(`http://localhost:${port}/mcp`),
+        );
+
+        const client2 = new Client(
+          {
+            name: "test-client-2",
+            version: "1.0.0",
+          },
+          {
+            capabilities: {},
+          },
+        );
+
+        await client2.connect(transport2);
+
+        // Increment counter for client 1 twice
+        const result1a = await client1.callTool({
+          arguments: {},
+          name: "increment-counter",
+        });
+
+        const result1b = await client1.callTool({
+          arguments: {},
+          name: "increment-counter",
+        });
+
+        // Increment counter for client 2 once
+        const result2 = await client2.callTool({
+          arguments: {},
+          name: "increment-counter",
+        });
+
+        // Verify counters are independent per session
+        expect((result1a.content as Array<{ text: string }>)[0].text).toContain(
+          ": 1",
+        );
+        expect((result1b.content as Array<{ text: string }>)[0].text).toContain(
+          ": 2",
+        );
+        expect((result2.content as Array<{ text: string }>)[0].text).toContain(
+          ": 1",
+        );
+
+        await client1.close();
+        await client2.close();
+      } finally {
+        await server.stop();
+      }
+    });
+
+    it("should work in stateless mode without persistent sessionId", async () => {
+      const server = new FastMCP<TestAuth>({
+        authenticate: async () => ({
+          userId: "test-user",
+        }),
+        name: "test-server",
+        version: "1.0.0",
+      });
+
+      let capturedSessionId: string | undefined;
+
+      server.addTool({
+        description: "Test tool in stateless mode",
+        execute: async (_args, context) => {
+          capturedSessionId = context.sessionId;
+          return `Session ID: ${context.sessionId || "none"}`;
+        },
+        name: "test-stateless",
+        parameters: z.object({}),
+      });
+
+      const port = 3000 + Math.floor(Math.random() * 1000);
+
+      await server.start({
+        httpStream: {
+          port,
+          stateless: true,
+        },
+        transportType: "httpStream",
+      });
+
+      try {
+        const transport = new StreamableHTTPClientTransport(
+          new URL(`http://localhost:${port}/mcp`),
+        );
+
+        const client = new Client(
+          {
+            name: "test-client",
+            version: "1.0.0",
+          },
+          {
+            capabilities: {},
+          },
+        );
+
+        await client.connect(transport);
+
+        await client.callTool({
+          arguments: {},
+          name: "test-stateless",
+        });
+
+        // In stateless mode, sessionId should be undefined
+        expect(capturedSessionId).toBeUndefined();
+
+        await client.close();
+      } finally {
+        await server.stop();
+      }
+    });
+  });
+
+  describe("stdio transport", () => {
+    it("should not have sessionId in stdio transport", async () => {
+      const server = new FastMCP<TestAuth>({
+        authenticate: async () => ({
+          userId: "test-user",
+        }),
+        name: "test-server",
+        version: "1.0.0",
+      });
+
+      let capturedSessionId: string | undefined;
+
+      server.addTool({
+        description: "Test tool for stdio",
+        execute: async (_args, context) => {
+          capturedSessionId = context.sessionId;
+          return `Session ID: ${context.sessionId || "none"}`;
+        },
+        name: "test-stdio",
+        parameters: z.object({}),
+      });
+
+      await server.start({ transportType: "stdio" });
+
+      // In stdio transport, sessionId should be undefined
+      expect(capturedSessionId).toBeUndefined();
+    });
+  });
+});

package/src/FastMCP.test.ts

@@ -148,7 +148,7 @@ test("adds tools with Zod v4 schema", async () => {
           {
             description: "Add two numbers (using Zod v4 schema)",
             inputSchema: {
-              $schema: "https://json-schema.org/draft/2020-12/schema",
+              $schema: "http://json-schema.org/draft-07/schema#",
               additionalProperties: false,
               properties: {
                 a: { type: "number" },
@@ -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),
     },
   );

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,7 @@ 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 &&
@@ -2249,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,