akanjs 3.0.0-alpha.101 → 3.0.0-alpha.102

package/common/TrustedProxy.ts

@@ -67,6 +67,23 @@ export class TrustedProxy {
     return peerAddress ? normalizeIpAddress(peerAddress) : null;
   }
 
+  /**
+   * Whether an address is one no public name should resolve to: the local ranges `isTrusted` reads, plus the
+   * unspecified address, the carrier-grade NAT block `100.64/10`, multicast and the reserved top of IPv4. Used
+   * to refuse a fetch whose destination a caller chose by name, so it judges the address alone and never the
+   * configured proxy list — a trusted proxy is still not somewhere to send an outbound request.
+   */
+  static isPrivateAddress(address: string): boolean {
+    const bytes = TrustedProxy.#toBytes(normalizeIpAddress(address));
+    if (!bytes) return true;
+    if (TrustedProxy.#isLocalRange(bytes)) return true;
+    if (bytes.length === 4) {
+      const [a = 0, b = 0] = bytes;
+      return a === 0 || (a === 100 && b >= 64 && b <= 127) || a >= 224;
+    }
+    return bytes.every((byte) => byte === 0) || bytes[0] === 0xff;
+  }
+
   /** `10/8`, `172.16/12`, `192.168/16`, `127/8`, `169.254/16`, and their IPv6 counterparts `::1`, `fc00::/7`, `fe80::/10`. */
   static #isLocalRange(bytes: Uint8Array): boolean {
     if (bytes.length === 4) {

package/common/mcpExposure.ts

@@ -17,6 +17,8 @@ export interface McpExposureEndpoint {
   guards?: string[];
   fileUpload?: boolean;
   mcp?: boolean;
+  /** `false` when a guard declares `static agents = false`: no model may ever pass, whatever else the guards say. */
+  agents?: boolean;
 }
 
 export interface McpExposureOption {
@@ -68,6 +70,9 @@ export const mcpRefusalOf = (
   if (endpoint.mcp === false)
     return "it declares `mcp: false`, so it is deliberately off the agent shelf. HTTP still serves it.";
 
+  if (endpoint.agents === false)
+    return `its guards (${(endpoint.guards ?? []).join(", ")}) admit no agent — an act reserved for a person, so it is off the agent shelf. HTTP still serves it.`;
+
   if (!endpoint.guards?.length)
     return "it declares no guards, and exposure follows them — write `guards: [Public]` if anonymous access is the intent.";
 

package/fetch/client/fetchClient.ts

@@ -456,8 +456,10 @@ export class FetchClient {
     const updateGuards = signal.updateGuards ?? signal.cruGuards;
     const removeGuards = signal.removeGuards ?? signal.cruGuards;
 
-    const mcp = (verb: keyof NonNullable<SerializedSignal["mcp"]>) =>
-      signal.mcp?.[verb] === false ? { mcp: false as const } : {};
+    const mcp = (verb: keyof NonNullable<SerializedSignal["mcp"]>) => ({
+      ...(signal.mcp?.[verb] === false ? { mcp: false as const } : {}),
+      ...(signal.agents?.[verb] === false ? { agents: false as const } : {}),
+    });
     const endpoint: { [key: string]: SerializedEndpoint } = {};
     if (signal.getGuards) {
       endpoint[names.model] = {
@@ -631,7 +633,10 @@ export class FetchClient {
       live: `${refName}Live${capSuffix}`,
     };
 
-    const mcp = slice.mcp === false ? { mcp: false as const } : {};
+    const mcp = {
+      ...(slice.mcp === false ? { mcp: false as const } : {}),
+      ...(slice.agents === false ? { agents: false as const } : {}),
+    };
     const endpoint: { [key: string]: SerializedEndpoint } = {
       [names.list]: {
         type: "query",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.101",
+  "version": "3.0.0-alpha.102",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -96,6 +96,17 @@ export interface AkanAppOptions {
    * module. Handed down as `AKAN_MODULES`, since each replica builds its own container.
    */
   modules?: string[];
+  /**
+   * The inverse of `modules`: mount everything except these and whatever reaches them, in every child. Written
+   * for a lib the app depends on but does not serve — `server.ts` is generated from the dependency graph, so a
+   * lib cannot be dropped by editing it. Handed down as `AKAN_DISABLE_MODULES`, and applied after `modules`.
+   */
+  disableModules?: string[];
+  /**
+   * The same, by owning lib: every module the named libs registered stays out of every child, along with
+   * everything that reaches one. Handed down as `AKAN_DISABLE_LIBS`.
+   */
+  disableLibs?: string[];
   /**
    * Run the one replica in this process instead of spawning it — see `#startSolo`. Defaults on for a single
    * traffic replica the environment configured, and off whenever `replica` is passed here, because code that
@@ -141,6 +152,8 @@ export class AkanApp {
   /** The gateway hands `/_akan/client|styles|fonts` straight off disk, so it needs the same answer its children do. */
   readonly #web = getWebConfigFromEnv();
   readonly #modules: string[];
+  readonly #disableModules: string[];
+  readonly #disableLibs: string[];
   readonly #solo: boolean;
   readonly #children = new Map<number, ChildState>();
   readonly #roomChildren = new Map<string, Set<number>>();
@@ -182,6 +195,8 @@ export class AkanApp {
     this.#prefix = normalizeRoutePrefix(resolvedOptions.prefix) ?? getApiPrefix();
     this.#websocketPrefix = normalizeRoutePrefix(resolvedOptions.websocketPrefix) ?? getWsPrefix();
     this.#modules = resolvedOptions.modules ?? [];
+    this.#disableModules = resolvedOptions.disableModules ?? [];
+    this.#disableLibs = resolvedOptions.disableLibs ?? [];
     this.#solo = AkanApp.#resolveSolo(resolvedOptions, this.#replica);
     this.#logHub = LogHub.attach();
   }
@@ -322,6 +337,8 @@ export class AkanApp {
       AKAN_WS_PREFIX: this.#websocketPrefix,
       ...(this.#openapi === undefined ? {} : { AKAN_OPENAPI: this.#openapi ? "true" : "false" }),
       ...(this.#modules.length ? { AKAN_MODULES: this.#modules.join(",") } : {}),
+      ...(this.#disableModules.length ? { AKAN_DISABLE_MODULES: this.#disableModules.join(",") } : {}),
+      ...(this.#disableLibs.length ? { AKAN_DISABLE_LIBS: this.#disableLibs.join(",") } : {}),
     });
 
     resetEnvCache();
@@ -415,6 +432,8 @@ export class AkanApp {
         AKAN_WS_PREFIX: this.#websocketPrefix,
         ...(this.#openapi === undefined ? {} : { AKAN_OPENAPI: this.#openapi ? "true" : "false" }),
         ...(this.#modules.length ? { AKAN_MODULES: this.#modules.join(",") } : {}),
+        ...(this.#disableModules.length ? { AKAN_DISABLE_MODULES: this.#disableModules.join(",") } : {}),
+        ...(this.#disableLibs.length ? { AKAN_DISABLE_LIBS: this.#disableLibs.join(",") } : {}),
       },
       ipc: (message) => this.#handleMessage(idx, message as AkanIpcMessage, proc),
       stdout: "pipe",

package/server/akanServer.ts

@@ -33,7 +33,7 @@ import { LogForwarder } from "./logging/logForwarder";
 import { LogHub } from "./logging/logHub";
 import { LogStreamRoute } from "./logging/logStreamRoute";
 import { RotatingLogWriter } from "./logging/rotatingLogWriter";
-import { type McpAuthOption, McpRouter } from "./mcp";
+import { type McpAuthOption, type McpRateLimitOption, McpRouter } from "./mcp";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { WebProxyRunner } from "./proxy";
 import { SignalResolver } from "./resolver";
@@ -65,6 +65,18 @@ export interface AkanServerOptions {
    * services, signals, routes and schedules do not exist. Omitted or empty mounts every enabled module.
    */
   modules?: string[];
+  /**
+   * The inverse of `modules`: mount everything except these and whatever reaches them. Written for a lib the
+   * app depends on but does not serve — `server.ts` is generated from the dependency graph, so a lib cannot be
+   * dropped by editing it. Applied after `modules`, so a module named by both stays out.
+   */
+  disableModules?: string[];
+  /**
+   * The same, by owning lib: every module the named libs registered stays out, along with everything that
+   * reaches one. This is the spelling for a lib the app depends on but does not serve — it does not drift as
+   * the lib gains modules.
+   */
+  disableLibs?: string[];
 }
 
 export interface McpServerOption {
@@ -106,8 +118,20 @@ export interface McpServerOption {
    * half turns this off and halves what each of those calls costs the model. `AKAN_MCP_LEGACY_TEXT=false`.
    */
   legacyTextBlock?: boolean;
+  /**
+   * How much of a result's shape each tool advertises: `shallow` (default) names nested models instead of inlining
+   * them, `full` inlines the whole closure, `none` publishes no `outputSchema` and keeps the text block on. The
+   * listing is re-sent to every agent that connects, and the nested closures were most of it. `AKAN_MCP_OUTPUT_SCHEMA`.
+   */
+  outputSchema?: "full" | "shallow" | "none";
   /** OAuth resource-server identity: which issuers a client may authenticate with, and the scopes to demand. */
   auth?: McpAuthOption;
+  /**
+   * Per-caller budget for `tools/call`, `resources/read` and `prompts/get`: 120 calls a minute and 8 in flight by
+   * default, counted per process. `false` takes it off. `AKAN_MCP_RATE_LIMIT` (`<calls>` or `<calls>/<seconds>`,
+   * `off` to disable) and `AKAN_MCP_CONCURRENT`.
+   */
+  rateLimit?: McpRateLimitOption | false;
 }
 
 interface AkanAppPrepared {
@@ -156,6 +180,8 @@ export class AkanServer {
   /** Resolved at `init`: what this process actually serves, after env and artifact availability. */
   web: AkanWebConfig = getWebConfigFromEnv();
   modules: string[];
+  disableModules: string[];
+  disableLibs: string[];
   shutdownTimeoutMs = AkanServer.#defaultShutdownTimeoutMs();
 
   #di: DiLifecycle;
@@ -206,7 +232,12 @@ export class AkanServer {
     this.serverMode = serverMode;
     
     this.modules = options?.modules ?? AkanServer.#envList("AKAN_MODULES") ?? [];
-    this.#di = new DiLifecycle({ env: this.env, modules: this.modules }, ...libs);
+    this.disableModules = options?.disableModules ?? AkanServer.#envList("AKAN_DISABLE_MODULES") ?? [];
+    this.disableLibs = options?.disableLibs ?? AkanServer.#envList("AKAN_DISABLE_LIBS") ?? [];
+    this.#di = new DiLifecycle(
+      { env: this.env, modules: this.modules, disableModules: this.disableModules, disableLibs: this.disableLibs },
+      ...libs,
+    );
   }
   setPrefix(prefix: string) {
     if (this.status !== "stopped") throw new Error("Route prefix must be set before app initialization.");
@@ -813,7 +844,11 @@ export class AkanServer {
         !("database" in value) &&
         !("service" in value) &&
         !("scalar" in value) &&
-        ("openapi" in value || "mcp" in value || "modules" in value),
+        ("openapi" in value ||
+          "mcp" in value ||
+          "modules" in value ||
+          "disableModules" in value ||
+          "disableLibs" in value),
     );
   }
 
@@ -884,9 +919,31 @@ export class AkanServer {
       ...(Number.isInteger(pageSize) && pageSize > 0 ? { pageSize } : {}),
       ...(process.env.AKAN_MCP_LANGUAGE ? { language: process.env.AKAN_MCP_LANGUAGE } : {}),
       ...(AkanServer.#isEnvOff("AKAN_MCP_LEGACY_TEXT") ? { legacyTextBlock: false } : {}),
+      ...AkanServer.#mcpOutputSchemaFromEnv(),
+      ...AkanServer.#mcpRateLimitFromEnv(),
     };
   }
 
+  /** `AKAN_MCP_RATE_LIMIT=off` disables; `120` is per minute, `120/30` per thirty seconds; `AKAN_MCP_CONCURRENT` caps in-flight calls. */
+  static #mcpRateLimitFromEnv(): Pick<McpServerOption, "rateLimit"> {
+    const raw = process.env.AKAN_MCP_RATE_LIMIT?.trim().toLowerCase();
+    if (raw === "off" || raw === "false" || raw === "0") return { rateLimit: false };
+    const option: McpRateLimitOption = {};
+    if (raw) {
+      const [calls, seconds] = raw.split("/").map((part) => Number(part));
+      if (Number.isInteger(calls) && calls > 0) option.calls = calls;
+      if (Number.isInteger(seconds) && seconds > 0) option.windowMs = seconds * 1000;
+    }
+    const concurrent = Number(process.env.AKAN_MCP_CONCURRENT);
+    if (Number.isInteger(concurrent) && concurrent >= 0) option.concurrent = concurrent;
+    return Object.keys(option).length ? { rateLimit: option } : {};
+  }
+
+  static #mcpOutputSchemaFromEnv(): Pick<McpServerOption, "outputSchema"> {
+    const value = process.env.AKAN_MCP_OUTPUT_SCHEMA;
+    return value === "full" || value === "shallow" || value === "none" ? { outputSchema: value } : {};
+  }
+
   /**
    * Both consumers build their path by concatenation — the route key, and the RFC 9728 metadata path the resource
    * identifier is inserted into — so `AKAN_MCP_PATH=mcp` served a route named `mcp` and published its metadata at

package/server/di/diLifecycle.ts

@@ -50,6 +50,17 @@ export interface DiLifecycleProps {
    * empty mounts every module whose service is enabled.
    */
   modules?: string[];
+  /**
+   * Drop these modules and everything that reaches them, leaving the rest mounted. Applied over `modules`
+   * rather than beside it, so a module named by both stays out.
+   */
+  disableModules?: string[];
+  /**
+   * The same, by owning lib: every database and service module the named libs registered goes, along with
+   * everything that reaches one. What a lib's `option.ts` contributes — middleware, web proxies, adaptor
+   * overrides — is untouched, as it is under `modules`.
+   */
+  disableLibs?: string[];
 }
 
 /**
@@ -100,7 +111,7 @@ export class DiLifecycle {
     return !names.some((name) => process.env[name] === "false" || process.env[name] === "0");
   }
 
-  constructor({ env, modules = [] }: DiLifecycleProps, ...libs: AkanLib[]) {
+  constructor({ env, modules = [], disableModules = [], disableLibs = [] }: DiLifecycleProps, ...libs: AkanLib[]) {
     this.#env = env;
     
     this.#predefinedAdaptor = { ...getPredefinedAdaptor(getEnv().databaseMode ?? "single") };
@@ -122,6 +133,8 @@ export class DiLifecycle {
     this.webProxies.push(...defaultOption.getWebProxies());
     const databaseCandidates = new Map<string, DiModuleCandidate>();
     const serviceCandidates = new Map<string, DiModuleCandidate>();
+
+    const moduleLibs = new Map<string, string>();
     libs.forEach((lib) => {
       lib.option.getMiddlewares().forEach((middleware) => {
         this.#middleware.set(middleware.refName, middleware);
@@ -137,15 +150,24 @@ export class DiLifecycle {
       this.webProxies.push(...lib.option.getWebProxies());
       lib.database.forEach((mod) => {
         databaseCandidates.set(mod.constant.refName, { refName: mod.constant.refName, module: mod });
+        moduleLibs.set(mod.constant.refName, lib.name);
       });
       lib.service.forEach((mod) => {
         serviceCandidates.set(mod.service.srv.refName, { refName: mod.service.srv.refName, module: mod });
+        moduleLibs.set(mod.service.srv.refName, lib.name);
       });
       lib.scalar.forEach((mod) => {
         this.#scalar.set(mod.constant.refName, mod);
       });
     });
-    const disabledModules = this.#resolveDisabledModules(databaseCandidates, serviceCandidates, modules);
+    const disabledModules = this.#resolveDisabledModules({
+      databaseCandidates,
+      serviceCandidates,
+      modules,
+      disableModules,
+      disableLibs,
+      moduleLibs,
+    });
     databaseCandidates.forEach(({ refName, module }) => {
       if (disabledModules.has(refName)) return;
       this.#database.set(refName, module as DatabaseModule);
@@ -188,11 +210,21 @@ export class DiLifecycle {
     assertUniqueRegistrations("adaptor", adaptorRegistrations);
   }
 
-  #resolveDisabledModules(
-    databaseCandidates: Map<string, DiModuleCandidate>,
-    serviceCandidates: Map<string, DiModuleCandidate>,
-    modules: string[],
-  ) {
+  #resolveDisabledModules({
+    databaseCandidates,
+    serviceCandidates,
+    modules,
+    disableModules,
+    disableLibs,
+    moduleLibs,
+  }: {
+    databaseCandidates: Map<string, DiModuleCandidate>;
+    serviceCandidates: Map<string, DiModuleCandidate>;
+    modules: string[];
+    disableModules: string[];
+    disableLibs: string[];
+    moduleLibs: Map<string, string>;
+  }) {
     const candidates = new Map<string, DiModuleCandidate>([...databaseCandidates, ...serviceCandidates]);
     const disabledReasons = new Map<string, string>();
 
@@ -208,6 +240,13 @@ export class DiLifecycle {
       });
     }
 
+    const excluded = this.#resolveExcludedModules({ candidates, disableModules, disableLibs, moduleLibs });
+    
+    excluded.forEach((reason, refName) => {
+      if (!disabledReasons.has(refName)) disabledReasons.set(refName, reason);
+    });
+    const excludedClosure = new Set(excluded.keys());
+
     let changed = true;
     while (changed) {
       changed = false;
@@ -218,6 +257,7 @@ export class DiLifecycle {
           const dependencyReason = disabledReasons.get(dependencyRefName);
           if (!dependencyReason) continue;
           disabledReasons.set(refName, `depends on disabled module "${dependencyRefName}"`);
+          if (excludedClosure.has(dependencyRefName)) excludedClosure.add(refName);
           changed = true;
           break;
         }
@@ -228,9 +268,70 @@ export class DiLifecycle {
       this.disabledModules.set(refName, reason);
       this.logger.verbose(`Skipping disabled module "${refName}": ${reason}`);
     });
+    
+    const cascaded = [...excludedClosure]
+      .filter((refName) => !excluded.has(refName))
+      .sort((a, b) => a.localeCompare(b));
+    if (cascaded.length) {
+      const option = disableLibs.length
+        ? disableModules.length
+          ? "disableModules/disableLibs"
+          : "disableLibs"
+        : "disableModules";
+      this.logger.info(`${option} also dropped ${cascaded.length} dependent module(s): ${cascaded.join(", ")}`);
+    }
     return new Set(disabledReasons.keys());
   }
 
+  /**
+   * The modules the caller took off, by name and by owning lib, each mapped to the reason it is gone. An
+   * unknown name is refused for the mirror of the reason `modules` refuses one: a typo there drops a module
+   * silently, and a typo here keeps one running silently.
+   */
+  #resolveExcludedModules({
+    candidates,
+    disableModules,
+    disableLibs,
+    moduleLibs,
+  }: {
+    candidates: Map<string, DiModuleCandidate>;
+    disableModules: string[];
+    disableLibs: string[];
+    moduleLibs: Map<string, string>;
+  }) {
+    const excluded = new Map<string, string>();
+    if (disableModules.length) {
+      const known = new Set([...candidates.keys(), ...this.#service.keys()]);
+      const unknown = disableModules.filter((refName) => !known.has(refName));
+      if (unknown.length) {
+        const registered = [...known].sort((a, b) => a.localeCompare(b)).join(", ");
+        throw new Error(
+          `[DI:disableModules] unknown module ${unknown.map((refName) => `"${refName}"`).join(", ")}. Registered: ${registered}`,
+        );
+      }
+      disableModules.forEach((refName) => {
+        if (candidates.has(refName)) excluded.set(refName, 'named by the "disableModules" option');
+      });
+    }
+    if (disableLibs.length) {
+
+      const known = new Set(this.#libs.map((lib) => lib.name));
+      const unknown = disableLibs.filter((name) => !known.has(name));
+      if (unknown.length) {
+        const registered = [...known].sort((a, b) => a.localeCompare(b)).join(", ");
+        throw new Error(
+          `[DI:disableLibs] unknown lib ${unknown.map((name) => `"${name}"`).join(", ")}. Mounted: ${registered}`,
+        );
+      }
+      const excludedLibs = new Set(disableLibs);
+      moduleLibs.forEach((libName, refName) => {
+        if (!excludedLibs.has(libName) || !candidates.has(refName) || excluded.has(refName)) return;
+        excluded.set(refName, `in lib "${libName}", named by the "disableLibs" option`);
+      });
+    }
+    return excluded;
+  }
+
   /**
    * The named modules closed over everything they reach: the services and signals they inject, and the cascade
    * edges whose absence fails `CascadeRunner.seal`. `null` means no selection was asked for.

package/server/mcp/McpAuth.ts

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto";
 import type { PromiseOrObject } from "akanjs/base";
+import { clientAddressFromHeaders } from "akanjs/common";
 import type { HttpRoutes } from "../types";
 
 export interface McpAuthOption {
@@ -170,7 +172,7 @@ export class McpAuth {
     return [
       "Bearer",
       [
-        `resource_metadata="${new URL(McpAuth.wellKnownPath + this.#props.path, McpAuth.origin(req)).href}"`,
+        `resource_metadata="${new URL(McpAuth.wellKnownPath + this.#props.path, this.publicOrigin(req)).href}"`,
         ...(failure ? [`error="${failure.error}"`, `error_description="${failure.description}"`] : []),
         ...(scopes.length ? [`scope="${scopes.join(" ")}"`] : []),
       ].join(", "),
@@ -178,22 +180,37 @@ export class McpAuth {
   }
 
   #resource(req: Request) {
-    return this.#props.resource ?? new URL(this.#props.path, McpAuth.origin(req)).href;
+    return this.#props.resource ?? new URL(this.#props.path, this.publicOrigin(req)).href;
   }
 
   /**
-   * The public origin, 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.
-   *
-   * `McpRouter` compares an `Origin` header against this too — the same proxy that makes `req.url` wrong for the
-   * metadata document makes it wrong for a same-origin check, and there the cost is a flat 403.
+   * 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 {
+        return new URL(this.#props.resource).origin;
+      } catch {
+      }
+    }
+    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. `AKAN_MCP_RESOURCE` pins the identifier for a
-   * deployment that cannot make the guarantee.
+   * `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);
@@ -202,6 +219,23 @@ 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"}`;
+    const claims = McpAuth.#claims(token);
+    const id = [claims?.sid, claims?.jti, claims?.sub].find((value) => typeof value === "string" && value);
+    return typeof id === "string" ? `token:${id}` : `token:${createHash("sha256").update(token).digest("base64url")}`;
+  }
+
   static #bearer(req: Request): string | null {
     const [scheme, token] = (req.headers.get("authorization") ?? "").split(" ");
     return scheme === "Bearer" && token ? token : null;

package/server/mcp/McpDispatcher.ts

@@ -154,6 +154,7 @@ export class McpDispatcher {
             endpointInfo: found.endpointInfo,
             adaptor: found.endpoint,
             ctx: new McpExecutionContext(req, {}),
+            origin: "mcp",
           }).canListForAccount();
         cached.set(key, verdict);
         return await verdict;

package/server/mcp/McpRateLimiter.ts

@@ -0,0 +1,88 @@
+export interface McpRateLimitOption {
+  /** Calls one caller may make 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. */
+  concurrent?: number;
+}
+
+export type McpRateLimitVerdict =
+  | { ok: true; release: () => void }
+  | { ok: false; reason: "calls" | "concurrent"; retryAfterMs: number };
+
+interface McpRateBucket {
+  windowStart: number;
+  count: number;
+  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;
+
+  readonly calls: number;
+  readonly windowMs: number;
+  readonly concurrent: number;
+  readonly #buckets = new Map<string, McpRateBucket>();
+  #sweptAt = 0;
+
+  constructor({
+    calls = McpRateLimiter.defaults.calls,
+    windowMs = McpRateLimiter.defaults.windowMs,
+    concurrent = McpRateLimiter.defaults.concurrent,
+  }: McpRateLimitOption = {}) {
+    this.calls = Math.max(0, Math.floor(calls));
+    this.windowMs = Math.max(1, Math.floor(windowMs));
+    this.concurrent = Math.max(0, Math.floor(concurrent));
+  }
+
+  acquire(key: string, now = Date.now()): 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);
+      },
+    };
+  }
+
+  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";
+    return `${window}, ${inFlight}, per caller`;
+  }
+
+  #bucketOf(key: string, now: number) {
+    const found = this.#buckets.get(key);
+    if (found && now - found.windowStart < this.windowMs) return found;
+    const bucket: McpRateBucket = { windowStart: now, count: 0, inFlight: found?.inFlight ?? 0 };
+    this.#buckets.set(key, bucket);
+    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;
+    for (const [key, bucket] of this.#buckets)
+      if (!bucket.inFlight && now - bucket.windowStart >= this.windowMs) this.#buckets.delete(key);
+  }
+}