effect 4.0.7 → 4.1.0

package/src/ai/internal/mcpCore.ts

@@ -149,6 +149,20 @@ export class UnsupportedByProtocol extends Data.TaggedError("UnsupportedByProtoc
   readonly feature: string
 }> {}
 
+/**
+ * A request rejected outside the handler, for example by MCP middleware.
+ * Adapters send it as a JSON-RPC error with its code, message and data, never
+ * as a tool result. `error` keeps the original failure for in-process callers.
+ *
+ * @internal
+ */
+export class RequestRejected extends Data.TaggedError("RequestRejected")<{
+  readonly code: number
+  readonly message: string
+  readonly data?: unknown
+  readonly error: McpSchema.McpErrorBase
+}> {}
+
 /**
  * @internal
  */
@@ -157,6 +171,7 @@ export type ToolError =
   | InvalidToolInput
   | InvalidToolContinuation
   | ToolExecutionError
+  | RequestRejected
 
 /**
  * @internal
@@ -166,12 +181,13 @@ export interface ToolRegistration {
   // `tool.title ?? tool.annotations?.title` at the public boundary.
   readonly descriptor: McpSchema.Tool
   readonly isVisible: (profile: NegotiatedProtocolProfile<string>) => boolean
+  readonly visible?: Visible | undefined
   readonly handle: (
     call: typeof McpSchema.CallTool.payloadSchema.Type,
     invocation: McpInvocation
   ) => Effect.Effect<
     OperationOutcome<McpSchema.CallToolResult>,
-    InvalidToolInput | InvalidToolContinuation | ToolExecutionError,
+    ToolNotFound | InvalidToolInput | InvalidToolContinuation | ToolExecutionError | RequestRejected,
     never
   >
 }
@@ -184,8 +200,13 @@ export interface Tools {
     registration: ToolRegistration
   ) => Effect.Effect<void>
   readonly list: (
+    invocation: McpInvocation
+  ) => Effect.Effect<ReadonlyArray<McpSchema.Tool>, RequestRejected>
+  // Skips request-level visibility checks.
+  readonly find: (
+    name: string,
     profile: NegotiatedProtocolProfile<string>
-  ) => Effect.Effect<ReadonlyArray<McpSchema.Tool>>
+  ) => McpSchema.Tool | undefined
   readonly call: (
     call: typeof McpSchema.CallTool.payloadSchema.Type,
     invocation: McpInvocation
@@ -198,9 +219,10 @@ export interface Tools {
 export interface ResourceRegistration {
   readonly descriptor: McpSchema.Resource
   readonly isVisible: (profile: NegotiatedProtocolProfile<string>) => boolean
+  readonly visible?: Visible | undefined
   readonly read: (
     invocation: McpInvocation
-  ) => Effect.Effect<McpSchema.ReadResourceResult, McpSchema.InternalError>
+  ) => Effect.Effect<McpSchema.ReadResourceResult, ResourceNotFound | McpSchema.InternalError | RequestRejected>
 }
 
 /**
@@ -209,12 +231,16 @@ export interface ResourceRegistration {
 export interface ResourceTemplateRegistration {
   readonly descriptor: McpSchema.ResourceTemplate
   readonly isVisible: (profile: NegotiatedProtocolProfile<string>) => boolean
+  readonly visible?: Visible | undefined
   readonly match: (uri: string) => ReadonlyArray<string> | undefined
   readonly read: (
     uri: string,
     params: ReadonlyArray<string>,
     invocation: McpInvocation
-  ) => Effect.Effect<McpSchema.ReadResourceResult, McpSchema.InvalidParams | McpSchema.InternalError>
+  ) => Effect.Effect<
+    McpSchema.ReadResourceResult,
+    ResourceNotFound | McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected
+  >
 }
 
 /**
@@ -224,17 +250,17 @@ export interface Resources {
   readonly register: (registration: ResourceRegistration) => Effect.Effect<void>
   readonly registerTemplate: (registration: ResourceTemplateRegistration) => Effect.Effect<void>
   readonly list: (
-    profile: NegotiatedProtocolProfile<string>
-  ) => Effect.Effect<ReadonlyArray<McpSchema.Resource>>
+    invocation: McpInvocation
+  ) => Effect.Effect<ReadonlyArray<McpSchema.Resource>, RequestRejected>
   readonly listTemplates: (
-    profile: NegotiatedProtocolProfile<string>
-  ) => Effect.Effect<ReadonlyArray<McpSchema.ResourceTemplate>>
+    invocation: McpInvocation
+  ) => Effect.Effect<ReadonlyArray<McpSchema.ResourceTemplate>, RequestRejected>
   readonly read: (
     uri: string,
     invocation: McpInvocation
   ) => Effect.Effect<
     McpSchema.ReadResourceResult,
-    ResourceNotFound | McpSchema.InvalidParams | McpSchema.InternalError
+    ResourceNotFound | McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected
   >
 }
 
@@ -251,10 +277,14 @@ export class PromptNotFound extends Data.TaggedError("PromptNotFound")<{
 export interface PromptRegistration {
   readonly descriptor: McpSchema.Prompt
   readonly isVisible: (profile: NegotiatedProtocolProfile<string>) => boolean
+  readonly visible?: Visible | undefined
   readonly get: (
     args: Readonly<Record<string, string>>,
     invocation: McpInvocation
-  ) => Effect.Effect<OperationOutcome<McpSchema.GetPromptResult>, McpSchema.InvalidParams | McpSchema.InternalError>
+  ) => Effect.Effect<
+    OperationOutcome<McpSchema.GetPromptResult>,
+    PromptNotFound | McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected
+  >
 }
 
 /**
@@ -263,15 +293,15 @@ export interface PromptRegistration {
 export interface Prompts {
   readonly register: (registration: PromptRegistration) => Effect.Effect<void>
   readonly list: (
-    profile: NegotiatedProtocolProfile<string>
-  ) => Effect.Effect<ReadonlyArray<McpSchema.Prompt>>
+    invocation: McpInvocation
+  ) => Effect.Effect<ReadonlyArray<McpSchema.Prompt>, RequestRejected>
   readonly get: (
     name: string,
     args: Readonly<Record<string, string>>,
     invocation: McpInvocation
   ) => Effect.Effect<
     OperationOutcome<McpSchema.GetPromptResult>,
-    PromptNotFound | McpSchema.InvalidParams | McpSchema.InternalError
+    PromptNotFound | McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected
   >
 }
 
@@ -314,12 +344,12 @@ export interface Completions {
     complete: (
       request: CompletionRequest,
       invocation: McpInvocation
-    ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError>
+    ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected>
   ) => Effect.Effect<void>
   readonly complete: (
     request: CompletionRequest,
     invocation: McpInvocation
-  ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError>
+  ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected>
 }
 
 /**
@@ -400,6 +430,14 @@ export interface McpCore {
   }>
 }
 
+/**
+ * Runs the request-level visibility checks of a registration on a list
+ * request, after `isVisible` passed.
+ *
+ * @internal
+ */
+export type Visible = (invocation: McpInvocation) => Effect.Effect<boolean, RequestRejected>
+
 /**
  * @internal
  */
@@ -413,24 +451,35 @@ export const make: Effect.Effect<McpCore> = Effect.sync(() => {
     (
       request: CompletionRequest,
       invocation: McpInvocation
-    ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError>
+    ) => Effect.Effect<CompletionResult, McpSchema.InvalidParams | McpSchema.InternalError | RequestRejected>
   >()
 
+  const filterList = <D>(
+    registrations: Iterable<{
+      readonly descriptor: D
+      readonly isVisible: ToolRegistration["isVisible"]
+      readonly visible?: Visible | undefined
+    }>,
+    invocation: McpInvocation
+  ): Effect.Effect<ReadonlyArray<D>, RequestRejected> =>
+    Effect.map(
+      Effect.filter(
+        Arr.filter(registrations, (entry) => entry.isVisible(invocation.protocol)),
+        (entry) => entry.visible === undefined ? Effect.succeed(true) : entry.visible(invocation)
+      ),
+      (entries) => entries.map((entry) => entry.descriptor)
+    )
+
   const tools: Tools = {
     register: (registration) =>
       Effect.sync(() => {
         registrations.set(registration.descriptor.name, registration)
       }),
-    list: (profile) =>
-      Effect.sync(() => {
-        const descriptors: Array<McpSchema.Tool> = []
-        for (const registration of registrations.values()) {
-          if (registration.isVisible(profile)) {
-            descriptors.push(registration.descriptor)
-          }
-        }
-        return descriptors
-      }),
+    list: (invocation) => filterList(registrations.values(), invocation),
+    find: (name, profile) => {
+      const registration = registrations.get(name)
+      return registration !== undefined && registration.isVisible(profile) ? registration.descriptor : undefined
+    },
     call: (call, invocation) =>
       Effect.suspend((): Effect.Effect<OperationOutcome<McpSchema.CallToolResult>, ToolError> => {
         const registration = registrations.get(call.name)
@@ -465,18 +514,8 @@ export const make: Effect.Effect<McpCore> = Effect.sync(() => {
           resourceTemplateRegistrations[index] = registration
         }
       }),
-    list: (profile) =>
-      Effect.sync(() =>
-        resourceRegistrations
-          .filter((entry) => entry.isVisible(profile))
-          .map((entry) => entry.descriptor)
-      ),
-    listTemplates: (profile) =>
-      Effect.sync(() =>
-        resourceTemplateRegistrations
-          .filter((entry) => entry.isVisible(profile))
-          .map((entry) => entry.descriptor)
-      ),
+    list: (invocation) => filterList(resourceRegistrations, invocation),
+    listTemplates: (invocation) => filterList(resourceTemplateRegistrations, invocation),
     read: Effect.fnUntraced(function*(uri, invocation) {
       const resource = resourceRegistrations.find((entry) => entry.descriptor.uri === uri)
       if (resource !== undefined && resource.isVisible(invocation.protocol)) {
@@ -497,12 +536,7 @@ export const make: Effect.Effect<McpCore> = Effect.sync(() => {
       Effect.sync(() => {
         promptRegistrations.set(registration.descriptor.name, registration)
       }),
-    list: (profile) =>
-      Effect.sync(() =>
-        Array.from(promptRegistrations.values())
-          .filter((entry) => entry.isVisible(profile))
-          .map((entry) => entry.descriptor)
-      ),
+    list: (invocation) => filterList(promptRegistrations.values(), invocation),
     get: Effect.fnUntraced(function*(name, args, invocation) {
       const registration = promptRegistrations.get(name)
       if (registration === undefined || !registration.isVisible(invocation.protocol)) {

package/src/ai/internal/mcpProtocol/v2024_11_05.ts

@@ -154,12 +154,10 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(Effect.map((resources) => McpSchema.ListResourcesResult.make({ resources }))),
       "resources/templates/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) => McpSchema.ListResourceTemplatesResult.make({ resourceTemplates }))
         ),
       "resources/read": Effect.fnUntraced(function*({ uri }) {
@@ -189,7 +187,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) =>
               McpSchema.ListPromptsResult.make({
@@ -249,8 +247,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        return yield* core.tools.list(McpProtocol.profileFromClient(request)).pipe(
+        return yield* McpProtocol.listForClient(core.tools.list).pipe(
           Effect.map((tools) =>
             McpSchema.ListToolsResult.make({
               tools: tools.map((tool) =>

package/src/ai/internal/mcpProtocol/v2025_03_26.ts

@@ -166,7 +166,7 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(
             Effect.map((resources) =>
               McpSchema.ListResourcesResult.make({
@@ -182,9 +182,7 @@ export const protocol = McpProtocol.make({
             )
           ),
       "resources/templates/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) =>
             McpSchema.ListResourceTemplatesResult.make({
               resourceTemplates: resourceTemplates.map((template) => ({
@@ -212,7 +210,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) =>
               McpSchema.ListPromptsResult.make({
@@ -272,8 +270,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        const tools = yield* core.tools.list(McpProtocol.profileFromClient(request))
+        const tools = yield* McpProtocol.listForClient(core.tools.list)
         return McpSchema.ListToolsResult.make({
           tools: tools.map((tool) =>
             McpSchema.Tool.make({

package/src/ai/internal/mcpProtocol/v2025_06_18.ts

@@ -182,14 +182,12 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(
             Effect.map((resources) => McpSchema.ListResourcesResult.make({ resources }))
           ),
       "resources/templates/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) => McpSchema.ListResourceTemplatesResult.make({ resourceTemplates }))
         ),
       "resources/read": Effect.fnUntraced(function*({ uri }) {
@@ -207,7 +205,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": (_pageRequest) =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) => McpSchema.ListPromptsResult.make({ prompts }))
           ),
@@ -262,8 +260,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        const tools = yield* core.tools.list(McpProtocol.profileFromClient(request))
+        const tools = yield* McpProtocol.listForClient(core.tools.list)
         return McpSchema.ListToolsResult.make({
           tools: tools.map((tool) =>
             McpSchema.Tool.make({

package/src/ai/internal/mcpProtocol/v2025_11_25.ts

@@ -177,7 +177,7 @@ export const protocol = McpProtocol.make({
       "notifications/roots/list_changed": (_, { client, headers }) =>
         lifecycle.clientNotification(McpCore.ClientNotification.RootsChanged(), client.id, headers),
       "resources/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) => core.resources.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.resources.list)
           .pipe(
             Effect.map((resources) =>
               McpSchema.ListResourcesResult.make({
@@ -186,9 +186,7 @@ export const protocol = McpProtocol.make({
             )
           ),
       "resources/templates/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) =>
-          core.resources.listTemplates(McpProtocol.profileFromClient(request))
-        ).pipe(
+        McpProtocol.listForClient(core.resources.listTemplates).pipe(
           Effect.map((resourceTemplates) =>
             McpSchema.ListResourceTemplatesResult.make({
               resourceTemplates: resourceTemplates.map((resourceTemplate) =>
@@ -226,7 +224,7 @@ export const protocol = McpProtocol.make({
       "resources/unsubscribe": ({ uri }, { client, headers }) =>
         lifecycle.unsubscribe(uri, client.id, headers).pipe(Effect.as({})),
       "prompts/list": () =>
-        PublicMcpSchema.McpServerClient.use((request) => core.prompts.list(McpProtocol.profileFromClient(request)))
+        McpProtocol.listForClient(core.prompts.list)
           .pipe(
             Effect.map((prompts) =>
               McpSchema.ListPromptsResult.make({
@@ -285,8 +283,7 @@ export const protocol = McpProtocol.make({
         })
       }),
       "tools/list": Effect.fnUntraced(function*() {
-        const request = yield* PublicMcpSchema.McpServerClient
-        const tools = yield* core.tools.list(McpProtocol.profileFromClient(request))
+        const tools = yield* McpProtocol.listForClient(core.tools.list)
         return McpSchema.ListToolsResult.make({
           tools: tools.map((tool) =>
             McpSchema.Tool.make({

package/src/ai/internal/mcpProtocol/v2026_07_28.ts

@@ -327,6 +327,11 @@ export const makeHandlers = (
     context.serverInfo.extensions,
     (value): value is Readonly<Record<string, unknown>> => Predicate.isReadonlyObject(value)
   )
+  // Project only the wire fields; structurally compatible hints can carry extra properties.
+  const cacheHint = (family: keyof McpProtocol.CacheHints) => {
+    const hint = context.serverInfo.cacheHints?.[family]
+    return hint === undefined ? privateStaleCache : { ttlMs: hint.ttlMs, cacheScope: hint.cacheScope }
+  }
   const getDiscovery = Effect.map(context.registrationPresence, (presence) => {
     const capabilities: Types.Mutable<typeof McpSchema.ServerCapabilities.Type> = { completions: {}, logging: {} }
     if (extensions !== undefined) capabilities.extensions = extensions
@@ -483,7 +488,7 @@ export const makeHandlers = (
     ) {
       const discovery = yield* getDiscovery
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("discover"),
         supportedVersions: Array.from(discovery.supportedVersions),
         capabilities: discovery.capabilities,
         instructions: context.serverInfo.instructions
@@ -494,9 +499,9 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListResources.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const resources = yield* core.resources.list(invocation.protocol)
+      const resources = yield* core.resources.list(invocation)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("resources"),
         resources: resources.map(projectResource)
       }, context.serverInfo)
       return yield* decodeListResourcesResult(result)
@@ -505,9 +510,9 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListResourceTemplates.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const resourceTemplates = yield* core.resources.listTemplates(invocation.protocol)
+      const resourceTemplates = yield* core.resources.listTemplates(invocation)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("resourceTemplates"),
         resourceTemplates: resourceTemplates.map(projectResourceTemplate)
       }, context.serverInfo)
       return yield* decodeListResourceTemplatesResult(result)
@@ -537,10 +542,10 @@ export const makeHandlers = (
         )
       }
       const invocation = yield* getInvocation
-      const prompts = yield* core.prompts.list(invocation.protocol)
+      const prompts = yield* core.prompts.list(invocation)
       const projectedPrompts = yield* Effect.forEach(prompts, projectPrompt)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("prompts"),
         prompts: projectedPrompts
       }, context.serverInfo)
       return yield* decodeListPromptsResult(result)
@@ -593,17 +598,17 @@ export const makeHandlers = (
       _request: typeof McpSchema.ListTools.payloadSchema.Type
     ) {
       const invocation = yield* getInvocation
-      const tools = yield* core.tools.list(invocation.protocol)
+      const tools = yield* core.tools.list(invocation)
       const projectedTools = yield* Effect.forEach(tools, projectTool)
       const result = yield* projectCompleteResult({
-        ...privateStaleCache,
+        ...cacheHint("tools"),
         tools: projectedTools
       }, context.serverInfo)
       return yield* decodeListToolsResult(result)
     }, Effect.mapError(projectError)),
     "tools/call": Effect.fnUntraced(function*(request: typeof McpSchema.CallTool.payloadSchema.Type) {
       const invocation = yield* getInputInvocation(request)
-      const tool = (yield* core.tools.list(invocation.protocol)).find((tool) => tool.name === request.name)
+      const tool = core.tools.find(request.name, invocation.protocol)
       const httpRequest = yield* Effect.serviceOption(HttpServerRequest.HttpServerRequest)
 
       if (tool !== undefined && Option.isSome(httpRequest)) {

package/src/ai/internal/mcpProtocol.ts

@@ -16,6 +16,7 @@ import * as Schema from "../../Schema.ts"
 import type * as Scope from "../../Scope.ts"
 import type * as PublicMcpProtocol from "../McpProtocol.ts"
 import * as PublicMcpSchema from "../McpSchema.ts"
+import type * as PublicMcpServer from "../McpServer.ts"
 import * as McpCore from "./mcpCore.ts"
 
 const LEGACY_RESOURCE_NOT_FOUND_ERROR_CODE = -32002
@@ -95,6 +96,18 @@ export const invocationFromClient = (
   serverClient: request
 })
 
+/**
+ * Runs a core list operation for the legacy client of the current request.
+ *
+ * @internal
+ */
+export const listForClient = <A>(
+  list: (invocation: McpCore.McpInvocation) => Effect.Effect<A, McpCore.RequestRejected>
+): Effect.Effect<A, ProtocolError, PublicMcpSchema.McpServerClient> =>
+  PublicMcpSchema.McpServerClient.use((request) =>
+    list(invocationFromClient(request)).pipe(Effect.mapError(ProtocolError.fromFeature))
+  )
+
 /**
  * @internal
  */
@@ -212,6 +225,9 @@ export class ProtocolError extends Data.TaggedError("ProtocolError")<{
   static fromTool(
     error: McpCore.ToolError | McpCore.UnsupportedByProtocol
   ): ProtocolError {
+    if (error._tag === "RequestRejected") {
+      return new ProtocolError({ code: error.code, message: error.message, data: error.data })
+    }
     const message = Match.value(error).pipe(
       Match.tag("ToolNotFound", (error) => `Tool '${error.name}' not found`),
       Match.tag(
@@ -428,6 +444,7 @@ export interface HandlerInstallationContext {
     readonly websiteUrl?: string | undefined
     readonly icons?: ReadonlyArray<PublicMcpSchema.Icon> | undefined
     readonly extensions?: PublicMcpSchema.ServerCapabilities["extensions"] | undefined
+    readonly cacheHints?: CacheHints | undefined
   }
   readonly registrationPresence: Effect.Effect<{
     readonly tools: boolean
@@ -436,6 +453,18 @@ export interface HandlerInstallationContext {
   }>
 }
 
+/**
+ * Cache hints normalized to wire values when the server is constructed.
+ *
+ * @internal
+ */
+export type CacheHints = {
+  readonly [Family in keyof PublicMcpServer.CacheHints]?: {
+    readonly ttlMs: number
+    readonly cacheScope: "private"
+  }
+}
+
 /**
  * @internal
  */

package/src/ai/internal/mcpRuntime.ts

@@ -6,6 +6,7 @@
 import type { NonEmptyReadonlyArray } from "../../Array.ts"
 import * as Cause from "../../Cause.ts"
 import * as Context from "../../Context.ts"
+import * as SecureRandom from "../../crypto/SecureRandom.ts"
 import * as Effect from "../../Effect.ts"
 import type * as Headers from "../../http/Headers.ts"
 import { appendPreResponseHandlerUnsafe } from "../../http/HttpEffect.ts"
@@ -138,6 +139,7 @@ export interface HandlerInstallationOptions {
     readonly websiteUrl?: string | undefined
     readonly icons?: ReadonlyArray<PublicMcpSchema.Icon> | undefined
     readonly extensions?: NonNullable<PublicMcpSchema.ServerCapabilities["extensions"]> | undefined
+    readonly cacheHints?: McpProtocol.CacheHints | undefined
   }
 }
 
@@ -185,7 +187,8 @@ export interface ServerRuntimeShape {
     clientId: number,
     headers: Headers.Headers,
     notification: McpCore.ServerNotification,
-    fallbackLogLevel: LogLevel.LogLevel
+    fallbackLogLevel: LogLevel.LogLevel,
+    listChangeRevision: number | undefined
   ) => boolean
   readonly installHandlers: (
     options: HandlerInstallationOptions
@@ -506,8 +509,8 @@ export const make = Effect.fnUntraced(function*(
           })
       ),
     deliveryClientIds: () => stateful?.initializedClientIds() ?? [],
-    canDeliver: (clientId, headers, notification, fallback) =>
-      stateful?.canDeliver(clientId, headers, notification, fallback) ?? true,
+    canDeliver: (clientId, headers, notification, fallback, listChangeRevision) =>
+      stateful?.canDeliver(clientId, headers, notification, fallback, listChangeRevision) ?? true,
     installHandlers: Effect.fnUntraced(function*(options) {
       const contextMap = new Map<string, unknown>()
       const installationContext: McpProtocol.HandlerInstallationContext = {
@@ -561,10 +564,11 @@ export const make = Effect.fnUntraced(function*(
                 protocol: protocol as PublicMcpProtocol.ProtocolAdapter,
                 supportsResourceSubscriptions: httpRequest === undefined &&
                   capabilities.resources?.subscribe === true,
-                logLevel: options.defaultLogLevel
+                logLevel: options.defaultLogLevel,
+                listChangeRevision: options.getListChangeRevision?.() ?? 0
               }
               if (httpRequest !== undefined) {
-                const sessionId = crypto.randomUUID()
+                const sessionId = SecureRandom.uuidV4Unsafe()
                 stateful.registerHttp(sessionId, registration)
                 appendPreResponseHandlerUnsafe(
                   fiber.context,

package/src/ai/internal/mcpStatefulRuntime.ts

@@ -28,6 +28,7 @@ export interface Binding {
 
 interface Session extends Binding {
   readonly resourceSubscriptions: Set<string> | undefined
+  readonly listChangeRevision: number
   logLevel: SessionLogLevel
 }
 
@@ -37,6 +38,11 @@ interface Session extends Binding {
 export interface Registration extends Binding {
   readonly supportsResourceSubscriptions: boolean
   readonly logLevel: LogLevel.LogLevel
+  /**
+   * The server's list-change revision when the session initialized. Changes
+   * up to this revision are already reflected in what the client lists next.
+   */
+  readonly listChangeRevision: number
 }
 
 /**
@@ -67,7 +73,8 @@ export interface StatefulRuntime {
     clientId: number,
     headers: Headers.Headers,
     notification: McpCore.ServerNotification,
-    fallbackLogLevel: LogLevel.LogLevel
+    fallbackLogLevel: LogLevel.LogLevel,
+    listChangeRevision: number | undefined
   ) => boolean
   readonly effectLogLevel: (
     clientId: number,
@@ -84,6 +91,7 @@ const makeSession = (registration: Registration): Session => ({
   negotiatedProfile: registration.negotiatedProfile,
   protocol: registration.protocol,
   resourceSubscriptions: registration.supportsResourceSubscriptions ? new Set() : undefined,
+  listChangeRevision: registration.listChangeRevision,
   logLevel: { _tag: "Effect", level: registration.logLevel }
 })
 
@@ -157,8 +165,12 @@ export const make = (): StatefulRuntime => {
       return Effect.sync(() => subscriptions.delete(uri)).pipe(Effect.asVoid)
     },
     effectLogLevel,
-    canDeliver: (clientId, headers, notification, fallbackLogLevel) => {
+    canDeliver: (clientId, headers, notification, fallbackLogLevel, listChangeRevision) => {
       const session = resolveSession(clientId, headers)
+      if (listChangeRevision !== undefined) {
+        // A client without a session on this channel has not initialized.
+        return session !== undefined && listChangeRevision > session.listChangeRevision
+      }
       if (notification._tag === "LoggingMessage") {
         const minimum = session?.logLevel
         return minimum?._tag === "Mcp"