@oxy.so/core 7.19.0 → 7.20.0

package/dist/esm/server/appPermissions.js

@@ -2,10 +2,13 @@
  * Application roles, from the application's side: which of THIS application's
  * declared permissions does the person behind a request hold?
  *
- * Oxy decides who holds an app's operator powers (`docs/auth/application-roles.md`).
- * An app declares its keys (`payments.operate`, …) in the Console, its owners
- * grant them to people, and its backend asks — so no app keeps a
- * `*_OPERATOR_OXY_USER_IDS` allow-list in its environment.
+ * Oxy decides who holds an app's operator powers (`docs/auth/application-roles.md`),
+ * and the backend asks — so no app keeps a `*_OPERATOR_OXY_USER_IDS` allow-list
+ * in its environment. One of Oxy's own applications declares its keys
+ * (`payments.operate`, …) in Oxy's first-party registry, each held by roles of
+ * the owning organization (ADR 0056); a third-party app declares them in the
+ * Console and its owners grant them to people. The answer has the same shape
+ * either way.
  *
  * ```ts
  * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', applicationId: process.env.OXY_APPLICATION_ID });
@@ -31,6 +34,23 @@
  * `X-Oxy-User-Id`, is refused — an operator power is exercised by a person in
  * a session, never through delegation.
  *
+ * ## An MCP tool call
+ *
+ * An MCP request carries no session: its bearer is an access token Oxy issued
+ * for this app's MCP resource, which `@oxy.so/mcp`'s transport introspected
+ * live before the tool ran. Pass the call's `extra` (`context.request` in a
+ * catalog handler or `authorize`) the same way:
+ *
+ * ```ts
+ * const held = await oxy.appPermissionsFor(context.request, { fresh: true });
+ * ```
+ *
+ * The SDK presents that token, with THIS process's service token, to
+ * `POST /auth/mcp/oauth/app-permissions`. Oxy answers only for a token whose
+ * resource this application registered, only about this application, and for
+ * the person who authorized the token — whichever account the connection is
+ * acting as. Same answer type, cache, `fresh` and errors as a session.
+ *
  * ## Caching, and how soon a revocation lands
  *
  * Answers are cached per (application, session, user) for
@@ -43,9 +63,10 @@
  *
  * Node only; reachable solely from `@oxy.so/core/server`.
  */
+import { createHash } from 'node:crypto';
 import { applicationRolesMeSchema, isApplicationPermissionKey } from '@oxy.so/contracts';
 import { logger } from '../logger/index.js';
-import { authorityErrorBody, CallerAuthorityCache, errorStatus, permissionSet, readCallerSession, } from './callerAuthority.js';
+import { authorityErrorBody, CallerAuthorityCache, errorStatus, permissionSet, isBearerToken, readCallerSession, } from './callerAuthority.js';
 /** Default cache lifetime of one answer. */
 export const APP_PERMISSIONS_CACHE_TTL_MS = 30000;
 /** The typed failure of {@link OxyAppPermissionsResolver.resolve} and the middleware. */
@@ -58,6 +79,9 @@ export class OxyAppPermissionError extends Error {
         this.cause = options.cause;
     }
 }
+function isMcpCallerRequest(source) {
+    return source.authInfo !== undefined;
+}
 /** The status the middleware answers an error with, under `deny`. */
 export function appPermissionErrorStatus(error, deny = 404) {
     switch (error.code) {
@@ -92,16 +116,48 @@ export class OxyAppPermissionsResolver {
         this.cache = new CallerAuthorityCache(host.ttlMs, (value, userId) => value.operatorId === userId);
     }
     /**
-     * What the person behind `req` holds. Throws {@link OxyAppPermissionError};
+     * What the person behind `source` holds. Throws {@link OxyAppPermissionError};
      * never answers "nothing held" for a failure.
      */
-    async resolve(req, options = {}) {
-        const caller = readCallerSession(req);
+    async resolve(source, options = {}) {
+        if (isMcpCallerRequest(source))
+            return this.resolveMcp(source, options);
+        const caller = readCallerSession(source);
         if (!caller.ok) {
             throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', caller.reason === 'service'
                 ? 'Application permissions are held by a person in a session; this request is authenticated by a service token'
                 : 'No verified user session on this request; mount middleware.auth() first');
         }
+        const appId = await this.applicationIdFor(options);
+        return this.cache.read([appId], caller.session, options.fresh === true, () => this.lookup(appId, caller.session.accessToken));
+    }
+    /**
+     * Forget cached answers: every one, or those about one person (matched as
+     * either the session's user or the resolved operator).
+     */
+    invalidate(filter = {}) {
+        this.cache.invalidate(filter);
+    }
+    /**
+     * An MCP call: Oxy names the application (the one that registered the token's
+     * resource) and the person (who authorized the token); the answer is refused
+     * unless the application is the one this server expects.
+     */
+    async resolveMcp(source, options) {
+        const token = source.authInfo?.token;
+        if (typeof token !== 'string' || !isBearerToken(token)) {
+            throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', 'No verified MCP access token on this call');
+        }
+        const appId = await this.applicationIdFor(options);
+        // The person is known only once Oxy answers; the token's digest keys the
+        // entry, so the bearer itself is never held as a cache key.
+        const cacheKey = {
+            sessionId: `mcp:${createHash('sha256').update(token).digest('base64url')}`,
+            userId: null,
+        };
+        return this.cache.read([appId], cacheKey, options.fresh === true, () => this.lookupMcp(appId, token));
+    }
+    async applicationIdFor(options) {
         let applicationId = options.applicationId ?? null;
         if (!applicationId) {
             try {
@@ -114,15 +170,43 @@ export class OxyAppPermissionsResolver {
         if (!applicationId) {
             throw new OxyAppPermissionError('APP_PERMISSION_NOT_CONFIGURED', 'No application id: set OxyServerConfig.applicationId, configure service auth, or pass { applicationId }');
         }
-        const appId = applicationId;
-        return this.cache.read([appId], caller.session, options.fresh === true, () => this.lookup(appId, caller.session.accessToken));
+        return applicationId;
     }
-    /**
-     * Forget cached answers: every one, or those about one person (matched as
-     * either the session's user or the resolved operator).
-     */
-    invalidate(filter = {}) {
-        this.cache.invalidate(filter);
+    async lookupMcp(applicationId, mcpAccessToken) {
+        let answer;
+        try {
+            answer = await this.host.fetchMcpAppPermissions(mcpAccessToken);
+        }
+        catch (error) {
+            const status = errorStatus(error);
+            if (status === 401 && error.code === 'invalid_grant') {
+                throw new OxyAppPermissionError('APP_PERMISSION_SESSION_REQUIRED', 'Oxy refused the MCP access token while resolving application permissions', { cause: error });
+            }
+            if (status === 403) {
+                throw new OxyAppPermissionError('APP_PERMISSION_DENIED', 'Oxy refused this application’s permissions for the MCP access token', { cause: error });
+            }
+            // Anything else — this service's own credential refused (401
+            // `invalid_client`), an Oxy without the route, a 5xx, a timeout — is not
+            // an answer about the person.
+            logger.warn('[oxy.appPermissions] Could not resolve application permissions for MCP', {
+                component: 'auth',
+                method: 'appPermissions',
+                applicationId,
+                status,
+            });
+            throw new OxyAppPermissionError('APP_PERMISSION_UNAVAILABLE', 'Could not resolve application permissions from Oxy', { cause: error });
+        }
+        const parsed = applicationRolesMeSchema.safeParse(answer);
+        if (!parsed.success) {
+            throw new OxyAppPermissionError('APP_PERMISSION_UNAVAILABLE', 'Oxy answered with a malformed permission set');
+        }
+        if (parsed.data.applicationId !== applicationId) {
+            // Oxy answers about the application behind this server's service token;
+            // a different one means the configured id names another application.
+            logger.error(`[oxy.appPermissions] Oxy answered for application ${parsed.data.applicationId}, not ${applicationId}; check OxyServerConfig.applicationId`, undefined, { component: 'auth', method: 'appPermissions' });
+            throw new OxyAppPermissionError('APP_PERMISSION_NOT_CONFIGURED', 'An MCP access token answers only for the application behind this server’s service token');
+        }
+        return heldPermissions(applicationId, parsed.data.userId, parsed.data.permissions);
     }
     async lookup(applicationId, accessToken) {
         let answer;

package/dist/types/HttpService.d.ts

@@ -22,6 +22,12 @@ export type AccessTokenProvider = () => string | null;
  * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
+/**
+ * Told that Oxy answered 401 to a bearer an {@link AnonymousAuthProvider}
+ * supplied; `true` when it dropped that bearer, so the request is sent once
+ * more with the provider's next one.
+ */
+export type AnonymousAuthRejectedHandler = (token: string) => boolean;
 declare const credentialGenerationBrand: unique symbol;
 /**
  * An opaque, immutable token for ONE installation of a bearer in a client.
@@ -241,6 +247,7 @@ export declare class HttpService {
     private authRefreshHandler;
     private accessTokenProvider;
     private anonymousAuthProvider;
+    private anonymousAuthRejected;
     private deviceSecretMintInFlight;
     /**
      * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -557,8 +564,12 @@ export declare class HttpService {
      * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
      * consulted only when there is no access token, and never for `skipAuth`
      * requests. `null` removes it.
+     *
+     * `onRejected` hears of a 401 to one of the provider's bearers; when it
+     * drops that bearer (`true`), the request is sent once more with the
+     * provider's next one — a rotated or revoked service token heals itself.
      */
-    setAnonymousAuthProvider(provider: AnonymousAuthProvider | null): void;
+    setAnonymousAuthProvider(provider: AnonymousAuthProvider | null, onRejected?: AnonymousAuthRejectedHandler): void;
     clearTokens(): void;
     /**
      * Subscribe to access-token changes on this instance.

package/dist/types/server/OxyServer.d.ts

@@ -6,7 +6,7 @@ import type { HttpMethod } from '../client/context';
 import type { RequestOptions, ResponsePayload } from '../HttpService';
 import { type WorkloadCredentialProvider } from './workloadIdentity';
 import { type OxyAccountEvent, type OxyAccountEventFeedPage, type OxyMiddleware, type ServiceActingAsVerification, type VerifyAccountEventOptions } from './middleware';
-import { type AppPermissionsOptions, type AppPermissionsRequest, type OxyAppPermissions } from './appPermissions';
+import { type AppPermissionsOptions, type AppPermissionsSource, type OxyAppPermissions } from './appPermissions';
 import { ServerAccountsApi, ServerAppsApi, ServerAgencyApi, ServerAssetsApi, ServerLinkedAccountsApi, ServerNotificationsApi, ServerReputationApi } from './namespaces';
 import { type CallerAccessOptions, type OxyAccountAccess, type OxyApplicationAccess } from './callerAccess';
 import type { OxyCallerRequest } from './callerAuthority';
@@ -295,12 +295,23 @@ export declare class OxyServer extends OxyServices {
         requesterContext?: string;
         serviceTokenScopes?: string[];
     }): Promise<ResponsePayload<T>>;
+    /**
+     * Drop every cached entry that holds `token` (and is not minting): `true`
+     * when one did, so the next mint asks Oxy again.
+     */
+    private forgetServiceToken;
     /**
      * Which of this application's own declared permissions the PERSON behind
      * `req` holds (application roles, `docs/auth/application-roles.md`). `req`
      * must have passed `middleware.auth()`: the answer is read from Oxy with the
      * request's own verified bearer, for the human operator of its session.
      *
+     * An MCP tool call is asked the same way: pass its `extra`
+     * (`CatalogInvocationContext.request`), whose `authInfo.token` is the access
+     * token `@oxy.so/mcp` introspected. Oxy answers, for the person who
+     * authorized that token, only about the application that registered its
+     * resource — this server's own (`APP_PERMISSION_NOT_CONFIGURED` otherwise).
+     *
      * Cached per session for `appPermissionsCacheTtlMs` (30 s); pass
      * `{ fresh: true }` before a write. Throws `OxyAppPermissionError` — no
      * session (`APP_PERMISSION_SESSION_REQUIRED`, also for any service-token
@@ -308,7 +319,7 @@ export declare class OxyServer extends OxyServices {
      * application id (`APP_PERMISSION_NOT_CONFIGURED`) — and never answers
      * "nothing held" for a failure.
      */
-    appPermissionsFor(req: AppPermissionsRequest, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
+    appPermissionsFor(req: AppPermissionsSource, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
     /**
      * Drop cached caller-authority answers — application permissions and
      * account / application access — all of them, or one person's (as the
@@ -383,6 +394,7 @@ export declare class OxyServer extends OxyServices {
     }): void;
     private defaultApplicationId;
     private fetchRolesMe;
+    private fetchMcpAppPermissions;
     /**
      * Resolve authority live by default. Explicit read-only reuse lasts at most
      * 60s positive / 10s negative, anchored to request start; errors never cache.

package/dist/types/server/appPermissions.d.ts

@@ -2,10 +2,13 @@
  * Application roles, from the application's side: which of THIS application's
  * declared permissions does the person behind a request hold?
  *
- * Oxy decides who holds an app's operator powers (`docs/auth/application-roles.md`).
- * An app declares its keys (`payments.operate`, …) in the Console, its owners
- * grant them to people, and its backend asks — so no app keeps a
- * `*_OPERATOR_OXY_USER_IDS` allow-list in its environment.
+ * Oxy decides who holds an app's operator powers (`docs/auth/application-roles.md`),
+ * and the backend asks — so no app keeps a `*_OPERATOR_OXY_USER_IDS` allow-list
+ * in its environment. One of Oxy's own applications declares its keys
+ * (`payments.operate`, …) in Oxy's first-party registry, each held by roles of
+ * the owning organization (ADR 0056); a third-party app declares them in the
+ * Console and its owners grant them to people. The answer has the same shape
+ * either way.
  *
  * ```ts
  * const oxy = new OxyServer({ baseURL: 'https://api.oxy.so', applicationId: process.env.OXY_APPLICATION_ID });
@@ -31,6 +34,23 @@
  * `X-Oxy-User-Id`, is refused — an operator power is exercised by a person in
  * a session, never through delegation.
  *
+ * ## An MCP tool call
+ *
+ * An MCP request carries no session: its bearer is an access token Oxy issued
+ * for this app's MCP resource, which `@oxy.so/mcp`'s transport introspected
+ * live before the tool ran. Pass the call's `extra` (`context.request` in a
+ * catalog handler or `authorize`) the same way:
+ *
+ * ```ts
+ * const held = await oxy.appPermissionsFor(context.request, { fresh: true });
+ * ```
+ *
+ * The SDK presents that token, with THIS process's service token, to
+ * `POST /auth/mcp/oauth/app-permissions`. Oxy answers only for a token whose
+ * resource this application registered, only about this application, and for
+ * the person who authorized the token — whichever account the connection is
+ * acting as. Same answer type, cache, `fresh` and errors as a session.
+ *
  * ## Caching, and how soon a revocation lands
  *
  * Answers are cached per (application, session, user) for
@@ -51,7 +71,8 @@ export type OxyAppPermissionDenyStatus = 403 | 404;
 /**
  * - `APP_PERMISSION_DENIED` — a person in a session, without the permission.
  * - `APP_PERMISSION_SESSION_REQUIRED` — no user session on the request: anonymous,
- *   or authenticated by a service token (delegated or not).
+ *   or authenticated by a service token (delegated or not); for an MCP call, no
+ *   access token, or one Oxy refused (revoked, expired, another app's resource).
  * - `APP_PERMISSION_UNAVAILABLE` — Oxy could not be asked or gave no usable
  *   answer. Fails closed; answered 503.
  * - `APP_PERMISSION_NOT_CONFIGURED` — this server knows no application id, or
@@ -77,6 +98,8 @@ export interface OxyAppPermissions {
      * The HUMAN Oxy resolved from the session — record THIS as the actor in an
      * audit log. It differs from `req.userId` when a person acts as an
      * organization (the session speaks as the org; the operator is the person).
+     * For an MCP call it is the person who authorized the token, which may differ
+     * from the account the connection is acting as.
      */
     readonly operatorId: string;
     /** The held keys, sorted. */
@@ -86,7 +109,11 @@ export interface OxyAppPermissions {
 export interface AppPermissionsOptions {
     /** Skip the cache and ask Oxy (the answer still refreshes the cache). Use on writes. */
     fresh?: boolean;
-    /** Ask about another application than the server's configured one. */
+    /**
+     * Ask about another application than the server's configured one. Not for an
+     * MCP call: Oxy answers it only about the application that registered the
+     * token's resource, and any other id is `APP_PERMISSION_NOT_CONFIGURED`.
+     */
     applicationId?: string;
 }
 export interface RequireAppPermissionOptions extends AppPermissionsOptions {
@@ -109,6 +136,18 @@ export interface RequireAppPermissionOptions extends AppPermissionsOptions {
 export interface AppPermissionsRequest extends OxyCallerRequest {
     oxyAppPermissions?: OxyAppPermissions;
 }
+/**
+ * An MCP tool call: the `extra` (`RequestHandlerExtra`) an MCP handler receives,
+ * whose `authInfo` `@oxy.so/mcp`'s transport set after Oxy introspected the
+ * access token live. `CatalogInvocationContext.request` is one.
+ */
+export interface OxyMcpCallerRequest {
+    readonly authInfo?: {
+        readonly token: string;
+    };
+}
+/** What `appPermissionsFor` reads: a request after `middleware.auth()`, or an MCP tool call. */
+export type AppPermissionsSource = AppPermissionsRequest | OxyMcpCallerRequest;
 /** The status the middleware answers an error with, under `deny`. */
 export declare function appPermissionErrorStatus(error: OxyAppPermissionError, deny?: OxyAppPermissionDenyStatus): number;
 /** The response body for a status: the API error envelope (`docs/api-conventions.md`). */
@@ -119,6 +158,11 @@ export declare function assertApplicationPermissionKey(permission: unknown): ass
 export interface AppPermissionsHost {
     /** `GET /applications/:appId/roles/me` with this bearer, uncached. Rejects with the API error. */
     fetchRolesMe(applicationId: string, accessToken: string): Promise<unknown>;
+    /**
+     * `POST /auth/mcp/oauth/app-permissions` with this MCP access token, as this
+     * server's service, uncached. Rejects with the API error.
+     */
+    fetchMcpAppPermissions(mcpAccessToken: string): Promise<unknown>;
     /** The configured application id, or the one this server's service token names. */
     defaultApplicationId(): Promise<string | null>;
     readonly ttlMs: number;
@@ -132,10 +176,10 @@ export declare class OxyAppPermissionsResolver {
     private readonly cache;
     constructor(host: AppPermissionsHost);
     /**
-     * What the person behind `req` holds. Throws {@link OxyAppPermissionError};
+     * What the person behind `source` holds. Throws {@link OxyAppPermissionError};
      * never answers "nothing held" for a failure.
      */
-    resolve(req: AppPermissionsRequest, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
+    resolve(source: AppPermissionsSource, options?: AppPermissionsOptions): Promise<OxyAppPermissions>;
     /**
      * Forget cached answers: every one, or those about one person (matched as
      * either the session's user or the resolved operator).
@@ -143,5 +187,13 @@ export declare class OxyAppPermissionsResolver {
     invalidate(filter?: {
         userId?: string;
     }): void;
+    /**
+     * An MCP call: Oxy names the application (the one that registered the token's
+     * resource) and the person (who authorized the token); the answer is refused
+     * unless the application is the one this server expects.
+     */
+    private resolveMcp;
+    private applicationIdFor;
+    private lookupMcp;
     private lookup;
 }

package/dist/types/server/callerAuthority.d.ts

@@ -36,6 +36,16 @@ export interface OxyCallerSession {
     readonly sessionId: string;
     readonly accessToken: string;
 }
+/**
+ * Whose answer a cache entry is: the session (or other credential) it was read
+ * with, and the person, when known before asking. A caller whose person only
+ * Oxy's answer names (an MCP access token) passes `userId: null`; the reader's
+ * `isAbout` still matches the answer for {@link CallerAuthorityCache.invalidate}.
+ */
+export interface OxyCallerCacheKey {
+    readonly sessionId: string;
+    readonly userId: string | null;
+}
 /**
  * The person behind `req`, or why there is none: `service` for a request
  * authenticated by a service token (delegated or not — its bearer is the
@@ -113,7 +123,7 @@ export declare class CallerAuthorityCache<T> {
      *   resolved operator), for {@link invalidate}.
      */
     constructor(ttlMs: number, isAbout?: (value: T, userId: string) => boolean);
-    read(resourceKey: readonly string[], session: OxyCallerSession, fresh: boolean, lookup: () => Promise<T>): Promise<T>;
+    read(resourceKey: readonly string[], session: OxyCallerCacheKey, fresh: boolean, lookup: () => Promise<T>): Promise<T>;
     /** Forget every answer, or those about one person. */
     invalidate(filter?: {
         userId?: string;

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

@@ -49,7 +49,7 @@ export type { AliaMachineCredentialIntrospection, OxyAliaMachinePrincipal, OxyAl
 export type { CapabilityTicketGrant, CapabilityTicketIntrospection, CreateExecutionAuthorizationInput, ServiceCallOptions, ServiceCapabilityCatalog, ServiceUploadBody, ServiceUploadDescription, } from './namespaces';
 export { OxyAccountEventError, OXY_ACCOUNT_DELETED_EVENT_URI } from './middleware';
 export { APP_PERMISSIONS_CACHE_TTL_MS, OxyAppPermissionError, appPermissionErrorStatus, } from './appPermissions';
-export type { AppPermissionsOptions, OxyAppPermissionDenyStatus, OxyAppPermissionErrorCode, OxyAppPermissions, RequireAppPermissionOptions, } from './appPermissions';
+export type { AppPermissionsOptions, AppPermissionsSource, OxyMcpCallerRequest, OxyAppPermissionDenyStatus, OxyAppPermissionErrorCode, OxyAppPermissions, RequireAppPermissionOptions, } from './appPermissions';
 export type { AuthMiddlewareOptions, OxyAccountEvent, OxyAccountEventFeedItem, OxyAccountEventFeedPage, OxyMiddleware, RequireAccessOptions, ServiceActingAsVerification, ServiceApp, VerifyAccountEventOptions, } from './middleware';
 export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyActor, getOxyAuthRefusal, getOxyBillingPrincipal, getOxyDelegatedUserId, getOxyRequestAttribution, getOxyUserId, getRequiredOxyBillingPrincipal, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth';
 export type { OxyAuthHost } from './auth';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/core",
-  "version": "7.19.0",
+  "version": "7.20.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -181,7 +181,7 @@
   "dependencies": {
     "@noble/ciphers": "^2.4.0",
     "@noble/hashes": "^2.4.0",
-    "@oxy.so/contracts": "6.5.0",
+    "@oxy.so/contracts": "6.6.0",
     "@oxy.so/protocol": "^1.6.1",
     "@oxy.so/telemetry": "^2.1.0",
     "@scure/bip39": "^2.4.0",

package/src/HttpService.ts

@@ -55,6 +55,12 @@ export type AccessTokenProvider = () => string | null;
  * — `null` to send it anonymous. See {@link HttpService.setAnonymousAuthProvider}.
  */
 export type AnonymousAuthProvider = () => Promise<string | null>;
+/**
+ * Told that Oxy answered 401 to a bearer an {@link AnonymousAuthProvider}
+ * supplied; `true` when it dropped that bearer, so the request is sent once
+ * more with the provider's next one.
+ */
+export type AnonymousAuthRejectedHandler = (token: string) => boolean;
 
 declare const credentialGenerationBrand: unique symbol;
 /**
@@ -604,6 +610,7 @@ export class HttpService {
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
   private anonymousAuthProvider: AnonymousAuthProvider | null = null;
+  private anonymousAuthRejected: AnonymousAuthRejectedHandler | null = null;
   private deviceSecretMintInFlight: Promise<DeviceSecretMintOutcome> | null = null;
   /**
    * Bumped by every {@link endSession}. A re-mint captures it before its first
@@ -1145,6 +1152,33 @@ export class HttpService {
 
         // Handle response
         if (!response.ok) {
+          // A 401 to the bearer the anonymous provider supplied (a backend's
+          // own service token, no user session): once its owner has dropped
+          // it, send the request once more with the provider's next one. A
+          // 401 means the request never ran, so this is safe for any method.
+          if (
+            response.status === 401 &&
+            !contextToken &&
+            usesSessionAuth &&
+            !config.expectedCredentialGeneration &&
+            !config._isAuthRetry &&
+            authHeader?.startsWith('Bearer ') &&
+            this.anonymousAuthRejected?.(authHeader.slice('Bearer '.length))
+          ) {
+            void discardResponseBody(response);
+            if (domain.aborted) throw createCancelledError();
+            // Same reasons as the session retry below: no dedupe (the original
+            // is still in flight under its key), no queue slot (this attempt
+            // holds one).
+            return this.request<T>({
+              ...config,
+              _isAuthRetry: true,
+              retry: false,
+              deduplicate: false,
+              bypassQueue: true,
+              signal: domain,
+            });
+          }
           // On 401, delegate to the installed auth refresh handler and retry
           // once before giving up. HttpService deliberately does not know any
           // session routes; the refresh handler owns session rotation.
@@ -2319,9 +2353,17 @@ export class HttpService {
    * `OxyConfig.serviceIdentity`). A user session always wins: the provider is
    * consulted only when there is no access token, and never for `skipAuth`
    * requests. `null` removes it.
+   *
+   * `onRejected` hears of a 401 to one of the provider's bearers; when it
+   * drops that bearer (`true`), the request is sent once more with the
+   * provider's next one — a rotated or revoked service token heals itself.
    */
-  setAnonymousAuthProvider(provider: AnonymousAuthProvider | null): void {
+  setAnonymousAuthProvider(
+    provider: AnonymousAuthProvider | null,
+    onRejected?: AnonymousAuthRejectedHandler,
+  ): void {
     this.anonymousAuthProvider = provider;
+    this.anonymousAuthRejected = provider ? (onRejected ?? null) : null;
   }
 
   clearTokens(): void {

package/src/server/OxyServer.ts

@@ -66,7 +66,7 @@ import { OxyServices, type OxyConfig } from '../OxyServices';
 import { HttpService } from '../HttpService';
 import { createAuthenticatedFetch } from '../authenticatedFetch';
 import { awaitRequestSignal } from '../utils/requestSignal';
-import { createCancelledError } from '../utils/errorUtils';
+import { createCancelledError, extractErrorStatus } from '../utils/errorUtils';
 import type { HttpMethod, ServiceLane } from '../client/context';
 import type { RequestOptions, ResponsePayload } from '../HttpService';
 import { logger } from '../logger';
@@ -94,7 +94,7 @@ import {
   APP_PERMISSIONS_CACHE_TTL_MS,
   OxyAppPermissionsResolver,
   type AppPermissionsOptions,
-  type AppPermissionsRequest,
+  type AppPermissionsSource,
   type OxyAppPermissions,
 } from './appPermissions';
 import {
@@ -365,7 +365,10 @@ export class OxyServer extends OxyServices {
     };
     this.context.service = serviceLane;
     if (config.serviceIdentity === 'when-anonymous') {
-      this.http.setAnonymousAuthProvider(() => this.serviceTokenForAnonymousRequest());
+      this.http.setAnonymousAuthProvider(
+        () => this.serviceTokenForAnonymousRequest(),
+        (token) => this.forgetServiceToken(token),
+      );
     }
     const ttl = config.appPermissionsCacheTtlMs ?? APP_PERMISSIONS_CACHE_TTL_MS;
     if (!Number.isFinite(ttl) || ttl < 0) {
@@ -381,6 +384,7 @@ export class OxyServer extends OxyServices {
       ttlMs: ttl,
       defaultApplicationId: () => this.defaultApplicationId(),
       fetchRolesMe: (applicationId, accessToken) => this.fetchRolesMe(applicationId, accessToken),
+      fetchMcpAppPermissions: (mcpAccessToken) => this.fetchMcpAppPermissions(mcpAccessToken),
     });
     this.callerAccess = new OxyCallerAccessResolver({
       ttlMs: ttl,
@@ -873,8 +877,7 @@ export class OxyServer extends OxyServices {
       serviceTokenScopes,
       ...rest
     } = options;
-    const token = await this.platformServiceToken({ scopes: serviceTokenScopes });
-    const merged: Record<string, string> = { ...headers, Authorization: `Bearer ${token}` };
+    const merged: Record<string, string> = { ...headers };
     if (actAs) merged['X-Oxy-User-Id'] = actAs;
     if (
       [requesterToken, taskId, capabilityTicket, requesterContext].filter(
@@ -886,16 +889,52 @@ export class OxyServer extends OxyServices {
     if (taskId) merged['X-Oxy-Task-Id'] = taskId;
     if (capabilityTicket) merged['X-Oxy-Capability-Ticket'] = capabilityTicket;
     if (requesterContext) merged['X-Oxy-Requester-Context'] = requesterContext;
-    return this.request<T>(method, target.href, data, {
-      cache: false,
-      ...rest,
-      ...([requesterToken, taskId, capabilityTicket, requesterContext].some(
-        (proof) => proof !== undefined,
-      )
-        ? { cache: false, deduplicate: false, retry: false }
-        : {}),
-      headers: merged,
-    });
+    const send = (token: string) =>
+      this.request<T>(method, target.href, data, {
+        cache: false,
+        ...rest,
+        ...([requesterToken, taskId, capabilityTicket, requesterContext].some(
+          (proof) => proof !== undefined,
+        )
+          ? { cache: false, deduplicate: false, retry: false }
+          : {}),
+        headers: { ...merged, Authorization: `Bearer ${token}` },
+      });
+    const token = await this.platformServiceToken({ scopes: serviceTokenScopes });
+    try {
+      return await send(token);
+    } catch (error) {
+      // A 401 refused the request before it ran, so sending it again is safe
+      // whatever its method. A cached token Oxy no longer accepts (keys
+      // rotated, credential revoked) is dropped and the request sent once
+      // more with a freshly minted one: once, never after an abort, and only
+      // when the refused token was this server's cached one.
+      if (
+        extractErrorStatus(error) !== 401 ||
+        rest.signal?.aborted ||
+        !this.forgetServiceToken(token)
+      ) {
+        throw error;
+      }
+      const fresh = await this.platformServiceToken({ scopes: serviceTokenScopes });
+      if (fresh === token) throw error;
+      return send(fresh);
+    }
+  }
+
+  /**
+   * Drop every cached entry that holds `token` (and is not minting): `true`
+   * when one did, so the next mint asks Oxy again.
+   */
+  private forgetServiceToken(token: string): boolean {
+    let forgot = false;
+    for (const [cacheKey, entry] of this.serviceTokens) {
+      if (entry.token === token && !entry.pending) {
+        this.serviceTokens.delete(cacheKey);
+        forgot = true;
+      }
+    }
+    return forgot;
   }
 
   // ── Application roles ────────────────────────────────────────────────────
@@ -906,6 +945,12 @@ export class OxyServer extends OxyServices {
    * must have passed `middleware.auth()`: the answer is read from Oxy with the
    * request's own verified bearer, for the human operator of its session.
    *
+   * An MCP tool call is asked the same way: pass its `extra`
+   * (`CatalogInvocationContext.request`), whose `authInfo.token` is the access
+   * token `@oxy.so/mcp` introspected. Oxy answers, for the person who
+   * authorized that token, only about the application that registered its
+   * resource — this server's own (`APP_PERMISSION_NOT_CONFIGURED` otherwise).
+   *
    * Cached per session for `appPermissionsCacheTtlMs` (30 s); pass
    * `{ fresh: true }` before a write. Throws `OxyAppPermissionError` — no
    * session (`APP_PERMISSION_SESSION_REQUIRED`, also for any service-token
@@ -914,7 +959,7 @@ export class OxyServer extends OxyServices {
    * "nothing held" for a failure.
    */
   appPermissionsFor(
-    req: AppPermissionsRequest,
+    req: AppPermissionsSource,
     options: AppPermissionsOptions = {},
   ): Promise<OxyAppPermissions> {
     return this.appPermissions.resolve(req, options);
@@ -1047,6 +1092,15 @@ export class OxyServer extends OxyServices {
     );
   }
 
+  private fetchMcpAppPermissions(mcpAccessToken: string): Promise<unknown> {
+    return this.serviceRequest<unknown>(
+      'POST',
+      '/auth/mcp/oauth/app-permissions',
+      { token: mcpAccessToken },
+      { cache: false, deduplicate: false, retry: false },
+    );
+  }
+
   // ── Delegation and account events ────────────────────────────────────────
 
   /**