effect 4.0.7 → 4.1.0

package/dist/ai/McpServer.js

@@ -16,6 +16,7 @@ import * as Cause from "../Cause.js";
 import * as Context from "../Context.js";
 import * as Data from "../Data.js";
 import * as Deferred from "../Deferred.js";
+import * as Duration from "../Duration.js";
 import * as Effect from "../Effect.js";
 import * as ErrorReporter from "../ErrorReporter.js";
 import * as Exit from "../Exit.js";
@@ -43,6 +44,7 @@ import * as Schema from "../Schema.js";
 import * as SchemaAST from "../SchemaAST.js";
 import * as Scope from "../Scope.js";
 import * as Stream from "../Stream.js";
+import * as Tracer from "../Tracer.js";
 import * as AiError from "./AiError.js";
 import * as McpCore from "./internal/mcpCore.js";
 import * as McpProtocolInternal from "./internal/mcpProtocol.js";
@@ -106,8 +108,18 @@ const toInternalServerNotification = message => {
       return undefined;
   }
 };
-// Request services must come from the invocation, including when a handler is registered during a request.
-const omitRequestServices = /*#__PURE__*/Context.omit(McpRequestContext, McpServerClient, HttpServerRequest.HttpServerRequest, CurrentLogLevel);
+const middlewareKeyPrefix = "effect/ai/McpServer/Middleware-";
+// Do not capture request services or middleware stacks at registration.
+const requestServiceKeys = /*#__PURE__*/new Set([McpRequestContext.key, McpServerClient.key, HttpServerRequest.HttpServerRequest.key, HttpServerRequest.ParsedSearchParams.key, HttpRouter.RouteContext.key, CurrentLogLevel.key, Scope.Scope.key, Tracer.ParentSpan.key]);
+const omitRequestServices = context => {
+  const services = new Map();
+  for (const [key, value] of context.mapUnsafe) {
+    if (!requestServiceKeys.has(key) && !key.startsWith(middlewareKeyPrefix)) {
+      services.set(key, value);
+    }
+  }
+  return Context.makeUnsafe(services);
+};
 const provideInvocationContext = (effect, invocation) => {
   let provided = Effect.provideService(effect, McpRequestContext, invocation.requestContext);
   const requestMetadata = invocation.requestContext.requestMetadata;
@@ -117,6 +129,329 @@ const provideInvocationContext = (effect, invocation) => {
   }
   return invocation.serverClient === undefined ? provided : Effect.provideService(provided, McpServerClient, invocation.serverClient);
 };
+const MiddlewareTypeId = "~effect/ai/McpServer/Middleware";
+/**
+ * Creates MCP middleware that runs around `tools/call`, `resources/read`,
+ * `prompts/get` and `completion/complete` requests.
+ *
+ * **Details**
+ *
+ * Middleware is how request-level dependencies are satisfied: declare the
+ * services it provides with `middleware<{ provides: S }>()` and provide them to
+ * the handler effect. It receives the request headers, session id and request
+ * context, so it can resolve the current user per request.
+ *
+ * Pass a function, or an Effect that builds the function. Services the Effect
+ * reads are requirements of the middleware layer. Services the function reads
+ * per request, other than `McpRequestContext`, are per-request requirements
+ * of the result; see {@link Middleware} for how they are met.
+ *
+ * Failures must be `McpErrorBase` values. A middleware failure is sent as a
+ * JSON-RPC error with its `code`, `message` and `data`, never as a tool
+ * result. Pick custom codes from the implementation-defined range
+ * (-32000 to -32019): any numeric `code` is sent as is. Defects are logged,
+ * reported to the `ErrorReporter` and sent as `InternalError("Internal error")`.
+ * Interruption propagates.
+ *
+ * Local middleware runs inside global middleware, and middleware provided both
+ * locally and globally runs once. Middleware never runs for `initialize`. It
+ * runs for list requests only when it wraps a {@link visibility}, so that the
+ * visibility check can read the services it provides.
+ *
+ * **Example** (Resolving the current user per request)
+ *
+ * ```ts
+ * import { Context, Effect, Layer, Schema } from "effect"
+ * import { McpSchema, McpServer, Tool, Toolkit } from "effect/ai"
+ *
+ * class CurrentUser extends Context.Service<CurrentUser, { readonly id: string }>()("CurrentUser") {}
+ *
+ * class Unauthorized extends Schema.Error<Unauthorized>("Unauthorized")({
+ *   ...McpSchema.McpErrorBase.fields,
+ *   _tag: Schema.tag("Unauthorized"),
+ *   code: Schema.tag(-32001)
+ * }) {}
+ *
+ * const WhoAmI = Tool.make("WhoAmI", { success: Schema.String, dependencies: [CurrentUser] })
+ * const Tools = Toolkit.make(WhoAmI)
+ *
+ * const Auth = McpServer.middleware<{ provides: CurrentUser }>()((effect, { headers }) => {
+ *   const token = headers["authorization"]
+ *   return token === undefined
+ *     ? Effect.fail(new Unauthorized({ message: "Missing credentials" }))
+ *     : Effect.provideService(effect, CurrentUser, { id: token })
+ * })
+ *
+ * const Registrations = McpServer.toolkit(Tools).pipe(
+ *   Layer.provide(Auth.layer),
+ *   Layer.provide(Tools.toLayer({
+ *     WhoAmI: () => Effect.map(CurrentUser, (user) => user.id)
+ *   }))
+ * )
+ * ```
+ *
+ * @stability unstable
+ * @category middleware
+ * @since 4.0.0
+ */
+export const middleware = function () {
+  if (arguments.length === 0) {
+    return makeMiddleware;
+  }
+  return makeMiddleware(arguments[0], arguments[1]);
+};
+/**
+ * Creates middleware that hides registrations per request.
+ *
+ * **Details**
+ *
+ * The check runs for every registration the middleware is provided to, on list
+ * requests and on calls, reads, gets and completions. When it returns `false`
+ * the registration is left out of list results, and requests for it fail as if
+ * it was not registered.
+ *
+ * The result is a `Middleware` and composes like one. The check receives the
+ * same {@link MiddlewareOptions} as middleware, and services it reads per
+ * request, other than `McpRequestContext`, are met the same way. Scope a
+ * visibility to some tools by providing its layer to their toolkit only, or
+ * branch on `target`.
+ *
+ * On a list request, the check and the middleware outside the innermost
+ * visibility run once for each registration. Middleware inside it does not
+ * run. A failure of that middleware or of a check fails the whole list
+ * request. It never hides a registration.
+ *
+ * Unlike `EnabledWhen`, a visibility runs the middleware around it on list
+ * requests, and middleware sees requests for hidden registrations.
+ *
+ * **Example** (Hiding admin tools from other users)
+ *
+ * ```ts
+ * import { Context, Effect, Layer, Schema } from "effect"
+ * import { McpServer, Tool, Toolkit } from "effect/ai"
+ *
+ * class CurrentUser extends Context.Service<CurrentUser, { readonly isAdmin: boolean }>()("CurrentUser") {}
+ *
+ * const AdminTools = Toolkit.make(Tool.make("DeleteUser", { success: Schema.String }))
+ *
+ * const Auth = McpServer.middleware<{ provides: CurrentUser }>()((effect, { headers }) =>
+ *   Effect.provideService(effect, CurrentUser, { isAdmin: headers["x-role"] === "admin" })
+ * )
+ * const AdminOnly = McpServer.visibility(() => Effect.map(CurrentUser, (user) => user.isAdmin))
+ *
+ * const Registrations = McpServer.toolkit(AdminTools).pipe(
+ *   Layer.provide(AdminOnly.combine(Auth).layer),
+ *   Layer.provide(AdminTools.toLayer({ DeleteUser: () => Effect.succeed("deleted") }))
+ * )
+ * ```
+ *
+ * @see {@link middleware} for providing the services a check reads
+ *
+ * @stability unstable
+ * @category middleware
+ * @since 4.0.0
+ */
+export const visibility = (check, options) => makeMiddleware(Effect.isEffect(check) ? Effect.map(check, makeGate) : makeGate(check), options);
+// Raised by a visibility gate. It is left out of the types because `makeInvoke`
+// replaces it with the not-found error of the request. It still has the shape
+// of an MCP error, since middleware outside the gate sees it as one.
+class Hidden extends /*#__PURE__*/Data.TaggedError("effect/ai/McpServer/Hidden") {}
+const failHidden = /*#__PURE__*/Effect.fail(/*#__PURE__*/new Hidden({
+  code: McpSchema.INVALID_PARAMS_ERROR_CODE,
+  message: "Not found"
+}));
+// Marks the middleware functions created by `visibility`.
+const gates = /*#__PURE__*/new WeakSet();
+const makeGate = check => {
+  const gate = (effect, options) => Effect.flatMap(check(options), visible => visible ? effect : failHidden);
+  gates.add(gate);
+  return gate;
+};
+class MiddlewareFn extends /*#__PURE__*/Context.Service()("effect/ai/McpServer/MiddlewareFn") {}
+const makeMiddleware = (fn, options) => {
+  const middleware = new MiddlewareImpl(Effect.isEffect(fn) ? Layer.effect(MiddlewareFn)(fn) : Layer.succeed(MiddlewareFn, fn));
+  return options?.global ? middleware.layerGlobal : middleware;
+};
+let middlewareId = 0;
+class MiddlewareImpl {
+  [MiddlewareTypeId] = {};
+  layer;
+  layerGlobal;
+  layerFn;
+  dependencies;
+  constructor(layerFn, dependencies) {
+    this.layerFn = layerFn;
+    this.dependencies = dependencies;
+    const contextKey = `${middlewareKeyPrefix}${++middlewareId}`;
+    this.layer = Layer.effectContext(Effect.gen(function* () {
+      const stack = [yield* MiddlewareFn];
+      if (dependencies) {
+        const memoMap = yield* Layer.CurrentMemoMap;
+        const scope = yield* Effect.scope;
+        stack.push(...getMiddleware(yield* Layer.buildWithMemoMap(dependencies, memoMap, scope)));
+      }
+      return Context.makeUnsafe(new Map([[contextKey, stack]]));
+    })).pipe(Layer.provide(layerFn));
+    this.layerGlobal = Layer.effectDiscard(Effect.gen(function* () {
+      const stack = Context.getOrUndefinedUnsafe(yield* Effect.context(), contextKey);
+      const {
+        globalMiddleware
+      } = internalState.get(yield* McpServer);
+      yield* Effect.acquireRelease(Effect.sync(() => {
+        globalMiddleware.push(...stack);
+      }), () => Effect.sync(() => {
+        for (const fn of stack) {
+          const index = globalMiddleware.indexOf(fn);
+          if (index !== -1) globalMiddleware.splice(index, 1);
+        }
+      }));
+    })).pipe(Layer.provide(this.layer));
+  }
+  combine(other) {
+    return new MiddlewareImpl(this.layerFn, this.dependencies ? Layer.provideMerge(this.dependencies, other.layer) : other.layer);
+  }
+}
+// The innermost middleware comes first.
+const getMiddleware = context => {
+  const stacks = [];
+  let maxLength = 0;
+  for (const [key, value] of context.mapUnsafe) {
+    if (key.startsWith(middlewareKeyPrefix)) {
+      stacks.push(value);
+      maxLength = Math.max(maxLength, value.length);
+    }
+  }
+  const unique = new Set();
+  for (let i = maxLength - 1; i >= 0; i--) {
+    for (const stack of stacks) {
+      if (i < stack.length) unique.add(stack[i]);
+    }
+  }
+  return Arr.fromIterable(unique).reverse();
+};
+const isMcpError = error => Predicate.hasProperty(error, "code") && typeof error.code === "number" && Predicate.hasProperty(error, "message") && typeof error.message === "string";
+// Distinguishes handler failures from failures raised or rewritten by middleware.
+const HandlerFailure = /*#__PURE__*/Context.Reference("effect/ai/McpServer/HandlerFailure", {
+  defaultValue: () => false
+});
+const handlerFailure = /*#__PURE__*/Context.make(HandlerFailure, true);
+const internalError = /*#__PURE__*/new InternalError({
+  message: "Internal error"
+});
+const rejectWith = error => Effect.fail(new McpCore.RequestRejected({
+  code: error.code,
+  message: error.message,
+  data: error.data,
+  error
+}));
+const notFound = (method, target) => {
+  switch (method) {
+    case "tools/call":
+      return new McpCore.ToolNotFound({
+        name: target
+      });
+    case "resources/read":
+      return new McpCore.ResourceNotFound({
+        uri: target
+      });
+    case "prompts/get":
+      return new McpCore.PromptNotFound({
+        name: target
+      });
+    case "completion/complete":
+      return new InvalidParams({
+        message: "Unknown completion reference or argument"
+      });
+  }
+};
+const isHidden = error => error instanceof Hidden;
+// Recovers a request rejected by a visibility gate. Any other cause, including
+// one that also holds an interrupt, is propagated unchanged.
+const catchHidden = onHidden => self => Effect.catchCause(self, cause => {
+  const failure = Cause.findFail(cause);
+  return !Cause.hasInterrupts(cause) && Result.isSuccess(failure) && isHidden(failure.success.error) ? onHidden() : Effect.failCause(cause);
+});
+// The innermost middleware comes first. Middleware provided both locally and
+// globally runs once, at its outermost position.
+const middlewareStack = (localMiddleware, globalMiddleware) => {
+  if (globalMiddleware.length === 0) {
+    return localMiddleware;
+  }
+  if (localMiddleware.length === 0) {
+    return globalMiddleware;
+  }
+  const stack = [...localMiddleware, ...globalMiddleware];
+  return stack.filter((fn, index) => stack.lastIndexOf(fn) === index);
+};
+// Runs a handler inside middleware. The handler's own failures pass through, a
+// visibility gate fails with `Hidden`, and other failures become
+// `RequestRejected`: middleware failures as JSON-RPC errors, anything else as
+// a reported internal error.
+const runMiddleware = (handler, middleware, invocation, request) => {
+  const effect = middleware.length === 0 ? handler : Effect.withFiber(fiber => {
+    const headers = Context.getOrUndefined(fiber.context, HttpServerRequest.HttpServerRequest)?.headers ?? Headers.empty;
+    const options = {
+      ...request,
+      requestContext: invocation.requestContext,
+      headers,
+      sessionId: headers[MCP_SESSION_ID_HEADER]
+    };
+    const handled = Effect.catchCause(handler, cause => Effect.failCause(Cause.annotate(cause, handlerFailure)));
+    return middleware.reduce((effect, fn) => fn(effect, options), handled);
+  });
+  return provideInvocationContext(effect, invocation).pipe(Effect.catchCause(cause => {
+    if (Cause.hasInterrupts(cause)) {
+      return Effect.failCause(cause);
+    }
+    const failure = Cause.findFail(cause);
+    if (Result.isSuccess(failure) && !Cause.hasDies(cause)) {
+      const error = failure.success.error;
+      if (isHidden(error)) {
+        return Effect.fail(error);
+      }
+      if (middleware.length === 0 || Context.get(Cause.reasonAnnotations(failure.success), HandlerFailure)) {
+        return Effect.failCause(cause);
+      }
+      if (isMcpError(error)) {
+        return rejectWith(error);
+      }
+    }
+    return Effect.logError(cause).pipe(Effect.andThen(ErrorReporter.report(cause)), Effect.andThen(rejectWith(internalError)));
+  }));
+};
+// Request services override captured services; global middleware wraps local middleware.
+const makeInvoke = (context, globalMiddleware) => {
+  const services = context === undefined ? Context.empty() : omitRequestServices(context);
+  const localMiddleware = context === undefined ? [] : getMiddleware(context);
+  const invoke = (handler, invocation, request) => runMiddleware(services.mapUnsafe.size === 0 ? handler : Effect.updateContext(handler, context => Context.merge(services, context)), middlewareStack(localMiddleware, globalMiddleware), invocation, request).pipe(catchHidden(() => Effect.fail(notFound(request.method, request.target))));
+  // On list requests only the middleware outside the innermost visibility runs.
+  const visible = (method, target) => invocation => {
+    const middleware = middlewareStack(localMiddleware, globalMiddleware);
+    const innermost = middleware.findIndex(fn => gates.has(fn));
+    if (innermost === -1) {
+      return Effect.succeed(true);
+    }
+    return runMiddleware(Effect.void, middleware.slice(innermost), invocation, {
+      method,
+      target,
+      payload: undefined
+    }).pipe(Effect.as(true), catchHidden(() => Effect.succeed(false)));
+  };
+  return {
+    invoke,
+    visible
+  };
+};
+// Applies the `EnabledWhen` annotation of a registration.
+const isEnabled = annotations => {
+  const enabledWhen = Context.getOrUndefined(annotations, EnabledWhen);
+  return profile => enabledWhen === undefined || enabledWhen({
+    protocolVersion: profile.protocolVersion,
+    capabilities: profile.clientCapabilities,
+    clientInfo: profile.clientInfo
+  });
+};
+const rejectedError = rejected => Effect.fail(rejected.error);
 /**
  * Service that stores and serves an MCP server's registered tools, resources,
  * prompts, completions, and outgoing notifications.
@@ -144,6 +479,7 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
     const resourceTemplates = [];
     const prompts = [];
     const notificationsQueue = yield* Queue.make();
+    const globalMiddleware = [];
     const notificationDelivery = {
       consumers: 0,
       listChangeRevision: 0,
@@ -233,18 +569,22 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
         } else {
           tools[existingIndex] = options;
         }
-        const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen);
+        const {
+          invoke,
+          visible
+        } = makeInvoke(options.services, globalMiddleware);
         yield* internalCore.tools.register({
           descriptor: new McpTool({
             ...options.tool,
             title: options.tool.title ?? options.tool.annotations?.title
           }),
-          isVisible: profile => enabledWhen === undefined || enabledWhen({
-            protocolVersion: profile.protocolVersion,
-            capabilities: profile.clientCapabilities,
-            clientInfo: profile.clientInfo
-          }),
-          handle: (call, invocation) => provideInvocationContext(options.handle(call.arguments), invocation).pipe(Effect.catchTags({
+          visible: visible("tools/list", options.tool.name),
+          isVisible: isEnabled(options.annotations),
+          handle: (call, invocation) => invoke(options.handle(call.arguments), invocation, {
+            method: "tools/call",
+            target: call.name,
+            payload: call
+          }).pipe(Effect.catchTags({
             InternalError: error => Effect.fail(new McpCore.ToolExecutionError({
               name: options.tool.name,
               message: error.message
@@ -259,9 +599,9 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
       }),
       callTool: Effect.fnUntraced(function* (request) {
         const client = yield* McpServerClient;
-        const result = yield* internalCore.tools.call(request, McpProtocolInternal.invocationFromClient(client)).pipe(Effect.mapError(error => new InvalidParams({
+        const result = yield* internalCore.tools.call(request, McpProtocolInternal.invocationFromClient(client)).pipe(Effect.catch(error => error._tag === "RequestRejected" ? rejectedError(error) : Effect.fail(new InvalidParams({
           message: error._tag === "ToolNotFound" ? `Tool '${error.name}' not found` : error.message
-        })));
+        }))));
         if (result._tag === "InputRequired") {
           return yield* new InvalidParams({
             message: "Client input is not supported by this MCP protocol"
@@ -284,17 +624,21 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
         } else {
           resources[existingIndex] = options;
         }
+        const {
+          invoke,
+          visible
+        } = makeInvoke(options.services, globalMiddleware);
         yield* internalCore.resources.register({
           descriptor: options.resource,
-          isVisible: profile => {
-            const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen);
-            return enabledWhen === undefined || enabledWhen({
-              protocolVersion: profile.protocolVersion,
-              capabilities: profile.clientCapabilities,
-              clientInfo: profile.clientInfo
-            });
-          },
-          read: invocation => provideInvocationContext(options.handle, invocation)
+          visible: visible("resources/list", options.resource.uri),
+          isVisible: isEnabled(options.annotations),
+          read: invocation => invoke(options.handle, invocation, {
+            method: "resources/read",
+            target: options.resource.uri,
+            payload: {
+              uri: options.resource.uri
+            }
+          })
         });
         yield* notifications.client["notifications/resources/list_changed"]({});
       }),
@@ -303,6 +647,7 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
         completions,
         handle,
         routerPath,
+        services,
         template
       }) {
         const existingIndex = resourceTemplates.findIndex(({
@@ -319,18 +664,16 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
             annotations
           };
         }
+        const {
+          invoke,
+          visible
+        } = makeInvoke(services, globalMiddleware);
         const templateMatcher = makeUriMatcher();
         templateMatcher.add(routerPath, true);
         yield* internalCore.resources.registerTemplate({
           descriptor: template,
-          isVisible: profile => {
-            const enabledWhen = Context.getOrUndefined(annotations, EnabledWhen);
-            return enabledWhen === undefined || enabledWhen({
-              protocolVersion: profile.protocolVersion,
-              capabilities: profile.clientCapabilities,
-              clientInfo: profile.clientInfo
-            });
-          },
+          visible: visible("resources/templates/list", template.uriTemplate),
+          isVisible: isEnabled(annotations),
           match: uri => {
             const match = templateMatcher.find(uri);
             if (match === undefined) {
@@ -342,10 +685,20 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
             }
             return params;
           },
-          read: (uri, params, invocation) => provideInvocationContext(handle(uri, Array.from(params)), invocation)
+          read: (uri, params, invocation) => invoke(handle(uri, Array.from(params)), invocation, {
+            method: "resources/read",
+            target: uri,
+            payload: {
+              uri
+            }
+          })
         });
         for (const [param, handle] of Object.entries(completions)) {
-          yield* internalCore.completions.register(`resource/${template.uriTemplate}/${param}`, (request, invocation) => provideInvocationContext(handle(request.argument.value, request.context), invocation).pipe(Effect.map(result => ({
+          yield* internalCore.completions.register(`resource/${template.uriTemplate}/${param}`, (request, invocation) => invoke(handle(request.argument.value, request.context), invocation, {
+            method: "completion/complete",
+            target: template.uriTemplate,
+            payload: request
+          }).pipe(Effect.map(result => ({
             values: result.completion.values,
             total: result.completion.total,
             hasMore: result.completion.hasMore,
@@ -356,9 +709,12 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
       }),
       findResource: Effect.fnUntraced(function* (uri) {
         const client = yield* McpServerClient;
-        return yield* internalCore.resources.read(uri, McpProtocolInternal.invocationFromClient(client)).pipe(Effect.catchTag("ResourceNotFound", error => Effect.fail(new InvalidParams({
-          message: `Resource '${error.uri}' not found`
-        }))));
+        return yield* internalCore.resources.read(uri, McpProtocolInternal.invocationFromClient(client)).pipe(Effect.catchTags({
+          ResourceNotFound: error => Effect.fail(new InvalidParams({
+            message: `Resource '${error.uri}' not found`
+          })),
+          RequestRejected: rejectedError
+        }));
       }),
       get prompts() {
         return prompts;
@@ -372,20 +728,29 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
         } else {
           prompts[existingIndex] = options;
         }
+        const {
+          invoke,
+          visible
+        } = makeInvoke(options.services, globalMiddleware);
         yield* internalCore.prompts.register({
           descriptor: options.prompt,
-          isVisible: profile => {
-            const enabledWhen = Context.getOrUndefined(options.annotations, EnabledWhen);
-            return enabledWhen === undefined || enabledWhen({
-              protocolVersion: profile.protocolVersion,
-              capabilities: profile.clientCapabilities,
-              clientInfo: profile.clientInfo
-            });
-          },
-          get: (params, invocation) => provideInvocationContext(options.handle(params), invocation).pipe(Effect.map(result => Predicate.isTagged(result, "InputRequired") ? McpCore.OperationOutcome.InputRequired(result) : McpCore.OperationOutcome.Complete(result)))
+          visible: visible("prompts/list", options.prompt.name),
+          isVisible: isEnabled(options.annotations),
+          get: (params, invocation) => invoke(options.handle(params), invocation, {
+            method: "prompts/get",
+            target: options.prompt.name,
+            payload: {
+              name: options.prompt.name,
+              arguments: params
+            }
+          }).pipe(Effect.map(result => Predicate.isTagged(result, "InputRequired") ? McpCore.OperationOutcome.InputRequired(result) : McpCore.OperationOutcome.Complete(result)))
         });
         for (const [param, handle] of Object.entries(options.completions)) {
-          yield* internalCore.completions.register(`prompt/${options.prompt.name}/${param}`, (request, invocation) => provideInvocationContext(handle(request.argument.value, request.context), invocation).pipe(Effect.map(result => ({
+          yield* internalCore.completions.register(`prompt/${options.prompt.name}/${param}`, (request, invocation) => invoke(handle(request.argument.value, request.context), invocation, {
+            method: "completion/complete",
+            target: options.prompt.name,
+            payload: request
+          }).pipe(Effect.map(result => ({
             values: result.completion.values,
             total: result.completion.total,
             hasMore: result.completion.hasMore,
@@ -399,9 +764,12 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
         name
       }) {
         const client = yield* McpServerClient;
-        const outcome = yield* internalCore.prompts.get(name, params ?? {}, McpProtocolInternal.invocationFromClient(client)).pipe(Effect.catchTag("PromptNotFound", () => new InvalidParams({
-          message: `Prompt '${name}' not found`
-        })));
+        const outcome = yield* internalCore.prompts.get(name, params ?? {}, McpProtocolInternal.invocationFromClient(client)).pipe(Effect.catchTags({
+          PromptNotFound: () => new InvalidParams({
+            message: `Prompt '${name}' not found`
+          }),
+          RequestRejected: rejectedError
+        }));
         return outcome._tag === "Complete" ? outcome.value : yield* new InvalidParams({
           message: "Client input is not supported by this MCP protocol"
         });
@@ -419,7 +787,7 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
           },
           argument: complete.argument,
           context: complete.context
-        }, McpProtocolInternal.invocationFromClient(client));
+        }, McpProtocolInternal.invocationFromClient(client)).pipe(Effect.catchTag("RequestRejected", rejectedError));
         return {
           _meta: result.metadata,
           completion: {
@@ -433,12 +801,19 @@ export class McpServer extends /*#__PURE__*/Context.Service()("effect/ai/McpServ
     internalState.set(service, {
       core: internalCore,
       notifications: notificationsQueue,
-      notificationDelivery
+      notificationDelivery,
+      globalMiddleware
     });
     return service;
   });
   /**
-   * Layer that provides the MCP server and client services.
+   * Layer that provides the MCP server service.
+   *
+   * **Details**
+   *
+   * It doesn't run a transport or discharge request-level dependencies. Use it
+   * to call registrations in process, providing their request-level
+   * dependencies with MCP middleware.
    *
    * @stability unstable
    * @since 4.0.0
@@ -452,6 +827,26 @@ const cancelledResponses = /*#__PURE__*/new WeakMap();
 const httpPostResponses = /*#__PURE__*/new WeakMap();
 const requestKey = requestId => `${typeof requestId}:${requestId}`;
 class McpClientKey extends Data.Class {}
+// Converts each hint to the wire's nonnegative integer `ttlMs` once, when the server is built.
+const normalizeCacheHints = cacheHints => {
+  if (cacheHints === undefined) return Effect.succeed(undefined);
+  const normalized = {};
+  for (const [name, hint] of Object.entries(cacheHints)) {
+    if (hint === undefined) continue;
+    const ttlMs = Option.match(Duration.fromInput(hint.ttl), {
+      onNone: () => NaN,
+      onSome: ttl => Math.floor(Duration.toMillis(ttl))
+    });
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 0 || hint.cacheScope !== "private") {
+      return Effect.fail(new Cause.IllegalArgumentError(`McpServer cacheHints.${name} must have a finite, nonnegative ttl and a "private" cacheScope`));
+    }
+    normalized[name] = {
+      ttlMs,
+      cacheScope: "private"
+    };
+  }
+  return Effect.succeed(normalized);
+};
 /**
  * Runs an MCP server over the current `RpcServer.Protocol`.
  *
@@ -466,9 +861,13 @@ class McpClientKey extends Data.Class {}
  * @since 4.0.0
  */
 export const run = /*#__PURE__*/Effect.fnUntraced(function* (options) {
+  const cacheHints = yield* normalizeCacheHints(options.cacheHints);
   const runtimeOption = yield* Effect.serviceOption(McpRuntime.ServerRuntime);
   const runtime = Option.isSome(runtimeOption) ? runtimeOption.value : yield* McpRuntime.make(options.protocols);
-  return yield* runWithRuntime(options, runtime, "custom");
+  return yield* runWithRuntime({
+    ...options,
+    cacheHints
+  }, runtime, "custom");
 });
 const runWithRuntime = /*#__PURE__*/Effect.fnUntraced(function* (options, runtime, transport, requestScoped) {
   const protocol = yield* RpcServer.Protocol;
@@ -975,7 +1374,7 @@ const runWithRuntime = /*#__PURE__*/Effect.fnUntraced(function* (options, runtim
           if (requestContext?.clientId !== clientId || !isLoggingLevel(level) || McpSchema.LoggingLevel.literals.indexOf(notification.level) < McpSchema.LoggingLevel.literals.indexOf(level)) {
             return;
           }
-        } else if (!runtime.canDeliver(clientId, (requestContext?.clientId === clientId ? requestHeaders : undefined) ?? clientStates.get(clientId)?.sessionHeaders ?? Headers.empty, notification, defaultLogLevel)) {
+        } else if (!runtime.canDeliver(clientId, (requestContext?.clientId === clientId ? requestHeaders : undefined) ?? clientStates.get(clientId)?.sessionHeaders ?? Headers.empty, notification, defaultLogLevel, listChangeRevision)) {
           return;
         }
         const rpc = selectedProtocol.serverNotificationRpcs.requests.get(projected.tag);
@@ -1028,6 +1427,11 @@ const runWithRuntime = /*#__PURE__*/Effect.fnUntraced(function* (options, runtim
  * `McpServer.layer`, so registration layers can use the `McpServer` service
  * while the server is running.
  *
+ * Pass registration layers as `registrations` to build them before the server
+ * reads its first request. The transport discharges the request-level
+ * dependencies it supplies (see `ProvidedServices`); any other `McpRequest`
+ * marker stays in the layer's requirements and must be met by MCP middleware.
+ *
  * **Gotchas**
  *
  * Unlike `layerStdio` and `layerHttp`, this layer does not install a concrete
@@ -1043,9 +1447,13 @@ const runWithRuntime = /*#__PURE__*/Effect.fnUntraced(function* (options, runtim
  */
 export const layer = options => layerWithRuntime(options, "custom").pipe(Layer.provide(McpRuntime.layer(options.protocols)));
 const layerWithRuntime = (options, transport) => Layer.effectDiscard(Effect.gen(function* () {
+  const cacheHints = yield* normalizeCacheHints(options.cacheHints);
   const runtime = yield* McpRuntime.ServerRuntime;
-  yield* Effect.forkScoped(runWithRuntime(options, runtime, transport));
-})).pipe(Layer.provideMerge(McpServer.layer));
+  yield* Effect.forkScoped(runWithRuntime({
+    ...options,
+    cacheHints
+  }, runtime, transport));
+})).pipe(Layer.provide(options.registrations ?? Layer.empty), Layer.provideMerge(McpServer.layer));
 /**
  * Creates a layer that runs an MCP server over standard input and output.
  *
@@ -1061,6 +1469,11 @@ const layerWithRuntime = (options, transport) => Layer.effectDiscard(Effect.gen(
  * `McpRequestContext` and legacy `McpServerClient` services to handlers, and
  * requires `Stdio`.
  *
+ * Pass registration layers as `registrations` to build them before the server
+ * reads its first request. The transport discharges the request-level
+ * dependencies it supplies (see `ProvidedServices`); any other `McpRequest`
+ * marker stays in the layer's requirements and must be met by MCP middleware.
+ *
  * @see {@link layer} for running over an existing `RpcServer.Protocol`
  * @see {@link layerHttp} for the single-endpoint HTTP transport
  *
@@ -1161,6 +1574,13 @@ const mcpStdioSerialization = protocols => {
  * serverless hosts where execution must belong to each request, use
  * `layerHttpRequestScoped` instead.
  *
+ * Pass registration layers as `registrations` to build them before the
+ * endpoint serves its first request. The transport discharges the
+ * request-level dependencies it supplies (see `ProvidedServices`) and converts
+ * the remaining `McpRequest` markers into `HttpRouter.Request` markers, so
+ * `HttpRouter.middleware` can provide them, for example to authenticate the
+ * request and resolve the current user.
+ *
  * `layerHttp` always implements the single-endpoint Streamable HTTP topology.
  * Using `v2024_11_05` here is a custom compatibility transport for that
  * revision's schema. It does not implement the historical two-endpoint
@@ -1210,6 +1630,10 @@ export const layerHttp = options => {
  * Configuring a sessionful protocol through an untyped caller fails layer
  * construction with `IllegalArgumentError`.
  *
+ * Registrations passed as `registrations` are built once, before the routes
+ * are added, and shared by every POST. Remaining `McpRequest` markers become
+ * `HttpRouter.Request` markers, as with `layerHttp`.
+ *
  * @see {@link layerHttp} for the long-lived HTTP transport and HTTP admission policy
  *
  * @stability unstable
@@ -1222,6 +1646,10 @@ export const layerHttpRequestScoped = options => Layer.effectDiscard(Effect.gen(
   if (stateful !== undefined) {
     return yield* new Cause.IllegalArgumentError(`McpServer.layerHttpRequestScoped does not support the sessionful MCP protocol ${stateful.protocolVersion}`);
   }
+  const serverOptions = {
+    ...options,
+    cacheHints: yield* normalizeCacheHints(options.cacheHints)
+  };
   const server = yield* McpServer;
   const {
     core,
@@ -1235,7 +1663,7 @@ export const layerHttpRequestScoped = options => Layer.effectDiscard(Effect.gen(
     subscribeServerNotifications: Effect.die("Subscriptions are disabled for request-scoped MCP servers"),
     getListChangeRevision: () => notificationDelivery.listChangeRevision,
     defaultLogLevel: yield* CurrentLogLevel,
-    serverInfo: options
+    serverInfo: serverOptions
   });
   yield* Effect.acquireRelease(Effect.sync(() => {
     notificationDelivery.requestEndpoints++;
@@ -1250,7 +1678,7 @@ export const layerHttpRequestScoped = options => Layer.effectDiscard(Effect.gen(
       protocol
     } = yield* RpcServer.makeProtocolWithHttpEffect().pipe(Effect.provideService(RpcSerialization.RpcSerialization, mcpHttpSerialization));
     const notifications = yield* Queue.make();
-    yield* runWithRuntime(options, runtime, "http", {
+    yield* runWithRuntime(serverOptions, runtime, "http", {
       notifications,
       handlers
     }).pipe(Effect.provideService(RpcServer.Protocol, protocol), Effect.provideService(McpServer, server), Effect.forkScoped({
@@ -1258,7 +1686,7 @@ export const layerHttpRequestScoped = options => Layer.effectDiscard(Effect.gen(
     }));
     return yield* Effect.provideService(httpEffect, RequestNotificationQueue, notifications);
   }));
-})).pipe(Layer.provideMerge(McpServer.layer), Layer.provide(McpRuntime.layer(options.protocols)));
+})).pipe(Layer.provide(options.registrations ?? Layer.empty), Layer.provideMerge(McpServer.layer), Layer.provide(McpRuntime.layer(options.protocols)));
 const layerMcpProtocolHttp = options => Layer.effect(RpcServer.Protocol)(Effect.gen(function* () {
   const {
     httpEffect,
@@ -1480,6 +1908,13 @@ const toolResultContent = encoded => encoded === undefined ? [] : [{
 /**
  * Registers a `Toolkit` with the `McpServer`.
  *
+ * **Details**
+ *
+ * The MCP middleware in the current context, provided with
+ * `Effect.provide(middleware.layer)`, runs around every call to the toolkit.
+ *
+ * @see {@link ToolkitRequirements} for which services are request-level
+ *
  * @stability unstable
  * @category handlers
  * @since 4.0.0
@@ -1500,12 +1935,11 @@ export const registerToolkit = /*#__PURE__*/Effect.fnUntraced(function* (toolkit
     }
     return Context.makeUnsafe(services);
   }));
-  const services = omitRequestServices(yield* Effect.context());
-  const reportCause = cause => Effect.provideContext(ErrorReporter.report(cause), services);
+  const services = yield* Effect.context();
   // Interruption propagates; anything else is logged, reported and scrubbed.
   const internalToolError = cause => {
     const failure = Cause.findFail(cause);
-    return Result.isFailure(failure) && !Cause.hasDies(cause) ? Effect.failCause(failure.failure) : Effect.logError(cause).pipe(Effect.andThen(reportCause(cause)), Effect.as(toolErrorResult(INTERNAL_TOOL_ERROR_MESSAGE)));
+    return Result.isFailure(failure) && !Cause.hasDies(cause) ? Effect.failCause(failure.failure) : Effect.logError(cause).pipe(Effect.andThen(ErrorReporter.report(cause)), Effect.as(toolErrorResult(INTERNAL_TOOL_ERROR_MESSAGE)));
   };
   const registrations = [];
   for (const tool of Object.values(built.tools)) {
@@ -1570,8 +2004,9 @@ export const registerToolkit = /*#__PURE__*/Effect.fnUntraced(function* (toolkit
           isError: result.isFailure,
           structuredContent: result.isFailure ? undefined : result.encodedResult,
           content: toolResultContent(result.encodedResult)
-        }))), Effect.catchCause(handleCause), Effect.provideContext(services));
-      }
+        }))), Effect.catchCause(handleCause));
+      },
+      services
     });
   }
   for (const registration of registrations) {
@@ -1598,13 +2033,31 @@ const toolJsonSchema = (schema, strict) => {
   };
 };
 /**
- * Registers an `AiToolkit` with the `McpServer`.
+ * Creates a layer that registers a `Toolkit` with the `McpServer`.
+ *
+ * **Details**
+ *
+ * The layer requires `McpServer`. Pass it to a transport through the
+ * `registrations` option, or provide the transport layer to it.
+ *
+ * @see {@link ToolkitRequirements} for which services are request-level
  *
  * @stability unstable
  * @category layers
  * @since 4.0.0
  */
-export const toolkit = toolkit => Layer.effectDiscard(registerToolkit(toolkit)).pipe(Layer.provide(McpServer.layer));
+export const toolkit = toolkit => Layer.effectDiscard(registerToolkit(toolkit));
+// Leave defects and interruption to makeInvoke; convert only expected failures.
+const handlerFailureToInternalError = cause => Cause.hasDies(cause) || Cause.hasInterrupts(cause) ? Effect.failCause(cause) : Effect.fail(new InternalError({
+  message: Cause.prettyErrors(cause)[0].message
+}));
+const completionHandler = (handle, encodeValues) => (input, context) => handle(input, context).pipe(Effect.flatMap(encodeValues), Effect.map(values => ({
+  completion: {
+    values: values,
+    total: values.length,
+    hasMore: false
+  }
+})), Effect.catchCause(handlerFailureToInternalError));
 /**
  * Registers an MCP resource or resource template from an Effect program.
  *
@@ -1618,19 +2071,15 @@ export const registerResource = function () {
   if (arguments.length === 1) {
     const options = arguments[0];
     return Effect.gen(function* () {
-      const services = omitRequestServices(yield* Effect.context());
+      const services = yield* Effect.context();
       const registry = yield* McpServer;
       yield* registry.addResource({
         resource: new Resource({
           ...options,
           annotations: options
         }),
-        handle: options.content.pipe(Effect.provideContext(services), Effect.map(content => resolveResourceContent(options.uri, content)), Effect.catchCause(cause => {
-          const prettyError = Cause.prettyErrors(cause)[0];
-          return Effect.fail(new InternalError({
-            message: prettyError.message
-          }));
-        })),
+        services,
+        handle: options.content.pipe(Effect.map(content => resolveResourceContent(options.uri, content)), Effect.catchCause(handlerFailureToInternalError)),
         annotations: options.annotations ?? Context.empty()
       });
     });
@@ -1642,7 +2091,7 @@ export const registerResource = function () {
     uriPath
   } = compileUriTemplate(...arguments);
   return Effect.fnUntraced(function* (options) {
-    const services = omitRequestServices(yield* Effect.context());
+    const services = yield* Effect.context();
     const registry = yield* McpServer;
     const decode = Schema.decodeUnknownEffect(schema);
     const template = new ResourceTemplate({
@@ -1652,41 +2101,32 @@ export const registerResource = function () {
     });
     const completions = Object.create(null);
     for (const [param, handle] of Object.entries(options.completion ?? {})) {
-      const encodeArray = Schema.encodeUnknownEffect(Schema.Array(params[param]));
-      const handler = (input, context) => handle(input, context).pipe(Effect.flatMap(encodeArray), Effect.map(values => ({
-        completion: {
-          values: values,
-          total: values.length,
-          hasMore: false
-        }
-      })), Effect.catchCause(cause => {
-        const prettyError = Cause.prettyErrors(cause)[0];
-        return Effect.fail(new InternalError({
-          message: prettyError.message
-        }));
-      }), Effect.provideContext(services));
-      completions[param] = handler;
+      completions[param] = completionHandler(handle, Schema.encodeUnknownEffect(Schema.Array(params[param])));
     }
     yield* registry.addResourceTemplate({
       template,
       routerPath,
       completions,
+      services,
       annotations: options.annotations ?? Context.empty(),
       handle: (uri, params) => decode(params).pipe(Effect.mapError(error => new InvalidParams({
         message: error.message
-      })), Effect.flatMap(params => options.content(uri, ...params).pipe(Effect.map(content => resolveResourceContent(uri, content)), Effect.catchCause(cause => {
-        const prettyError = Cause.prettyErrors(cause)[0];
-        return Effect.fail(new InternalError({
-          message: prettyError.message
-        }));
-      }))), Effect.provideContext(services))
+      })), Effect.flatMap(params => options.content(uri, ...params).pipe(Effect.map(content => resolveResourceContent(uri, content)), Effect.catchCause(handlerFailureToInternalError))))
     });
   });
 };
 /**
  * Creates a layer that registers an MCP resource or resource template.
  *
+ * **Details**
+ *
+ * Services read by the content and completion handlers are request-level, so
+ * providing them with `Layer.provide` doesn't satisfy them. Read
+ * construction-time services in an enclosing `Layer.unwrap` and close over
+ * them, and provide per-request services with MCP middleware.
+ *
  * @see {@link registerResource} for the Effect-level resource registration API
+ * @see {@link middleware} for providing request-level dependencies
  *
  * @stability unstable
  * @category layers
@@ -1694,10 +2134,10 @@ export const registerResource = function () {
  */
 export const resource = function () {
   if (arguments.length === 1) {
-    return Layer.effectDiscard(registerResource(arguments[0])).pipe(Layer.provide(McpServer.layer));
+    return Layer.effectDiscard(registerResource(arguments[0]));
   }
   const register = registerResource(...arguments);
-  return options => Layer.effectDiscard(register(options)).pipe(Layer.provide(McpServer.layer));
+  return options => Layer.effectDiscard(register(options));
 };
 /**
  * Registers an MCP prompt from an Effect program.
@@ -1733,36 +2173,19 @@ export const registerPrompt = options => {
   const completion = options.completion ?? {};
   return Effect.gen(function* () {
     const registry = yield* McpServer;
-    const services = omitRequestServices(yield* Effect.context());
+    const services = yield* Effect.context();
     const completions = Object.create(null);
     for (const [param, handle] of Object.entries(completion)) {
-      const encodeArray = Schema.encodeEffect(Schema.Array(props[param]));
-      const handler = (input, context) => handle(input, context).pipe(Effect.flatMap(encodeArray), Effect.map(values => ({
-        completion: {
-          values: values,
-          total: values.length,
-          hasMore: false
-        }
-      })), Effect.catchCause(cause => {
-        const prettyError = Cause.prettyErrors(cause)[0];
-        return Effect.fail(new InternalError({
-          message: prettyError.message
-        }));
-      }), Effect.provide(services));
-      completions[param] = handler;
+      completions[param] = completionHandler(handle, Schema.encodeUnknownEffect(Schema.Array(props[param])));
     }
     yield* registry.addPrompt({
       prompt,
       completions,
+      services,
       annotations: options.annotations ?? Context.empty(),
       handle: params => decode(params).pipe(Effect.mapError(error => new InvalidParams({
         message: error.message
-      })), Effect.flatMap(params => options.content(params).pipe(Effect.catchCause(cause => {
-        const prettyError = Cause.prettyErrors(cause)[0];
-        return Effect.fail(new InternalError({
-          message: prettyError.message
-        }));
-      }))), Effect.map(messages => {
+      })), Effect.flatMap(params => options.content(params).pipe(Effect.catchCause(handlerFailureToInternalError))), Effect.map(messages => {
         messages = typeof messages === "string" ? [{
           role: "user",
           content: TextContent.make({
@@ -1773,20 +2196,28 @@ export const registerPrompt = options => {
           messages,
           description: prompt.description
         });
-      }), Effect.provideContext(services))
+      }))
     });
   });
 };
 /**
  * Creates a layer that registers an MCP prompt.
  *
+ * **Details**
+ *
+ * Services read by the content and completion handlers are request-level, so
+ * providing them with `Layer.provide` doesn't satisfy them. Read
+ * construction-time services in an enclosing `Layer.unwrap` and close over
+ * them, and provide per-request services with MCP middleware.
+ *
  * @see {@link registerPrompt} for the Effect-level prompt registration API
+ * @see {@link middleware} for providing request-level dependencies
  *
  * @stability unstable
  * @category layers
  * @since 4.0.0
  */
-export const prompt = options => Layer.effectDiscard(registerPrompt(options)).pipe(Layer.provide(McpServer.layer));
+export const prompt = options => Layer.effectDiscard(registerPrompt(options));
 /**
  * Collects structured input from the current MCP client and decodes the
  * accepted response with `schema`.
@@ -1834,6 +2265,21 @@ export const elicit = /*#__PURE__*/Effect.fnUntraced(function* (options) {
  * @since 4.0.0
  */
 export const clientCapabilities = /*#__PURE__*/McpRequestContext.useSync(_ => _.clientCapabilities);
+/**
+ * Decodes an `Mcp-Name` header, including base64-wrapped values.
+ * Returns `undefined` for malformed values.
+ *
+ * **Details**
+ *
+ * Use in `HttpRouter.middleware` to identify the tool, prompt or resource
+ * targeted by a `2026-07-28` request. Earlier protocols carry the name only
+ * in the JSON-RPC body.
+ *
+ * @stability unstable
+ * @category decoding
+ * @since 4.0.0
+ */
+export const decodeNameHeader = value => McpProtocolInternal.decodeRoutingHeader(value);
 // -----------------------------------------------------------------------------
 // Internal
 // -----------------------------------------------------------------------------