akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/server/mcp/McpAuth.ts

@@ -4,26 +4,17 @@ import { clientAddressFromHeaders } from "akanjs/common";
 import type { HttpRoutes } from "../types";
 
 export interface McpAuthOption {
-  /**
-   * Where a client may obtain a token, published in the metadata document for it to discover. Naming one also
-   * makes a credential mandatory: an MCP client begins its OAuth flow only on a 401, so a server that let an
-   * anonymous `initialize` succeed would leave it connected to the anonymous shelf and never asking.
-   */
+  /** Naming any makes a credential mandatory: an MCP client starts its OAuth flow only on a 401. */
   authorizationServers?: string[];
-  /** Scopes every call must carry. Declaring any turns `insufficient_scope` enforcement on. */
+  /** Declaring any turns `insufficient_scope` enforcement on. */
   scopes?: string[];
   /** Overrides the resource identifier when the public URL differs from what the request reports. */
   resource?: string;
-  /**
-   * Verifies a bearer token's signature and returns its claims, or `null` for one this server did not mint. The
-   * framework holds no signing key, so the module that issues tokens supplies this through `option.setMcp`; without
-   * it the claims are read unverified and a forged token degrades to an anonymous caller instead of being refused.
-   */
+  /** Claims, or `null` to refuse. Unset: claims are read unverified, so a forged token degrades to anonymous. */
   verify?: (token: string) => PromiseOrObject<Record<string, unknown> | null>;
 }
 
 export interface McpAuthProps extends McpAuthOption {
-  /** Path the MCP endpoint is mounted at. Its absolute URL is this server's OAuth resource identifier. */
   path: string;
 }
 
@@ -33,13 +24,6 @@ interface McpAuthFailure {
   description: string;
 }
 
-/**
- * The OAuth 2.1 protected-resource half of the MCP authorization spec: the RFC 9728 metadata document, the
- * `WWW-Authenticate` challenge that points at it, and the token checks that can be made without an issuer.
- *
- * The authorization server itself is a separate project. What lives here is what a resource server owes a
- * client regardless of who mints the tokens, so wiring one up later needs no change on this side.
- */
 export class McpAuth {
   static readonly wellKnownPath = "/.well-known/oauth-protected-resource";
 
@@ -49,10 +33,6 @@ export class McpAuth {
     this.#props = props;
   }
 
-  /**
-   * Both spellings of the metadata path. RFC 9728 inserts the resource's path into the well-known URL, and MCP
-   * clients try that form first and the bare one second; serving only one leaves half the clients at a 404.
-   */
   createRoutes(): HttpRoutes {
     const handler = { GET: (req: Request) => this.#metadata(req) };
     return {
@@ -61,11 +41,6 @@ export class McpAuth {
     };
   }
 
-  /**
-   * A request that carried no credential at all gets a challenge with no `error` code — RFC 6750 §3.1 reserves
-   * the code for a credential that was presented and found wanting — so a client reads it as "authenticate",
-   * not as "your token is bad".
-   */
   unauthorized(req: Request, failure?: McpAuthFailure) {
     const status = failure?.status ?? 401;
     const description = failure?.description ?? "Authentication is required to use this MCP server.";
@@ -75,16 +50,6 @@ export class McpAuth {
     );
   }
 
-  /**
-   * Refuses a bearer token that is already provably unusable, before the signal pipeline sees it.
-   *
-   * With a `verify` hook the token is checked end to end and one that fails is refused outright. Without one the
-   * claims are read **without verifying the signature**, which is sound only because every branch below can deny
-   * and none can grant: a forged token still has to pass the app's own middleware afterwards, so the worst a
-   * crafted payload achieves is refusing itself. What this buys is the failure mode it removes — an expired or
-   * foreign token otherwise degrades to an anonymous caller, and the agent is told a tool does not exist rather
-   * than that it needs to authenticate.
-   */
   async reject(req: Request): Promise<Response | null> {
     const token = McpAuth.#bearer(req);
     if (!token) return null;
@@ -101,17 +66,11 @@ export class McpAuth {
     return failure ? this.unauthorized(req, failure) : null;
   }
 
-  /**
-   * The 401 a credential-less request gets once an authorization server is named. A server naming none keeps
-   * anonymous access, which is what a public catalogue wants; the public tools of a server naming one are still
-   * reachable, with the token the challenge sends the client off to obtain.
-   */
   challengeAnonymous(req: Request): Response | null {
     if (!this.#props.authorizationServers?.length || McpAuth.#bearer(req)) return null;
     return this.unauthorized(req);
   }
 
-  /** A verifier that throws has said no: the token is refused, never let through as an anonymous caller. */
   async #verified(token: string): Promise<Record<string, unknown> | null> {
     try {
       return (await this.#props.verify?.(token)) ?? null;
@@ -139,10 +98,6 @@ export class McpAuth {
     return null;
   }
 
-  /**
-   * Enforced only when `scopes` is configured, because this server's own tokens carry no scope claim at all —
-   * declaring one is how a deployment says its issuer mints them.
-   */
   #missingScopes(claims: Record<string, unknown>) {
     const required = this.#props.scopes ?? [];
     if (!required.length) return [];
@@ -183,12 +138,6 @@ export class McpAuth {
     return this.#props.resource ?? new URL(this.#props.path, this.publicOrigin(req)).href;
   }
 
-  /**
-   * The origin this server is known by. A configured `resource` settles it — that URL is what an authorization
-   * server issued `aud` for, so nothing a request says can be more authoritative — and only a server with none
-   * falls back to what the request reports. Every place that names the server to a client reads this: the
-   * resource identifier, the `resource_metadata` URL in the challenge, and `McpRouter`'s same-origin check.
-   */
   publicOrigin(req: Request) {
     if (this.#props.resource) {
       try {
@@ -199,19 +148,6 @@ export class McpAuth {
     return McpAuth.origin(req);
   }
 
-  /**
-   * The public origin as the request reports it, not the one the request arrived on. Behind a proxy `req.url`
-   * names the internal host the proxy dialed, and publishing that as the resource identifier is not cosmetic: an
-   * authorization server issues `aud` for the URL the *client* used, so every correctly-issued token would then
-   * fail the audience check.
-   *
-   * `x-forwarded-host` is a request header, so this is exactly as trustworthy as the edge that overwrites it, and
-   * a deployment whose edge merely appends leaves both the same-origin comparison and the audience a token is
-   * checked against to the caller. A browser cannot reach it — a custom header is not on a preflight, and the
-   * `OPTIONS` is judged on the real host — but a direct caller can. That is why `publicOrigin` prefers a
-   * configured `resource` (`AKAN_MCP_RESOURCE`, or what `libs/shared` derives from its issuer) and reads this only
-   * for a server that pinned nothing.
-   */
   static origin(req: Request) {
     const url = new URL(req.url);
     const forwarded = (header: string) => req.headers.get(header)?.split(",")[0]?.trim();
@@ -219,15 +155,6 @@ export class McpAuth {
     return `${forwarded("x-forwarded-proto") ?? url.protocol.replace(":", "")}://${host}`;
   }
 
-  /**
-   * Who a rate limit counts. A bearer token is one caller however many connections it opens: its session id,
-   * failing that its token id or subject, failing that the token itself hashed — an opaque token has nothing else.
-   * With no token the caller is the address a proxy recorded, and callers with no recorded address share one
-   * bucket, which is the right shape for a server that nothing fronts and that admits anonymous calls.
-   *
-   * Read unverified on purpose: this runs after `reject`, so a token that reaches it has already passed whatever
-   * verification the server has, and a key needs no more than that.
-   */
   static callerKey(req: Request): string {
     const token = McpAuth.#bearer(req);
     if (!token) return `ip:${clientAddressFromHeaders(req.headers) ?? "anonymous"}`;
@@ -237,13 +164,12 @@ export class McpAuth {
   }
 
   static #bearer(req: Request): string | null {
-    const [scheme, token] = (req.headers.get("authorization") ?? "").split(" ");
-    return scheme === "Bearer" && token ? token : null;
+    return /^Bearer +([^ ]+)/i.exec(req.headers.get("authorization") ?? "")?.[1] ?? null;
   }
 
   static #claims(token: string): Record<string, unknown> | null {
     const segments = token.split(".");
-
+    
     if (segments.length !== 3) return null;
     try {
       const claims: unknown = JSON.parse(Buffer.from(segments[1], "base64url").toString("utf8"));

package/server/mcp/McpDispatcher.ts

@@ -1,6 +1,6 @@
-import { type BackendEnv, ENDPOINT_META } from "akanjs/base";
+import { type BackendEnv, ENDPOINT_META, PrimitiveRegistry } from "akanjs/base";
 import { interpolateTranslation, Logger } from "akanjs/common";
-import { ConstantRegistry, mask } from "akanjs/constant";
+import { agentRead, ConstantRegistry, mask } from "akanjs/constant";
 import { DictionaryLookup } from "akanjs/dictionary";
 import { NoDocumentError } from "akanjs/document";
 import type { InjectRegistry, LiveRegistry } from "akanjs/service";
@@ -8,53 +8,30 @@ import type { Endpoint, EndpointCls } from "../../signal/endpoint";
 import type { EndpointInfo } from "../../signal/endpointInfo";
 import { Exception } from "../../signal/exception";
 import type { GuardCls } from "../../signal/guard";
-import { McpDocument, McpErrorCode, type McpExposedEndpoint, type McpToolResult } from "../../signal/mcp";
+import { McpDocument, type McpExposedEndpoint, type McpToolResult } from "../../signal/mcp";
 import type { MiddlewareCls } from "../../signal/middleware";
 import { SignalContext } from "../../signal/signalContext";
 import { McpExecutionContext } from "./McpExecutionContext";
 
-/** Raised when the caller presented no credential at all, so the client should be told to authenticate. */
 export class McpAuthRequiredError extends Error {}
 
-/**
- * A prompt failure whose message has already been through `#message` and is safe to put on the wire.
- *
- * It carries its JSON-RPC code because a prompt has no `isError` result to put a refusal in, so the code is the
- * only place left to say whose fault it was. Without it a mistyped argument reads as `-32603 internal error`,
- * while the *missing*-argument check `prompts/get` does itself answers `-32602` — the same mistake, two codes.
- */
-
 interface McpDispatcherProps {
   registry: InjectRegistry;
   env: BackendEnv;
   live: LiveRegistry;
   middleware: Map<string, MiddlewareCls>;
-  /** The one language error text is resolved in, matching the catalogue the client was handed. */
   language?: string;
-  /**
-   * Whether a structured result also ships as serialized JSON in the text block. `true` by default, which is what
-   * the spec asks for; `false` halves what every model-returning tool costs.
-   */
   legacyTextBlock?: boolean;
 }
 
-/** Executes one MCP tool call or resource read through the ordinary signal pipeline. */
 export class McpDispatcher {
   static readonly logger = new Logger("McpDispatcher");
 
-  /** What the text block says when the serialized duplicate is off. Read by a model, so English. */
   static readonly structuredNote = "The result is in this call's structuredContent.";
 
   readonly #props: McpDispatcherProps;
   #endpoints: Map<string, { endpointInfo: EndpointInfo; endpoint: Endpoint }> | null = null;
-  /**
-   * Built on first use and then held: the merge behind it is not free, a server whose calls all succeed never
-   * needs it, and a caller that types an argument wrong drives that path as often as it likes.
-   *
-   * Not deferred for the reason the endpoint index below is. Dictionaries register at module evaluation, before
-   * any route exists — `McpRouter` builds one at boot to resolve the catalogue's own text — so a lookup made in
-   * the constructor would be correct, just paid for by every process whether or not a call ever fails.
-   */
+  
   #lookup: DictionaryLookup | null = null;
 
   constructor(props: McpDispatcherProps) {
@@ -74,20 +51,12 @@ export class McpDispatcher {
       };
     } catch (error) {
       const status = McpDispatcher.#statusOf(error);
-
+      
       if ((status === 401 || status === 403) && !req.headers.get("authorization")) throw new McpAuthRequiredError();
       return McpDispatcher.#failure(this.#message(error, status, exposed.refName));
     }
   }
 
-  /**
-   * Drops catalogue entries whose account-scoped guards refuse this caller — an anonymous agent should not be
-   * offered a shelf of admin tools it can only fail at. Entries with no such guard are kept and stopped at call
-   * time instead, so the listing is a UX filter and never the access decision.
-   *
-   * The context is deliberately not `init()`-ed: parsing arguments that a listing does not have would throw,
-   * and a resource guard reached here reads `undefined` and fails closed, which is the behaviour we want.
-   */
   async filterForAccount<T extends { name: string }>(items: T[], req: Request): Promise<T[]> {
     const index = this.#index();
 
@@ -133,7 +102,7 @@ export class McpDispatcher {
     args: Record<string, unknown>,
     req: Request,
   ) {
-
+    
     return await SignalContext.run(endpoint, endpointInfo, key, "mcp", async () => {
       const context = await new SignalContext(key, req as Bun.BunRequest, {
         ...this.#props,
@@ -146,13 +115,6 @@ export class McpDispatcher {
     });
   }
 
-  /**
-   * Built on first use and kept: nothing before a `tools/call` needs it, and a router constructed to answer one
-   * request — which tests and tooling do — should not walk the whole registry to do it. Not an ordering
-   * workaround; DI has finished filling the registry long before any route is created.
-   *
-   * Keyed by endpoint key, which is globally unique and is what MCP names a tool by.
-   */
   #index() {
     if (this.#endpoints) return this.#endpoints;
     const endpoints = new Map<string, { endpointInfo: EndpointInfo; endpoint: Endpoint }>();
@@ -165,87 +127,48 @@ export class McpDispatcher {
   }
 
   #message(error: unknown, status: number | undefined, refName: string): string {
-
+    
     if (error instanceof NoDocumentError) return `No ${refName} found for the arguments given.`;
     if (status && status < 500) {
-
+      
       if (status === 401 || status === 403) return "You are not permitted to perform this action.";
       const raw = error instanceof Error ? error.message : String(error);
       
       this.#lookup ??= new DictionaryLookup(this.#props.language);
       const text = this.#lookup.text(raw);
-
       if (text) return interpolateTranslation(text, (error as { data?: Record<string, unknown> }).data);
       return raw;
     }
-
+    
     if (!SignalContext.wasReported(error))
       McpDispatcher.logger.error(`MCP call failed: ${error instanceof Error ? (error.stack ?? error.message) : error}`);
     return "The server failed to complete this request.";
   }
 
-  /**
-   * Anything without a status is treated as a crash, so the two failures an agent can trigger at will carry one:
-   * `McpArgumentError` (400) and `NoDocumentError` (404). Without them a mistyped id logged a stack and answered
-   * "the server failed", which is both a lie and a log-spam path any caller could drive.
-   */
   static #statusOf(error: unknown): number | undefined {
     const status = (error as { statusCode?: unknown } | null)?.statusCode;
     return typeof status === "number" ? status : undefined;
   }
 
-  /**
-   * The same split `#message` makes, in the currency a prompt reports failures in. `-32602` covers a not-found
-   * as well as a bad argument: this revision retired `-32002` and points resource-does-not-exist at invalid
-   * params, so the two caller mistakes share one code by the spec's own choice rather than for want of another.
-   */
-  static #codeOf(status: number | undefined) {
-    return status && status < 500 ? McpErrorCode.invalidParams : McpErrorCode.internal;
-  }
-
-  /**
-   * A structured result rides twice by default: once as `structuredContent`, once as the same JSON here, which is
-   * what the spec asks of a server for clients that predate the structured field. Every model return therefore
-   * costs the model twice what it carries, and `legacyTextBlock: false` is the deployment that has decided its
-   * clients read the structured half — the pointer keeps `content` non-empty, since a client that renders
-   * `content[0].text` and finds nothing shows an empty answer rather than a missing one.
-   */
   #content(structuredContent: unknown, value: unknown): McpToolResult["content"] {
     if (structuredContent !== undefined && this.#props.legacyTextBlock === false)
       return [{ type: "text", text: McpDispatcher.structuredNote }];
     return [{ type: "text", text: McpDispatcher.#text(structuredContent, value) }];
   }
 
-  /**
-   * The text block every result carries, whether or not a structured one goes with it.
-   *
-   * A structured result is mirrored as its JSON, which is what the spec asks for so a client with no structured
-   * support still reads the payload. A scalar return has no structured half to mirror, and encoding one as JSON
-   * spent the block on syntax: a tool returning an id answered `"507f…"`, quotes included, which a model then has
-   * to know to strip. Numbers and booleans read the same either way; only a string differs.
-   *
-   * `JSON.stringify(undefined)` is `undefined` rather than a string, so a void return would otherwise ship a
-   * content block with no `text` at all.
-   */
   static #text(structuredContent: unknown, value: unknown) {
     if (structuredContent === undefined && typeof value === "string") return value;
     return JSON.stringify(structuredContent ?? value) ?? "null";
   }
 
-  /**
-   * Strips what the return model marks `visual` — a field the page renders and no question is answered from.
-   *
-   * Done here rather than in `resolveReturn`, which every ordinary HTTP response also passes through: the point of
-   * a `visual` field is that a browser still receives it. MCP results reach an agent and nothing else, so this is
-   * where the model's own declaration is honoured, and it is the same `mask` the in-page agent's reads use.
-   */
   static #readable(exposed: McpExposedEndpoint, value: unknown): unknown {
-    const { refName, modelType } = exposed.endpoint.returns;
-    if (!modelType) return value;
+    const { refName, modelType, arrDepth = 0 } = exposed.endpoint.returns;
+    if (!modelType)
+      return PrimitiveRegistry.hasName(refName) ? agentRead(PrimitiveRegistry.get(refName), value, arrDepth) : value;
     try {
       return mask(ConstantRegistry.getModelRef(refName, modelType), value);
     } catch (error) {
-
+      
       McpDispatcher.logger.error(
         `MCP could not mask a "${refName}" (${modelType}) result, so it was not sent: ${
           error instanceof Error ? error.message : String(error)

package/server/mcp/McpEventStream.ts

@@ -1,17 +1,7 @@
-import { EventStream } from "../routing/eventStream";
+import { EventStream } from "akanjs/common";
 
-/**
- * One `text/event-stream` response carrying the notifications a single request produced, ending with that
- * request's own result.
- *
- * This is the only channel a server has for pushing anything: `2026-07-28` removed the GET stream, session
- * resumption and server-initiated requests, so nothing may be sent that is not related to a request in flight.
- * Closing the stream is also how the client cancels — `notifications/cancelled` is stdio-only — which is why
- * `cancel` is a constructor argument rather than something a caller could forget to wire. No event carries an
- * `id:`, since there is nothing a reconnecting client could resume.
- */
 export class McpEventStream extends EventStream {
-  /** Below any common proxy idle timeout, so a slow tool does not have its connection reaped mid-work. */
+  
   static readonly keepAliveMs = 15_000;
 
   constructor(onCancel: () => void) {

package/server/mcp/McpExecutionContext.ts

@@ -6,22 +6,10 @@ import { HttpExecutionContext } from "../../signal/signalContext";
 
 type McpArg = EndpointInfo["args"][number];
 
-/**
- * An argument the caller can fix, carrying a 400 so the dispatcher reports it as a tool error rather than as a
- * server failure. Everything that rejects an argument — the nullable check, `ID._parse`, a scalar's own
- * validator — throws a bare `Error`, and a bare `Error` is indistinguishable from a crash.
- */
 export class McpArgumentError extends Error {
   readonly statusCode = 400;
 }
 
-/**
- * Runs an endpoint for an MCP call while staying an HTTP context.
- *
- * MCP arrives over HTTP and the whole authorization stack reads the request through this context —
- * `AccountMiddleware` resolves the bearer token off `getHttpContext().req`, and `Self`/`Me` and every guard read
- * what it left there. A transport of its own would not adapt that stack, it would bypass it.
- */
 export class McpExecutionContext extends HttpExecutionContext {
   readonly #arguments: Record<string, unknown>;
 
@@ -31,22 +19,6 @@ export class McpExecutionContext extends HttpExecutionContext {
     this.#arguments = args;
   }
 
-  /**
-   * MCP passes one flat named object, so `param`/`search`/`body` all resolve by name from the same place. An
-   * absent value becomes `null` to match what a missing query string yields, letting `deserialize` apply the
-   * same nullability rules an HTTP call gets.
-   *
-   * A name nobody declared is the caller's mistake and is reported as one. `additionalProperties: false` travels
-   * in the published schema, but this server does not validate against it and plenty of clients do not either —
-   * so reading only the declared names dropped the rest in silence: `{ category, status }` on a slice that takes
-   * only `category` came back as a successful, unfiltered list, which a model reads as the filter having applied.
-   *
-   * "Declared" means what the *published schema* declares, which is why an `Any` argument counts as absent here.
-   * It is deliberately left out of that schema — the empty schema tells a model nothing — and the root list's raw
-   * `query` descriptor is the one that matters: read as sent, an agent could hand any model exposed through
-   * `mcp: { list: true }` an arbitrary query, which is precisely the narrowing a named filter slice exists to make
-   * deliberate. `additionalProperties: false` was never going to stop that on its own.
-   */
   override async getArgs(endpointInfo: EndpointInfo): Promise<unknown[]> {
     const declared = new Set(endpointInfo.args.filter(McpExecutionContext.#describable).map((arg) => arg.name));
     const undeclared = Object.keys(this.#arguments).find((name) => !declared.has(name));
@@ -60,17 +32,12 @@ export class McpExecutionContext extends HttpExecutionContext {
           enum: arg.enum,
         });
       } catch {
-
+        
         throw new McpArgumentError(McpExecutionContext.#argumentMessage(arg, value));
       }
     });
   }
 
-  /**
-   * Returns the serialized value rather than a `Response`, so the router can put it straight into a JSON-RPC
-   * result. The `Response` in the signature is the base class's; `WebSocketExecutionContext` widens it the same
-   * way, and `SignalContext` only ever hands this value back to its caller.
-   */
   override makeResponse(result: unknown, endpointInfo: EndpointInfo) {
     if (endpointInfo.returns.arrDepth === 0 && PrimitiveRegistry.has(endpointInfo.returns.returnRef as Cls))
       return result as unknown as Response;
@@ -79,18 +46,10 @@ export class McpExecutionContext extends HttpExecutionContext {
     }) as unknown as Response;
   }
 
-  /**
-   * One value where a list was declared becomes a one-element list. Both callers produce it: form-style uri
-   * expansion writes `?tags=a` for a single tag, and a model routinely types a bare string for an array field.
-   * The http context never meets this because `searchParams.getAll` always returns an array, and `deserialize`
-   * hands a lone scalar straight back instead of lifting it — so the endpoint would receive a string where it
-   * iterates a list.
-   */
   static #lift(arg: McpArg, value: unknown) {
     return arg.arrDepth && value !== null && !Array.isArray(value) ? [value] : value;
   }
 
-  /** The same rule `McpDocument` builds `properties` from, so what is refused is exactly what was not published. */
   static #describable(arg: McpArg) {
     const refName = PrimitiveRegistry.has(arg.argRef as Cls)
       ? PrimitiveRegistry.getName(arg.argRef as typeof PrimitiveScalar)

package/server/mcp/McpRateLimiter.ts

@@ -1,8 +1,15 @@
+import { type Dayjs, dayjs } from "akanjs/base";
+import { Logger } from "akanjs/common";
+
+export interface McpSharedCounter {
+  incr(topic: string, key: string, by?: number, option?: { expireAt?: Dayjs }): Promise<number>;
+}
+
 export interface McpRateLimitOption {
-  /** Calls one caller may make per window. `0` turns the counter off. */
+  /** Per caller per window; `0` turns the counter off. */
   calls?: number;
   windowMs?: number;
-  /** Calls one caller may have running at the same time. `0` turns the cap off. */
+  /** Per caller at once; `0` turns the cap off. */
   concurrent?: number;
 }
 
@@ -16,60 +23,85 @@ interface McpRateBucket {
   inFlight: number;
 }
 
-/**
- * Per-caller budget for the MCP methods that execute an endpoint.
- *
- * Two limits because they stop two different loops. A fixed window of `calls` stops a model that re-reads a list
- * slice as fast as the client lets it; a cap on `concurrent` calls stops one that fans out a ten-second query in
- * parallel, which the window alone would admit until the window filled. Counted in this process only — a
- * deployment with N replicas grants N budgets — and keyed by the caller the router derives, so a reset is a
- * restart and nothing else.
- */
 export class McpRateLimiter {
   static readonly defaults = { calls: 120, windowMs: 60_000, concurrent: 8 } as const;
+  static readonly #logger = new Logger("McpRateLimiter");
 
   readonly calls: number;
   readonly windowMs: number;
   readonly concurrent: number;
+  readonly #shared: McpSharedCounter | null;
   readonly #buckets = new Map<string, McpRateBucket>();
   #sweptAt = 0;
+  #sharedFailed = false;
 
-  constructor({
-    calls = McpRateLimiter.defaults.calls,
-    windowMs = McpRateLimiter.defaults.windowMs,
-    concurrent = McpRateLimiter.defaults.concurrent,
-  }: McpRateLimitOption = {}) {
+  constructor(
+    {
+      calls = McpRateLimiter.defaults.calls,
+      windowMs = McpRateLimiter.defaults.windowMs,
+      concurrent = McpRateLimiter.defaults.concurrent,
+    }: McpRateLimitOption = {},
+    shared: McpSharedCounter | null = null,
+  ) {
     this.calls = Math.max(0, Math.floor(calls));
     this.windowMs = Math.max(1, Math.floor(windowMs));
     this.concurrent = Math.max(0, Math.floor(concurrent));
+    this.#shared = shared;
   }
 
-  acquire(key: string, now = Date.now()): McpRateLimitVerdict {
+  async acquire(key: string, now = Date.now()): Promise<McpRateLimitVerdict> {
     this.#sweep(now);
     const bucket = this.#bucketOf(key, now);
     if (this.concurrent && bucket.inFlight >= this.concurrent)
       return { ok: false, reason: "concurrent", retryAfterMs: 1_000 };
-    if (this.calls && bucket.count >= this.calls)
-      return { ok: false, reason: "calls", retryAfterMs: Math.max(1, bucket.windowStart + this.windowMs - now) };
-    bucket.count += 1;
+    
     bucket.inFlight += 1;
     let released = false;
-    return {
-      ok: true,
-      release: () => {
-        if (released) return;
-        released = true;
-        bucket.inFlight = Math.max(0, bucket.inFlight - 1);
-      },
+    const release = () => {
+      if (released) return;
+      released = true;
+      bucket.inFlight = Math.max(0, bucket.inFlight - 1);
     };
+    const retryAfterMs = this.calls ? await this.#spend(key, bucket, now) : null;
+    if (retryAfterMs === null) return { ok: true, release };
+    release();
+    return { ok: false, reason: "calls", retryAfterMs };
   }
 
   describe() {
-    const window = this.calls ? `${this.calls} calls / ${Math.round(this.windowMs / 1000)}s` : "unlimited calls";
-    const inFlight = this.concurrent ? `${this.concurrent} in flight` : "unlimited in flight";
+    const across = this.#shared ? " across instances" : "";
+    const window = this.calls
+      ? `${this.calls} calls / ${Math.round(this.windowMs / 1000)}s${across}`
+      : "unlimited calls";
+    const inFlight = this.concurrent
+      ? `${this.concurrent} in flight${this.#shared ? " per instance" : ""}`
+      : "unlimited in flight";
     return `${window}, ${inFlight}, per caller`;
   }
 
+  async #spend(key: string, bucket: McpRateBucket, now: number): Promise<number | null> {
+    if (this.#shared) {
+      const window = Math.floor(now / this.windowMs);
+      const end = (window + 1) * this.windowMs;
+      try {
+        const count = await this.#shared.incr("mcpRate", `${key}:${window}`, 1, {
+          expireAt: dayjs(end + this.windowMs),
+        });
+        this.#sharedFailed = false;
+        return count > this.calls ? Math.max(1, end - now) : null;
+      } catch (error) {
+        if (!this.#sharedFailed)
+          McpRateLimiter.#logger.warn(
+            `MCP rate limit cannot reach the cache, so each instance counts its own window until it can: ${String(error)}`,
+          );
+        this.#sharedFailed = true;
+      }
+    }
+    if (bucket.count >= this.calls) return Math.max(1, bucket.windowStart + this.windowMs - now);
+    bucket.count += 1;
+    return null;
+  }
+
   #bucketOf(key: string, now: number) {
     const found = this.#buckets.get(key);
     if (found && now - found.windowStart < this.windowMs) return found;
@@ -78,7 +110,6 @@ export class McpRateLimiter {
     return bucket;
   }
 
-  /** Buckets are dropped once idle for a window, so the map is bounded by the callers of the last window, not ever. */
   #sweep(now: number) {
     if (now - this.#sweptAt < this.windowMs) return;
     this.#sweptAt = now;