@softure-ai/mcp-access 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,17 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`mcp-access@x.y.z`).
 
+## 0.5.0
+
+- Sessions that follow the tool list (#1055): `createMcpEndpoint` answers `initialize` with an `Mcp-Session-Id` that
+  carries the tool list version of the identity's access level, and answers `404 Not Found` to a request whose session
+  carries another version, so a connected client initializes again and re-lists the tools after a release that
+  changed one, without reconnecting the connector. Stateless: nothing is stored. A request without a session id is
+  served as before. `initialize` now declares `tools.listChanged: false`, since the endpoint never sends the
+  notification. `createMcpServerFactory` returns a factory with `toolListVersion(identity)`; a hand-written factory
+  passes `toolListVersion` to `createMcpEndpoint` to get sessions. `/testing` adds
+  `expectToolListSessionRenewed(before, after)`. Migrate: nothing for an app on `createMcpServerFactory`.
+
 ## 0.4.0
 
 - Operation tools with a context getter (#990), in `@softure-ai/mcp-access/jobs`: `registerOperationStatusTool`,

package/README.md

@@ -189,6 +189,27 @@ export const createServer = createMcpServerFactory({
   and count of each level, for an inline snapshot next to the catalog check: a schema change that forgets to update
   the snapshot fails the test.
 
+### Sessions that follow the tool list
+
+A hosted client can keep its cached `tools/list` for as long as its connection lives, even after the version moved,
+and the endpoint has no stream to send `notifications/tools/list_changed` on. So `createMcpEndpoint` ties a session to
+the tool list (#1055):
+
+- `initialize` answers with an `Mcp-Session-Id` that carries the tool list version of the identity's access level
+  (`<base64url(version)>.<random>`). Nothing is stored, so every instance can check it.
+- A request whose session carries another version (a release changed a tool, or the token's access level changed)
+  answers `404 Not Found` (`-32001 Session not found`). Streamable HTTP defines that as "start a new session": the
+  client initializes again, reads the new version and lists the tools again, without the user reconnecting.
+- A client that sends no session id is served as before. `initialize` declares `tools.listChanged: false`, since the
+  endpoint never sends the notification.
+- The version comes from the factory: `createMcpServerFactory` returns a factory with `toolListVersion(identity)`. A
+  hand-written factory issues no session id unless the endpoint gets `toolListVersion` itself:
+  `createMcpEndpoint({ createServer, toolListVersion: async (identity) => ... })`. A failing reader logs and serves
+  the request without a session.
+- In the app's tests, `expectToolListSessionRenewed(before, after)` (`/testing`) takes the previous and the new
+  factory and throws unless a session opened under `before` is renewed for every access level whose list changed (and
+  kept for the others).
+
 ### Strict tool input
 
 zod objects strip unknown keys, so a call with a misspelt field (`notes` for `note`) or a field of a newer tool list

package/dist/index.js

@@ -45,7 +45,7 @@ export const API_TOKEN_RATE_LIMIT_BUCKETS = {
 export const mcpAccess = defineModule({
     manifest: {
         id: MODULE_ID,
-        version: "0.4.0",
+        version: "0.5.0",
         dependsOn: { security: "^0.2.0", auth: "^0.2.0", jobs: "^0.1.1?", ops: "^0.2.0?" },
         dbSchema: "mcp",
         tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants", "oauth_registration_window", "used_confirmations", "operation_tasks"],

package/dist/server/endpoint.d.ts

@@ -9,8 +9,19 @@ export declare const MCP_RATE_LIMIT_BUCKET = "mcp";
 export declare const MAX_MCP_REQUEST_BYTES: number;
 /** The app's MCP server for one request. It registers write tools only when `canWrite` is true. */
 export type McpServerFactory = (identity: McpServerIdentity) => McpServer | Server | Promise<McpServer | Server>;
+/** Reads the tool list version the factory's servers answer at `initialize` for the identity. */
+export type ToolListVersionReader = (identity: McpServerIdentity) => Promise<string>;
+/** A factory that can tell its tool list version without building a server; `createMcpServerFactory` returns one. */
+export interface VersionedMcpServerFactory extends McpServerFactory {
+    readonly toolListVersion: ToolListVersionReader;
+}
 export interface McpEndpointOptions {
-    readonly createServer: McpServerFactory;
+    readonly createServer: McpServerFactory | VersionedMcpServerFactory;
+    /**
+     * The tool list version per identity, for sessions tied to it (#1055). Default: the factory's own
+     * `toolListVersion` (`createMcpServerFactory`). Without either, the endpoint issues no session id.
+     */
+    readonly toolListVersion?: ToolListVersionReader;
 }
 /** Serves one request to the MCP endpoint. */
 export type McpEndpoint = (ctx: McpAccessContext, request: Request) => Promise<Response>;
@@ -20,5 +31,5 @@ export type McpEndpoint = (ctx: McpAccessContext, request: Request) => Promise<R
  * (`responseMode: "json"`): a stream would add proxy buffering and timeouts for no tool that needs
  * it, and mid-call notifications are dropped.
  */
-export declare function createMcpEndpoint({ createServer }: McpEndpointOptions): McpEndpoint;
+export declare function createMcpEndpoint({ createServer, toolListVersion }: McpEndpointOptions): McpEndpoint;
 //# sourceMappingURL=endpoint.d.ts.map

package/dist/server/endpoint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../src/server/endpoint.ts"],"names":[],"mappings":"AAKA,OAAO,EAML,KAAK,SAAS,EACd,KAAK,MAAM,EACZ,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGvE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAE3C,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C,6FAA6F;AAC7F,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAOjD,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,iBAAiB,KAAK,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;AAEjH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;CACzC;AAED,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEzF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,YAAY,EAAE,EAAE,kBAAkB,GAAG,WAAW,CAmCnF"}
+{"version":3,"file":"endpoint.d.ts","sourceRoot":"","sources":["../../src/server/endpoint.ts"],"names":[],"mappings":"AAKA,OAAO,EAML,KAAK,SAAS,EACd,KAAK,MAAM,EACZ,MAAM,8BAA8B,CAAC;AAGtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGxD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAWvE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAE3C,8FAA8F;AAC9F,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAE3C,6FAA6F;AAC7F,eAAO,MAAM,qBAAqB,QAAc,CAAC;AAOjD,mGAAmG;AACnG,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,iBAAiB,KAAK,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;AAEjH,iGAAiG;AACjG,MAAM,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAErF,qHAAqH;AACrH,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,QAAQ,CAAC,eAAe,EAAE,qBAAqB,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,GAAG,yBAAyB,CAAC;IACpE;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,CAAC;CAClD;AAED,8CAA8C;AAC9C,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEzF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,YAAY,EAAE,eAAe,EAAE,EAAE,kBAAkB,GAAG,WAAW,CA+DpG"}

package/dist/server/endpoint.js

@@ -10,6 +10,7 @@ import { getProtectedResourceMetadataUrl, isOAuthEnabled } from "./oauth-http.js
 import { resolveMcpOrigins } from "./origins.js";
 import { MCP_READ_SCOPE, MCP_WRITE_SCOPE } from "./scopes.js";
 import { verifyAccessToken } from "./tokens.js";
+import { createSessionRenewalResponse, createToolListSessionId, isInitializeRequest, isToolListSessionCurrent, MCP_SESSION_ID_HEADER, rewriteInitializeAnswer, } from "./tool-list-session.js";
 import { isWritingEnabled } from "./writes-switch.js";
 export { MCP_READ_SCOPE, MCP_WRITE_SCOPE };
 /** The security bucket the endpoint counts in; `MCP_RATE_LIMIT_BUCKETS` holds its default. */
@@ -26,7 +27,8 @@ const NO_STORE = { "cache-control": "no-store" };
  * (`responseMode: "json"`): a stream would add proxy buffering and timeouts for no tool that needs
  * it, and mid-call notifications are dropped.
  */
-export function createMcpEndpoint({ createServer }) {
+export function createMcpEndpoint({ createServer, toolListVersion }) {
+    const readToolListVersion = toolListVersion ?? getFactoryToolListVersion(createServer);
     const handler = createMcpHandler((requestContext) => createServer(readIdentity(requestContext.authInfo)), {
         responseMode: "json",
         maxRequestBodySize: MAX_MCP_REQUEST_BYTES,
@@ -53,8 +55,39 @@ export function createMcpEndpoint({ createServer }) {
         const authInfo = await authenticate(ctx, request);
         if (authInfo instanceof Response)
             return authInfo;
-        return handler.fetch(request, { authInfo });
+        return serveInSession(request, authInfo);
     };
+    /**
+     * Sessions tied to the tool list version (#1055): a session from another version (a release changed a tool, or the
+     * access level changed) answers 404, so the client initializes again and lists the tools again; `initialize` gets a
+     * new session id. A request without a session id is served as it always was.
+     */
+    async function serveInSession(request, authInfo) {
+        const sessionId = request.headers.get(MCP_SESSION_ID_HEADER);
+        const isInitialize = sessionId === null && (await isInitializeRequest(request, MAX_MCP_REQUEST_BYTES));
+        if (readToolListVersion === undefined || (sessionId === null && !isInitialize)) {
+            const response = await handler.fetch(request, { authInfo });
+            return isInitialize ? rewriteInitializeAnswer(response, null) : response;
+        }
+        let version;
+        try {
+            version = await readToolListVersion(readIdentity(authInfo));
+        }
+        catch (error) {
+            // Without the version no session can be checked or issued: serve the request statelessly, as before #1055.
+            console.error(`@softure-ai/mcp-access: reading the tool list version failed: ${errorLogLabel(error)}`);
+            const response = await handler.fetch(request, { authInfo });
+            return isInitialize ? rewriteInitializeAnswer(response, null) : response;
+        }
+        if (sessionId !== null) {
+            return isToolListSessionCurrent(sessionId, version) ? handler.fetch(request, { authInfo }) : createSessionRenewalResponse();
+        }
+        return rewriteInitializeAnswer(await handler.fetch(request, { authInfo }), createToolListSessionId(version));
+    }
+}
+/** The factory's own version reader, when it has one (`createMcpServerFactory`). */
+function getFactoryToolListVersion(factory) {
+    return "toolListVersion" in factory && typeof factory.toolListVersion === "function" ? factory.toolListVersion : undefined;
 }
 /**
  * The verified identity as the SDK's `AuthInfo`, or the challenge response. Unknown, revoked,

package/dist/server/endpoint.js.map

@@ -1 +1 @@
-{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../../src/server/endpoint.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../../src/server/endpoint.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,oGAAoG;AACpG,gGAAgG;AAChG,kGAAkG;AAClG,4BAA4B;AAC5B,OAAO,EACL,2BAA2B,EAC3B,gBAAgB,EAChB,UAAU,EACV,cAAc,GAIf,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE/E,OAAO,EAAE,+BAA+B,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAyB,MAAM,aAAa,CAAC;AACvE,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAE3C,8FAA8F;AAC9F,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC;AAE3C,6FAA6F;AAC7F,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,aAAa,GAAG,QAAQ,CAAC;AAC/B,MAAM,aAAa,GAAG,gBAAgB,CAAC;AACvC,MAAM,QAAQ,GAAG,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC;AAyBjD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAE,YAAY,EAAE,eAAe,EAAsB;IACrF,MAAM,mBAAmB,GAAG,eAAe,IAAI,yBAAyB,CAAC,YAAY,CAAC,CAAC;IACvF,MAAM,OAAO,GAAG,gBAAgB,CAC9B,CAAC,cAAc,EAAE,EAAE,CAAC,YAAY,CAAC,YAAY,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,EACvE;QACE,YAAY,EAAE,MAAM;QACpB,kBAAkB,EAAE,qBAAqB;QACzC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,qDAAqD,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;KAC/G,CACF,CAAC;IAEF,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;QAC5B,qBAAqB,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QAE3G,IAAI,KAAK,CAAC;QACV,IAAI,CAAC;YACH,mFAAmF;YACnF,KAAK,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAC5F,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,0FAA0F;YAC1F,OAAO,CAAC,KAAK,CAAC,sDAAsD,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC5F,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,yBAAyB,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QACjG,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;YACd,OAAO,QAAQ,CAAC,IAAI,CAClB,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAC9B,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,GAAG,QAAQ,EAAE,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,EAAE,CAC1F,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAClD,IAAI,QAAQ,YAAY,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAClD,OAAO,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC,CAAC;IAEF;;;;OAIG;IACH,KAAK,UAAU,cAAc,CAAC,OAAgB,EAAE,QAAkB;QAChE,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QAC7D,MAAM,YAAY,GAAG,SAAS,KAAK,IAAI,IAAI,CAAC,MAAM,mBAAmB,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC;QACvG,IAAI,mBAAmB,KAAK,SAAS,IAAI,CAAC,SAAS,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/E,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC5D,OAAO,YAAY,CAAC,CAAC,CAAC,uBAAuB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,mBAAmB,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,2GAA2G;YAC3G,OAAO,CAAC,KAAK,CAAC,iEAAiE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACvG,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC5D,OAAO,YAAY,CAAC,CAAC,CAAC,uBAAuB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC3E,CAAC;QACD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,OAAO,wBAAwB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,4BAA4B,EAAE,CAAC;QAC9H,CAAC;QACD,OAAO,uBAAuB,CAAC,MAAM,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/G,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,SAAS,yBAAyB,CAAC,OAAqD;IACtF,OAAO,iBAAiB,IAAI,OAAO,IAAI,OAAO,OAAO,CAAC,eAAe,KAAK,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7H,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,YAAY,CAAC,GAAqB,EAAE,OAAgB;IACjE,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACpD,gGAAgG;IAChG,sGAAsG;IACtG,iGAAiG;IACjG,MAAM,cAAc,GAAG,MAAM,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACnD,MAAM,cAAc,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;IAC7F,MAAM,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1C,CAAC,CAAC,EAAE,cAAc,EAAE,mBAAmB,EAAE,+BAA+B,CAAC,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE;QAC9H,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC;IACvB,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,OAAO,2BAA2B,CAAC,IAAI,UAAU,CAAC,cAAc,CAAC,YAAY,EAAE,sBAAsB,CAAC,EAAE,SAAS,CAAC,CAAC;IACrH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAEvD,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,qDAAqD,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC3F,OAAO,2BAA2B,CAAC,IAAI,UAAU,CAAC,cAAc,CAAC,WAAW,EAAE,uBAAuB,CAAC,EAAE,SAAS,CAAC,CAAC;IACrH,CAAC;IACD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,2BAA2B,CAAC,IAAI,UAAU,CAAC,cAAc,CAAC,YAAY,EAAE,sBAAsB,CAAC,EAAE,SAAS,CAAC,CAAC;IACrH,CAAC;IACD,OAAO;QACL,KAAK;QACL,8EAA8E;QAC9E,QAAQ,EAAE,QAAQ,CAAC,OAAO;QAC1B,MAAM,EAAE,QAAQ,CAAC,QAAQ,IAAI,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;QAClG,qDAAqD;QACrD,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;QAC1D,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,EAAE;KAC5C,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,SAAS,YAAY,CAAC,QAA8B;IAClD,MAAM,MAAM,GAAG,QAAQ,EAAE,KAAK,EAAE,CAAC,aAAa,CAAC,CAAC;IAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;QAC1E,4FAA4F;QAC5F,gFAAgF;QAChF,MAAM,IAAI,KAAK,CAAC,wFAAwF,CAAC,CAAC;IAC5G,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC;AACrG,CAAC;AAED,qGAAqG;AACrG,SAAS,qBAAqB,CAAC,GAAqB;IAClD,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,OAA4D,CAAC;IAChH,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC,qBAAqB,CAAC,KAAK,SAAS,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CACb,uDAAuD,qBAAqB,oEAAoE,CACjJ,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-export { createMcpEndpoint, MAX_MCP_REQUEST_BYTES, MCP_RATE_LIMIT_BUCKET, MCP_READ_SCOPE, MCP_WRITE_SCOPE, type McpEndpoint, type McpEndpointOptions, type McpServerFactory, } from "./endpoint.js";
+export { createMcpEndpoint, MAX_MCP_REQUEST_BYTES, MCP_RATE_LIMIT_BUCKET, MCP_READ_SCOPE, MCP_WRITE_SCOPE, type McpEndpoint, type McpEndpointOptions, type McpServerFactory, type ToolListVersionReader, type VersionedMcpServerFactory, } from "./endpoint.js";
 export { actionTool, toFormData, type ActionToolOptions, type FormActionHandler } from "./action-tool.js";
 export { CONFIRMATION_FIELD, CONFIRMATION_SECRET_ENV, confirmationInput, DEFAULT_CONFIRMATION_TTL_SECONDS, MIN_CONFIRMATION_SECRET_LENGTH, pruneUsedConfirmations, toCanonicalJson, withConfirmation, type ConfirmationErrorCode, type ConfirmationEstimate, type ConfirmationRequest, type ConfirmedToolArgs, type WithConfirmationOptions, } from "./confirmation.js";
 export { createMcpAccessContext } from "./context.js";
@@ -21,5 +21,6 @@ export { createMcpServerFactory, type McpServerFactoryOptions } from "./server-f
 export { registerServerInfoTool, SERVER_INFO_TOOL_NAME, type McpBuildInfo, type RegisterServerInfoToolOptions, type ServedServerInfo, type ServerInfoAnswer, type ServerInfoToolOptions, } from "./server-info.js";
 export { toStrictToolInput, withStrictToolInput, type RenamedFields, type StrictToolInputMessages, type StrictToolInputOptions } from "./strict-input.js";
 export { DEFAULT_TOOL_LIST_RELEASE, describeToolList, fingerprintToolList, listServedTools, measureToolList, type MeasureToolListOptions, type RegisterTools, type ServedTool, type ToolListMeasurement, } from "./tool-list.js";
+export { createToolListSessionId, isToolListSessionCurrent, MCP_SESSION_ID_HEADER, readToolListSessionVersion, } from "./tool-list-session.js";
 export { toolError, toolResult, withToolErrors, type ToolCaller, type ToolCallHook, type ToolCallOutcome, type ToolCallRecord, type ToolErrorHints, type ToolErrorOptions, } from "./tools.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}

package/dist/server/index.js

@@ -22,5 +22,6 @@ export { createMcpServerFactory } from "./server-factory.js";
 export { registerServerInfoTool, SERVER_INFO_TOOL_NAME, } from "./server-info.js";
 export { toStrictToolInput, withStrictToolInput } from "./strict-input.js";
 export { DEFAULT_TOOL_LIST_RELEASE, describeToolList, fingerprintToolList, listServedTools, measureToolList, } from "./tool-list.js";
+export { createToolListSessionId, isToolListSessionCurrent, MCP_SESSION_ID_HEADER, readToolListSessionVersion, } from "./tool-list-session.js";
 export { toolError, toolResult, withToolErrors, } from "./tools.js";
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,+FAA+F;AAC/F,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,eAAe,GAIhB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAkD,MAAM,kBAAkB,CAAC;AAC1G,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,gCAAgC,EAChC,8BAA8B,EAC9B,sBAAsB,EACtB,eAAe,EACf,gBAAgB,GAMjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,uBAAuB,EACvB,4BAA4B,EAC5B,wBAAwB,EACxB,+BAA+B,EAC/B,sBAAsB,GAGvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,yBAAyB,EACzB,eAAe,EACf,mBAAmB,EACnB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GASjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,kCAAkC,EAClC,mBAAmB,EACnB,8BAA8B,EAC9B,cAAc,EACd,cAAc,EACd,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,2BAA2B,EAC3B,wBAAwB,EACxB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,qBAAqB,EACrB,2BAA2B,EAC3B,YAAY,EACZ,gCAAgC,EAChC,uBAAuB,EACvB,sBAAsB,EACtB,4BAA4B,GAK7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,iBAAiB,EAA0C,MAAM,eAAe,CAAC;AACrI,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,uBAAuB,EAAyD,MAAM,uBAAuB,CAAC;AAC1L,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACrG,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,iBAAiB,EAAwB,MAAM,cAAc,CAAC;AACtI,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAA+B,MAAM,YAAY,CAAC;AAC9F,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,GAE5B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,GAOlB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,GAMf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,sBAAsB,EAAgC,MAAM,qBAAqB,CAAC;AAC3F,OAAO,EACL,sBAAsB,EACtB,qBAAqB,GAMtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAiF,MAAM,mBAAmB,CAAC;AAC1J,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,eAAe,GAKhB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,SAAS,EACT,UAAU,EACV,cAAc,GAOf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"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"}

package/dist/server/server-factory.d.ts

@@ -1,6 +1,6 @@
 import { McpServer, type McpServerOptions } from "@modelcontextprotocol/server";
 import type { McpServerIdentity } from "../contract.js";
-import type { McpServerFactory } from "./endpoint.js";
+import type { VersionedMcpServerFactory } from "./endpoint.js";
 import { type StrictToolInputOptions } from "./strict-input.js";
 import { type ServerInfoToolOptions } from "./server-info.js";
 export interface McpServerFactoryOptions {
@@ -26,6 +26,10 @@ export interface McpServerFactoryOptions {
      */
     readonly serverInfoTool?: ServerInfoToolOptions;
 }
-/** An `McpServerFactory` whose servers carry the tool list's version for the identity's access level. */
-export declare function createMcpServerFactory(options: McpServerFactoryOptions): McpServerFactory;
+/**
+ * An `McpServerFactory` whose servers carry the tool list's version for the identity's access level. Its
+ * `toolListVersion(identity)` reads that version without building a server, so `createMcpEndpoint` ties each session
+ * to it (#1055).
+ */
+export declare function createMcpServerFactory(options: McpServerFactoryOptions): VersionedMcpServerFactory;
 //# sourceMappingURL=server-factory.d.ts.map

package/dist/server/server-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-factory.d.ts","sourceRoot":"","sources":["../../src/server/server-factory.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAuB,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAGtF,MAAM,WAAW,uBAAuB;IACtC,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC;IACpF,yGAAyG;IACzG,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC5D;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACjD;AAED,yGAAyG;AACzG,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,gBAAgB,CAmCzF"}
+{"version":3,"file":"server-factory.d.ts","sourceRoot":"","sources":["../../src/server/server-factory.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAuB,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAGtF,MAAM,WAAW,uBAAuB;IACtC,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC;IACpF,yGAAyG;IACzG,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC5D;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,qBAAqB,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,uBAAuB,GAAG,yBAAyB,CAqClG"}

package/dist/server/server-factory.js

@@ -12,7 +12,11 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { withStrictToolInput } from "./strict-input.js";
 import { registerServerInfoTool } from "./server-info.js";
 import { measureToolList } from "./tool-list.js";
-/** An `McpServerFactory` whose servers carry the tool list's version for the identity's access level. */
+/**
+ * An `McpServerFactory` whose servers carry the tool list's version for the identity's access level. Its
+ * `toolListVersion(identity)` reads that version without building a server, so `createMcpEndpoint` ties each session
+ * to it (#1055).
+ */
 export function createMcpServerFactory(options) {
     const strictOptions = options.strictToolInput === true ? {} : options.strictToolInput === false ? undefined : options.strictToolInput;
     // The served version reaches `get_server_info` here; the recording server registers it with a placeholder, since
@@ -39,11 +43,13 @@ export function createMcpServerFactory(options) {
         void measurement.catch(() => measurements.delete(identity.canWrite));
         return measurement;
     };
-    return async (identity) => {
-        const version = options.version ?? (await measure(identity)).toolListVersion;
+    const toolListVersion = async (identity) => options.version ?? (await measure(identity)).toolListVersion;
+    const factory = async (identity) => {
+        const version = await toolListVersion(identity);
         const server = new McpServer({ name: options.name, version, ...(options.title === undefined ? {} : { title: options.title }) }, options.serverOptions);
         await registerTools(server, identity, version);
         return server;
     };
+    return Object.assign(factory, { toolListVersion });
 }
 //# sourceMappingURL=server-factory.js.map

package/dist/server/server-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-factory.js","sourceRoot":"","sources":["../../src/server/server-factory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server-factory.js","sourceRoot":"","sources":["../../src/server/server-factory.ts"],"names":[],"mappings":"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"}

package/dist/server/tool-list-session.d.ts

@@ -0,0 +1,22 @@
+/** The header that carries the session id, both ways. */
+export declare const MCP_SESSION_ID_HEADER = "mcp-session-id";
+/** A new session id for the version: `<base64url(version)>.<32 hex>`, visible ASCII whatever the version holds. */
+export declare function createToolListSessionId(toolListVersion: string): string;
+/** The tool list version a session id carries, or `null` when the id is not one the endpoint issues. */
+export declare function readToolListSessionVersion(sessionId: string): string | null;
+/** Whether a request in this session may be served: its version is the current one. */
+export declare function isToolListSessionCurrent(sessionId: string, toolListVersion: string): boolean;
+/** The answer to a request in a session from another tool list version: the client starts a new session. */
+export declare function createSessionRenewalResponse(): Response;
+/**
+ * Whether the request is a JSON-RPC `initialize`: a POST without a session id whose JSON body asks for it. The body
+ * is read from a clone, and a body over `maxBytes` is not read (the SDK refuses it with 413 anyway).
+ */
+export declare function isInitializeRequest(request: Request, maxBytes: number): Promise<boolean>;
+/**
+ * The `initialize` answer with `capabilities.tools.listChanged: false`, since no answer of the endpoint ever carries
+ * the notification, and with the session id when there is one. The body keeps its format (JSON or one SSE event);
+ * an answer that is not a successful `InitializeResult` is returned as it is.
+ */
+export declare function rewriteInitializeAnswer(response: Response, sessionId: string | null): Promise<Response>;
+//# sourceMappingURL=tool-list-session.d.ts.map

package/dist/server/tool-list-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-list-session.d.ts","sourceRoot":"","sources":["../../src/server/tool-list-session.ts"],"names":[],"mappings":"AAQA,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AAOtD,mHAAmH;AACnH,wBAAgB,uBAAuB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wGAAwG;AACxG,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI3E;AAED,uFAAuF;AACvF,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAE5F;AAED,4GAA4G;AAC5G,wBAAgB,4BAA4B,IAAI,QAAQ,CAKvD;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAc9F;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsB7G"}

package/dist/server/tool-list-session.js

@@ -0,0 +1,97 @@
+// Sessions tied to the tool list version (#1055). A hosted client keeps its cached `tools/list` for as long as its
+// connection lives, even after a release changed a tool, and the endpoint has no channel to send
+// `notifications/tools/list_changed`. So the endpoint answers `initialize` with an `Mcp-Session-Id` that carries the
+// tool list version of the identity's access level, and a later request whose session carries another version gets
+// `404 Not Found`: Streamable HTTP defines that as "start a new session", so the client initializes again and lists
+// the tools again. Nothing is stored: the id itself holds the version, so any instance can check it.
+import { randomBytes } from "node:crypto";
+/** The header that carries the session id, both ways. */
+export const MCP_SESSION_ID_HEADER = "mcp-session-id";
+/** Random bytes after the version, as hex. */
+const RANDOM_BYTES = 16;
+const SESSION_ID_PATTERN = /^([A-Za-z0-9_-]+)\.[0-9a-f]+$/;
+const SSE_DATA_PREFIX = "data: ";
+/** A new session id for the version: `<base64url(version)>.<32 hex>`, visible ASCII whatever the version holds. */
+export function createToolListSessionId(toolListVersion) {
+    return `${Buffer.from(toolListVersion, "utf8").toString("base64url")}.${randomBytes(RANDOM_BYTES).toString("hex")}`;
+}
+/** The tool list version a session id carries, or `null` when the id is not one the endpoint issues. */
+export function readToolListSessionVersion(sessionId) {
+    const match = SESSION_ID_PATTERN.exec(sessionId);
+    if (match?.[1] === undefined)
+        return null;
+    return Buffer.from(match[1], "base64url").toString("utf8");
+}
+/** Whether a request in this session may be served: its version is the current one. */
+export function isToolListSessionCurrent(sessionId, toolListVersion) {
+    return readToolListSessionVersion(sessionId) === toolListVersion;
+}
+/** The answer to a request in a session from another tool list version: the client starts a new session. */
+export function createSessionRenewalResponse() {
+    return Response.json({ jsonrpc: "2.0", error: { code: -32001, message: "Session not found: the tool list changed, initialize again" }, id: null }, { status: 404, headers: { "cache-control": "no-store" } });
+}
+/**
+ * Whether the request is a JSON-RPC `initialize`: a POST without a session id whose JSON body asks for it. The body
+ * is read from a clone, and a body over `maxBytes` is not read (the SDK refuses it with 413 anyway).
+ */
+export async function isInitializeRequest(request, maxBytes) {
+    if (request.method !== "POST" || request.headers.has(MCP_SESSION_ID_HEADER))
+        return false;
+    const length = Number(request.headers.get("content-length") ?? "0");
+    if (!Number.isFinite(length) || length > maxBytes)
+        return false;
+    let body;
+    try {
+        const text = await request.clone().text();
+        if (text.length > maxBytes)
+            return false;
+        body = JSON.parse(text);
+    }
+    catch {
+        // Not JSON: the SDK answers the parse error itself.
+        return false;
+    }
+    return typeof body === "object" && body !== null && !Array.isArray(body) && body.method === "initialize";
+}
+/**
+ * The `initialize` answer with `capabilities.tools.listChanged: false`, since no answer of the endpoint ever carries
+ * the notification, and with the session id when there is one. The body keeps its format (JSON or one SSE event);
+ * an answer that is not a successful `InitializeResult` is returned as it is.
+ */
+export async function rewriteInitializeAnswer(response, sessionId) {
+    if (response.status !== 200)
+        return response;
+    const text = await response.text();
+    const isEventStream = (response.headers.get("content-type") ?? "").includes("text/event-stream");
+    const lines = text.split("\n");
+    const dataIndex = isEventStream ? lines.findIndex((line) => line.startsWith(SSE_DATA_PREFIX)) : -1;
+    const json = isEventStream ? (dataIndex === -1 ? null : (lines[dataIndex] ?? "").slice(SSE_DATA_PREFIX.length)) : text;
+    const answer = parseInitializeAnswer(json);
+    const headers = new Headers(response.headers);
+    // The body changes length, so the old one would be wrong.
+    headers.delete("content-length");
+    const tools = answer?.result?.capabilities?.tools;
+    if (answer === null || answer.result?.protocolVersion === undefined) {
+        return new Response(text, { status: response.status, statusText: response.statusText, headers });
+    }
+    if (tools !== undefined && tools !== null && typeof tools === "object")
+        tools.listChanged = false;
+    if (sessionId !== null)
+        headers.set(MCP_SESSION_ID_HEADER, sessionId);
+    const rewritten = JSON.stringify(answer);
+    if (isEventStream)
+        lines[dataIndex] = `${SSE_DATA_PREFIX}${rewritten}`;
+    return new Response(isEventStream ? lines.join("\n") : rewritten, { status: response.status, statusText: response.statusText, headers });
+}
+/** The answer as JSON, or `null` when there is none or it is not JSON (the SDK's own error text). */
+function parseInitializeAnswer(json) {
+    if (json === null)
+        return null;
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=tool-list-session.js.map

package/dist/server/tool-list-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-list-session.js","sourceRoot":"","sources":["../../src/server/tool-list-session.ts"],"names":[],"mappings":"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"}

package/dist/testing/index.d.ts

@@ -1,2 +1,3 @@
 export { expectToolCatalogMatchesServer, getToolCatalogDifferences, measureServedToolLists, type ServedToolLists, type ToolCatalogDifferences, } from "./catalog.js";
+export { expectToolListSessionRenewed } from "./sessions.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,sBAAsB,EACtB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}

package/dist/testing/index.js

@@ -1,3 +1,4 @@
 // `@softure-ai/mcp-access/testing`: checks for an app's own tests.
 export { expectToolCatalogMatchesServer, getToolCatalogDifferences, measureServedToolLists, } from "./catalog.js";
+export { expectToolListSessionRenewed } from "./sessions.js";
 //# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,sBAAsB,GAGvB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,sBAAsB,GAGvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}

package/dist/testing/sessions.d.ts

@@ -0,0 +1,8 @@
+import type { McpServerFactory } from "../server/endpoint.js";
+/**
+ * Throws unless a session opened under `before` (the previous release's factory) is renewed under `after` for every
+ * access level whose served tool list changed, and kept for every level whose list did not. A pair where no level
+ * changed throws too: the check would prove nothing.
+ */
+export declare function expectToolListSessionRenewed(before: McpServerFactory, after: McpServerFactory): Promise<void>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/testing/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/testing/sessions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAA6B,MAAM,uBAAuB,CAAC;AAWzF;;;;GAIG;AACH,wBAAsB,4BAA4B,CAAC,MAAM,EAAE,gBAAgB,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAanH"}

package/dist/testing/sessions.js

@@ -0,0 +1,40 @@
+import { createToolListSessionId, isToolListSessionCurrent } from "../server/tool-list-session.js";
+import { fingerprintToolList, listServedTools } from "../server/tool-list.js";
+const READER = { userId: "00000000-0000-4000-8000-000000000001", canWrite: false, tokenId: "session-check" };
+const WRITER = { ...READER, canWrite: true };
+const LEVELS = [
+    ["read", READER],
+    ["write", WRITER],
+];
+/**
+ * Throws unless a session opened under `before` (the previous release's factory) is renewed under `after` for every
+ * access level whose served tool list changed, and kept for every level whose list did not. A pair where no level
+ * changed throws too: the check would prove nothing.
+ */
+export async function expectToolListSessionRenewed(before, after) {
+    const problems = [];
+    const unchanged = [];
+    for (const [level, identity] of LEVELS) {
+        const sessionId = createToolListSessionId(await readVersion(before, identity));
+        const isCurrent = isToolListSessionCurrent(sessionId, await readVersion(after, identity));
+        const hasChanged = fingerprintToolList(await listServedTools(() => before(identity))) !== fingerprintToolList(await listServedTools(() => after(identity)));
+        if (!hasChanged)
+            unchanged.push(level);
+        if (hasChanged && isCurrent)
+            problems.push(`the ${level} tool list changed but a session opened before is kept`);
+        if (!hasChanged && !isCurrent)
+            problems.push(`the ${level} tool list did not change but a session opened before is renewed`);
+    }
+    if (unchanged.length === LEVELS.length)
+        problems.push(`the tool list did not change for any access level (${unchanged.join(", ")})`);
+    if (problems.length > 0)
+        throw new Error(`@softure-ai/mcp-access: sessions do not follow the tool list: ${problems.join("; ")}`);
+}
+async function readVersion(factory, identity) {
+    const reader = factory.toolListVersion;
+    if (typeof reader !== "function") {
+        throw new Error("@softure-ai/mcp-access: the factory has no toolListVersion; build it with createMcpServerFactory or pass toolListVersion to createMcpEndpoint");
+    }
+    return reader(identity);
+}
+//# sourceMappingURL=sessions.js.map

package/dist/testing/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../src/testing/sessions.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,uBAAuB,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AACnG,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9E,MAAM,MAAM,GAAsB,EAAE,MAAM,EAAE,sCAAsC,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;AAChI,MAAM,MAAM,GAAsB,EAAE,GAAG,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAChE,MAAM,MAAM,GAAG;IACb,CAAC,MAAM,EAAE,MAAM,CAAC;IAChB,CAAC,OAAO,EAAE,MAAM,CAAC;CACT,CAAC;AAEX;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,MAAwB,EAAE,KAAuB;IAClG,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG,uBAAuB,CAAC,MAAM,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC/E,MAAM,SAAS,GAAG,wBAAwB,CAAC,SAAS,EAAE,MAAM,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC1F,MAAM,UAAU,GAAG,mBAAmB,CAAC,MAAM,eAAe,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,mBAAmB,CAAC,MAAM,eAAe,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC5J,IAAI,CAAC,UAAU;YAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvC,IAAI,UAAU,IAAI,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,KAAK,wDAAwD,CAAC,CAAC;QACjH,IAAI,CAAC,UAAU,IAAI,CAAC,SAAS;YAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,KAAK,kEAAkE,CAAC,CAAC;IAC/H,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;QAAE,QAAQ,CAAC,IAAI,CAAC,sDAAsD,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrI,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iEAAiE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACnI,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,OAAyB,EAAE,QAA2B;IAC/E,MAAM,MAAM,GAAI,OAA8C,CAAC,eAAe,CAAC;IAC/E,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,+IAA+I,CAAC,CAAC;IACnK,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC1B,CAAC"}

package/module.json

@@ -1,6 +1,6 @@
 {
   "id": "mcp-access",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "dependsOn": { "security": "^0.2.0", "auth": "^0.2.0", "jobs": "^0.1.1?", "ops": "^0.2.0?" },
   "dbSchema": "mcp",
   "tables": ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants", "oauth_registration_window", "used_confirmations", "operation_tasks"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/mcp-access",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "SOFTURE AI MCP access module: hashed, scoped, expiring access tokens, a rate-limited Bearer endpoint around the app's MCP server factory, and a token page with client setup instructions for Next.js; tool result helpers with a safe error boundary, a stdio entry, a catalog parity check and the softure-mcp prune command.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -51,7 +51,7 @@ export const API_TOKEN_RATE_LIMIT_BUCKETS = {
 export const mcpAccess = defineModule({
   manifest: {
     id: MODULE_ID,
-    version: "0.4.0",
+    version: "0.5.0",
     dependsOn: { security: "^0.2.0", auth: "^0.2.0", jobs: "^0.1.1?", ops: "^0.2.0?" },
     dbSchema: "mcp",
     tables: ["access_tokens", "oauth_clients", "oauth_authorization_codes", "oauth_grants", "oauth_registration_window", "used_confirmations", "operation_tasks"],

package/src/server/endpoint.ts

@@ -19,6 +19,14 @@ import { getProtectedResourceMetadataUrl, isOAuthEnabled } from "./oauth-http.js
 import { resolveMcpOrigins } from "./origins.js";
 import { MCP_READ_SCOPE, MCP_WRITE_SCOPE } from "./scopes.js";
 import { verifyAccessToken, type McpAccessContext } from "./tokens.js";
+import {
+  createSessionRenewalResponse,
+  createToolListSessionId,
+  isInitializeRequest,
+  isToolListSessionCurrent,
+  MCP_SESSION_ID_HEADER,
+  rewriteInitializeAnswer,
+} from "./tool-list-session.js";
 import { isWritingEnabled } from "./writes-switch.js";
 
 export { MCP_READ_SCOPE, MCP_WRITE_SCOPE };
@@ -37,8 +45,21 @@ const NO_STORE = { "cache-control": "no-store" };
 /** The app's MCP server for one request. It registers write tools only when `canWrite` is true. */
 export type McpServerFactory = (identity: McpServerIdentity) => McpServer | Server | Promise<McpServer | Server>;
 
+/** Reads the tool list version the factory's servers answer at `initialize` for the identity. */
+export type ToolListVersionReader = (identity: McpServerIdentity) => Promise<string>;
+
+/** A factory that can tell its tool list version without building a server; `createMcpServerFactory` returns one. */
+export interface VersionedMcpServerFactory extends McpServerFactory {
+  readonly toolListVersion: ToolListVersionReader;
+}
+
 export interface McpEndpointOptions {
-  readonly createServer: McpServerFactory;
+  readonly createServer: McpServerFactory | VersionedMcpServerFactory;
+  /**
+   * The tool list version per identity, for sessions tied to it (#1055). Default: the factory's own
+   * `toolListVersion` (`createMcpServerFactory`). Without either, the endpoint issues no session id.
+   */
+  readonly toolListVersion?: ToolListVersionReader;
 }
 
 /** Serves one request to the MCP endpoint. */
@@ -50,7 +71,8 @@ export type McpEndpoint = (ctx: McpAccessContext, request: Request) => Promise<R
  * (`responseMode: "json"`): a stream would add proxy buffering and timeouts for no tool that needs
  * it, and mid-call notifications are dropped.
  */
-export function createMcpEndpoint({ createServer }: McpEndpointOptions): McpEndpoint {
+export function createMcpEndpoint({ createServer, toolListVersion }: McpEndpointOptions): McpEndpoint {
+  const readToolListVersion = toolListVersion ?? getFactoryToolListVersion(createServer);
   const handler = createMcpHandler(
     (requestContext) => createServer(readIdentity(requestContext.authInfo)),
     {
@@ -83,8 +105,40 @@ export function createMcpEndpoint({ createServer }: McpEndpointOptions): McpEndp
 
     const authInfo = await authenticate(ctx, request);
     if (authInfo instanceof Response) return authInfo;
-    return handler.fetch(request, { authInfo });
+    return serveInSession(request, authInfo);
   };
+
+  /**
+   * Sessions tied to the tool list version (#1055): a session from another version (a release changed a tool, or the
+   * access level changed) answers 404, so the client initializes again and lists the tools again; `initialize` gets a
+   * new session id. A request without a session id is served as it always was.
+   */
+  async function serveInSession(request: Request, authInfo: AuthInfo): Promise<Response> {
+    const sessionId = request.headers.get(MCP_SESSION_ID_HEADER);
+    const isInitialize = sessionId === null && (await isInitializeRequest(request, MAX_MCP_REQUEST_BYTES));
+    if (readToolListVersion === undefined || (sessionId === null && !isInitialize)) {
+      const response = await handler.fetch(request, { authInfo });
+      return isInitialize ? rewriteInitializeAnswer(response, null) : response;
+    }
+    let version;
+    try {
+      version = await readToolListVersion(readIdentity(authInfo));
+    } catch (error) {
+      // Without the version no session can be checked or issued: serve the request statelessly, as before #1055.
+      console.error(`@softure-ai/mcp-access: reading the tool list version failed: ${errorLogLabel(error)}`);
+      const response = await handler.fetch(request, { authInfo });
+      return isInitialize ? rewriteInitializeAnswer(response, null) : response;
+    }
+    if (sessionId !== null) {
+      return isToolListSessionCurrent(sessionId, version) ? handler.fetch(request, { authInfo }) : createSessionRenewalResponse();
+    }
+    return rewriteInitializeAnswer(await handler.fetch(request, { authInfo }), createToolListSessionId(version));
+  }
+}
+
+/** The factory's own version reader, when it has one (`createMcpServerFactory`). */
+function getFactoryToolListVersion(factory: McpServerFactory | VersionedMcpServerFactory): ToolListVersionReader | undefined {
+  return "toolListVersion" in factory && typeof factory.toolListVersion === "function" ? factory.toolListVersion : undefined;
 }
 
 /**

package/src/server/index.ts

@@ -9,6 +9,8 @@ export {
   type McpEndpoint,
   type McpEndpointOptions,
   type McpServerFactory,
+  type ToolListVersionReader,
+  type VersionedMcpServerFactory,
 } from "./endpoint.js";
 export { actionTool, toFormData, type ActionToolOptions, type FormActionHandler } from "./action-tool.js";
 export {
@@ -155,6 +157,12 @@ export {
   type ServedTool,
   type ToolListMeasurement,
 } from "./tool-list.js";
+export {
+  createToolListSessionId,
+  isToolListSessionCurrent,
+  MCP_SESSION_ID_HEADER,
+  readToolListSessionVersion,
+} from "./tool-list-session.js";
 export {
   toolError,
   toolResult,

package/src/server/server-factory.ts

@@ -10,7 +10,7 @@
 //   });
 import { McpServer, type McpServerOptions } from "@modelcontextprotocol/server";
 import type { McpServerIdentity } from "../contract.js";
-import type { McpServerFactory } from "./endpoint.js";
+import type { VersionedMcpServerFactory } from "./endpoint.js";
 import { withStrictToolInput, type StrictToolInputOptions } from "./strict-input.js";
 import { registerServerInfoTool, type ServerInfoToolOptions } from "./server-info.js";
 import { measureToolList, type ToolListMeasurement } from "./tool-list.js";
@@ -39,8 +39,12 @@ export interface McpServerFactoryOptions {
   readonly serverInfoTool?: ServerInfoToolOptions;
 }
 
-/** An `McpServerFactory` whose servers carry the tool list's version for the identity's access level. */
-export function createMcpServerFactory(options: McpServerFactoryOptions): McpServerFactory {
+/**
+ * An `McpServerFactory` whose servers carry the tool list's version for the identity's access level. Its
+ * `toolListVersion(identity)` reads that version without building a server, so `createMcpEndpoint` ties each session
+ * to it (#1055).
+ */
+export function createMcpServerFactory(options: McpServerFactoryOptions): VersionedMcpServerFactory {
   const strictOptions = options.strictToolInput === true ? {} : options.strictToolInput === false ? undefined : options.strictToolInput;
   // The served version reaches `get_server_info` here; the recording server registers it with a placeholder, since
   // its handler never runs there and the version is not part of the listed tool.
@@ -66,8 +70,9 @@ export function createMcpServerFactory(options: McpServerFactoryOptions): McpSer
     return measurement;
   };
 
-  return async (identity) => {
-    const version = options.version ?? (await measure(identity)).toolListVersion;
+  const toolListVersion = async (identity: McpServerIdentity): Promise<string> => options.version ?? (await measure(identity)).toolListVersion;
+  const factory = async (identity: McpServerIdentity): Promise<McpServer> => {
+    const version = await toolListVersion(identity);
     const server = new McpServer(
       { name: options.name, version, ...(options.title === undefined ? {} : { title: options.title }) },
       options.serverOptions,
@@ -75,4 +80,5 @@ export function createMcpServerFactory(options: McpServerFactoryOptions): McpSer
     await registerTools(server, identity, version);
     return server;
   };
+  return Object.assign(factory, { toolListVersion });
 }

package/src/server/tool-list-session.ts

@@ -0,0 +1,103 @@
+// Sessions tied to the tool list version (#1055). A hosted client keeps its cached `tools/list` for as long as its
+// connection lives, even after a release changed a tool, and the endpoint has no channel to send
+// `notifications/tools/list_changed`. So the endpoint answers `initialize` with an `Mcp-Session-Id` that carries the
+// tool list version of the identity's access level, and a later request whose session carries another version gets
+// `404 Not Found`: Streamable HTTP defines that as "start a new session", so the client initializes again and lists
+// the tools again. Nothing is stored: the id itself holds the version, so any instance can check it.
+import { randomBytes } from "node:crypto";
+
+/** The header that carries the session id, both ways. */
+export const MCP_SESSION_ID_HEADER = "mcp-session-id";
+
+/** Random bytes after the version, as hex. */
+const RANDOM_BYTES = 16;
+const SESSION_ID_PATTERN = /^([A-Za-z0-9_-]+)\.[0-9a-f]+$/;
+const SSE_DATA_PREFIX = "data: ";
+
+/** A new session id for the version: `<base64url(version)>.<32 hex>`, visible ASCII whatever the version holds. */
+export function createToolListSessionId(toolListVersion: string): string {
+  return `${Buffer.from(toolListVersion, "utf8").toString("base64url")}.${randomBytes(RANDOM_BYTES).toString("hex")}`;
+}
+
+/** The tool list version a session id carries, or `null` when the id is not one the endpoint issues. */
+export function readToolListSessionVersion(sessionId: string): string | null {
+  const match = SESSION_ID_PATTERN.exec(sessionId);
+  if (match?.[1] === undefined) return null;
+  return Buffer.from(match[1], "base64url").toString("utf8");
+}
+
+/** Whether a request in this session may be served: its version is the current one. */
+export function isToolListSessionCurrent(sessionId: string, toolListVersion: string): boolean {
+  return readToolListSessionVersion(sessionId) === toolListVersion;
+}
+
+/** The answer to a request in a session from another tool list version: the client starts a new session. */
+export function createSessionRenewalResponse(): Response {
+  return Response.json(
+    { jsonrpc: "2.0", error: { code: -32001, message: "Session not found: the tool list changed, initialize again" }, id: null },
+    { status: 404, headers: { "cache-control": "no-store" } },
+  );
+}
+
+/**
+ * Whether the request is a JSON-RPC `initialize`: a POST without a session id whose JSON body asks for it. The body
+ * is read from a clone, and a body over `maxBytes` is not read (the SDK refuses it with 413 anyway).
+ */
+export async function isInitializeRequest(request: Request, maxBytes: number): Promise<boolean> {
+  if (request.method !== "POST" || request.headers.has(MCP_SESSION_ID_HEADER)) return false;
+  const length = Number(request.headers.get("content-length") ?? "0");
+  if (!Number.isFinite(length) || length > maxBytes) return false;
+  let body: unknown;
+  try {
+    const text = await request.clone().text();
+    if (text.length > maxBytes) return false;
+    body = JSON.parse(text);
+  } catch {
+    // Not JSON: the SDK answers the parse error itself.
+    return false;
+  }
+  return typeof body === "object" && body !== null && !Array.isArray(body) && (body as { method?: unknown }).method === "initialize";
+}
+
+/**
+ * The `initialize` answer with `capabilities.tools.listChanged: false`, since no answer of the endpoint ever carries
+ * the notification, and with the session id when there is one. The body keeps its format (JSON or one SSE event);
+ * an answer that is not a successful `InitializeResult` is returned as it is.
+ */
+export async function rewriteInitializeAnswer(response: Response, sessionId: string | null): Promise<Response> {
+  if (response.status !== 200) return response;
+  const text = await response.text();
+  const isEventStream = (response.headers.get("content-type") ?? "").includes("text/event-stream");
+  const lines = text.split("\n");
+  const dataIndex = isEventStream ? lines.findIndex((line) => line.startsWith(SSE_DATA_PREFIX)) : -1;
+  const json = isEventStream ? (dataIndex === -1 ? null : (lines[dataIndex] ?? "").slice(SSE_DATA_PREFIX.length)) : text;
+
+  const answer = parseInitializeAnswer(json);
+  const headers = new Headers(response.headers);
+  // The body changes length, so the old one would be wrong.
+  headers.delete("content-length");
+  const tools = answer?.result?.capabilities?.tools;
+  if (answer === null || answer.result?.protocolVersion === undefined) {
+    return new Response(text, { status: response.status, statusText: response.statusText, headers });
+  }
+  if (tools !== undefined && tools !== null && typeof tools === "object") tools.listChanged = false;
+  if (sessionId !== null) headers.set(MCP_SESSION_ID_HEADER, sessionId);
+
+  const rewritten = JSON.stringify(answer);
+  if (isEventStream) lines[dataIndex] = `${SSE_DATA_PREFIX}${rewritten}`;
+  return new Response(isEventStream ? lines.join("\n") : rewritten, { status: response.status, statusText: response.statusText, headers });
+}
+
+/** The answer as JSON, or `null` when there is none or it is not JSON (the SDK's own error text). */
+function parseInitializeAnswer(json: string | null): InitializeAnswer | null {
+  if (json === null) return null;
+  try {
+    return JSON.parse(json) as InitializeAnswer;
+  } catch {
+    return null;
+  }
+}
+
+interface InitializeAnswer {
+  result?: { protocolVersion?: unknown; capabilities?: { tools?: { listChanged?: boolean } | null } };
+}

package/src/testing/index.ts

@@ -6,3 +6,4 @@ export {
   type ServedToolLists,
   type ToolCatalogDifferences,
 } from "./catalog.js";
+export { expectToolListSessionRenewed } from "./sessions.js";

package/src/testing/sessions.ts

@@ -0,0 +1,41 @@
+// Sessions tied to the tool list version (#1055), checked on the app's factories: a release that changes a tool must
+// renew the sessions opened before it, or a connected client keeps the old schemas. Framework-free: it throws.
+import type { McpServerIdentity } from "../contract.js";
+import type { McpServerFactory, VersionedMcpServerFactory } from "../server/endpoint.js";
+import { createToolListSessionId, isToolListSessionCurrent } from "../server/tool-list-session.js";
+import { fingerprintToolList, listServedTools } from "../server/tool-list.js";
+
+const READER: McpServerIdentity = { userId: "00000000-0000-4000-8000-000000000001", canWrite: false, tokenId: "session-check" };
+const WRITER: McpServerIdentity = { ...READER, canWrite: true };
+const LEVELS = [
+  ["read", READER],
+  ["write", WRITER],
+] as const;
+
+/**
+ * Throws unless a session opened under `before` (the previous release's factory) is renewed under `after` for every
+ * access level whose served tool list changed, and kept for every level whose list did not. A pair where no level
+ * changed throws too: the check would prove nothing.
+ */
+export async function expectToolListSessionRenewed(before: McpServerFactory, after: McpServerFactory): Promise<void> {
+  const problems: string[] = [];
+  const unchanged: string[] = [];
+  for (const [level, identity] of LEVELS) {
+    const sessionId = createToolListSessionId(await readVersion(before, identity));
+    const isCurrent = isToolListSessionCurrent(sessionId, await readVersion(after, identity));
+    const hasChanged = fingerprintToolList(await listServedTools(() => before(identity))) !== fingerprintToolList(await listServedTools(() => after(identity)));
+    if (!hasChanged) unchanged.push(level);
+    if (hasChanged && isCurrent) problems.push(`the ${level} tool list changed but a session opened before is kept`);
+    if (!hasChanged && !isCurrent) problems.push(`the ${level} tool list did not change but a session opened before is renewed`);
+  }
+  if (unchanged.length === LEVELS.length) problems.push(`the tool list did not change for any access level (${unchanged.join(", ")})`);
+  if (problems.length > 0) throw new Error(`@softure-ai/mcp-access: sessions do not follow the tool list: ${problems.join("; ")}`);
+}
+
+async function readVersion(factory: McpServerFactory, identity: McpServerIdentity): Promise<string> {
+  const reader = (factory as Partial<VersionedMcpServerFactory>).toolListVersion;
+  if (typeof reader !== "function") {
+    throw new Error("@softure-ai/mcp-access: the factory has no toolListVersion; build it with createMcpServerFactory or pass toolListVersion to createMcpEndpoint");
+  }
+  return reader(identity);
+}