Merge PR #1818: surface MCP OAuth reauthorization during catalog discovery

Author: RhysSullivan

.changeset/mcp-oauth-refresh-reauthorization.md

@@ -0,0 +1,12 @@
+---
+"@executor-js/sdk": patch
+"@executor-js/plugin-mcp": patch
+---
+
+**Rejected MCP OAuth grants now request reconnect without registering a disposable client**
+
+Remote MCP catalog discovery used the MCP SDK's interactive OAuth fallback when an upstream rejected Executor's stored bearer with `401`. A background refresh cannot finish that browser authorization, but the SDK first fetched OAuth metadata and dynamically registered another client. Executor then preserved the old catalog under a generic degraded health verdict, so clients saw zero or stale tools without a reliable reconnect signal.
+
+Executor now stops at the authenticated HTTP boundary for OAuth-backed MCP transports. A rejected stored bearer becomes a structured reauthorization result before OAuth discovery or Dynamic Client Registration runs. Catalog refresh still preserves the last authoritative tools, but records the connection as expired with a reconnect-required detail so the UI and API can direct the user through authorization again.
+
+API-key and unauthenticated MCP transports keep their existing `401` behavior, and ordinary incomplete discovery results remain degraded.

packages/core/sdk/src/executor.test.ts

@@ -125,11 +125,20 @@ const demoPlugin = definePlugin(() => ({
 const diagnosticsPlugin = definePlugin(() => ({
   id: "diagnostics" as const,
   storage: () => ({}),
-  resolveTools: () =>
+  resolveTools: ({ connection }) =>
     Effect.succeed({
       tools: [],
       incomplete: true,
       incompleteReason: "Schema introspection was rejected",
+      ...(String(connection.integration) === "diagnostics_expired"
+        ? {
+            health: {
+              status: "expired" as const,
+              checkedAt: Date.now(),
+              detail: "Reconnect the upstream OAuth grant",
+            },
+          }
+        : {}),
     }),
   extension: (ctx) => ({
     seed: () =>
@@ -138,6 +147,12 @@ const diagnosticsPlugin = definePlugin(() => ({
         description: "Diagnostics",
         config: {},
       }),
+    seedExpired: () =>
+      ctx.core.integrations.register({
+        slug: IntegrationSlug.make("diagnostics_expired"),
+        description: "Expired diagnostics",
+        config: {},
+      }),
   }),
 }))();
 
@@ -470,6 +485,44 @@ describe("createExecutor", () => {
     }),
   );
 
+  it.effect("preserves actionable health from an incomplete tool catalog", () =>
+    Effect.gen(function* () {
+      const executor = yield* makeTestExecutor({
+        plugins: [memoryCredentialsPlugin(), diagnosticsPlugin] as const,
+        coreTools: {},
+      });
+      yield* executor.diagnostics.seedExpired();
+
+      yield* executor.execute(
+        ToolAddress.make("executor.coreTools.connections.create"),
+        {
+          owner: "org",
+          name: "main",
+          integration: "diagnostics_expired",
+          template: "none",
+        },
+        { onElicitation: "accept-all" },
+      );
+
+      const refreshed = yield* executor.execute(
+        ToolAddress.make("executor.coreTools.connections.refresh"),
+        {
+          owner: "org",
+          name: "main",
+          integration: "diagnostics_expired",
+        },
+        { onElicitation: "accept-all" },
+      );
+      expect(refreshed).toMatchObject({
+        tools: [],
+        lastHealth: {
+          status: "expired",
+          detail: "Reconnect the upstream OAuth grant",
+        },
+      });
+    }),
+  );
+
   it.effect("hands pasted credential entry to the web UI", () =>
     Effect.gen(function* () {
       const executor = yield* makeTestExecutor({

packages/core/sdk/src/executor.ts

@@ -3229,8 +3229,10 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
         // clears it, and reconnect re-syncs tools anyway). Read fresh, since
         // the recorder wrote AFTER this sync's row was loaded. Keep stamping
         // the sync time so the stale-catalog check does not re-attempt this
-        // connection on every read.
-        const stampSyncedWithHealth = (reason: string) =>
+        // connection on every read. A plugin-supplied actionable `health`
+        // (e.g. the MCP plugin's reauthorization-required verdict) replaces
+        // the generic tool-sync verdict, never a recorded dead grant's.
+        const stampSyncedWithHealth = (reason: string, health?: HealthCheckResult) =>
           findConnectionRow(ref).pipe(
             Effect.flatMap((fresh) =>
               core.updateMany("connection", {
@@ -3241,7 +3243,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
                     ? { tools_synced_at: Date.now() }
                     : {
                         tools_synced_at: Date.now(),
-                        last_health: toolSyncHealth(reason),
+                        last_health: health ?? toolSyncHealth(reason),
                         updated_at: new Date(),
                       },
               }),
@@ -3310,7 +3312,7 @@ export const createExecutor = <const TPlugins extends readonly AnyPlugin[] = rea
           // server isn't re-dialed on every read; the freshness TTL re-attempts
           // later.
           const reason = syncHealthReason(result);
-          yield* stampSyncedWithHealth(reason);
+          yield* stampSyncedWithHealth(reason, result.health);
           yield* Effect.logWarning("executor tool sync preserved catalog", {
             reason,
             integration: String(ref.integration),

packages/core/sdk/src/plugin.ts

@@ -367,6 +367,10 @@ export interface ResolveToolsResult {
   /** Human-readable reason for an incomplete listing. Persisted by core when it
    *  preserves the prior catalog so operators can see why data is stale. */
   readonly incompleteReason?: string;
+  /** An actionable connection-health outcome discovered while enumerating the
+   *  catalog. Core persists it while preserving the prior non-authoritative
+   *  catalog. Omit for ordinary transient discovery failures. */
+  readonly health?: HealthCheckResult;
 }
 
 export interface ProjectToolSchemaInput<TStore = unknown> {

packages/plugins/mcp/src/sdk/connection.ts

@@ -49,6 +49,10 @@ export type RemoteConnectorInput = Omit<
   readonly headers?: Record<string, string>;
   readonly queryParams?: Record<string, string>;
   readonly authProvider?: OAuthClientProvider;
+  /** This provider only replays a resolved bearer. A 401 cannot be recovered
+   *  inside the MCP SDK and must return to core as reconnect-required before
+   *  the SDK attempts discovery or Dynamic Client Registration. */
+  readonly staticOAuthBearer?: boolean;
   readonly httpClientLayer?: Layer.Layer<HttpClient.HttpClient>;
 };
 
@@ -153,6 +157,18 @@ const nestedMcpHttpTransportError = (cause: unknown): Option.Option<McpHttpTrans
   return Option.none();
 };
 
+const hasNestedOAuthReauthorization = (cause: unknown): boolean => {
+  let current: unknown = cause;
+  for (let depth = 0; depth < 8; depth += 1) {
+    if (Predicate.isTagged(current, "McpOAuthReauthorizationRequired")) return true;
+    const decodedCause = decodeExternalTransportCause(current);
+    if (Option.isNone(decodedCause)) return false;
+    current = decodedCause.value.cause ?? decodedCause.value.data?.cause;
+    if (current === undefined) return false;
+  }
+  return false;
+};
+
 const externalTransportCodes = (cause: unknown): ReadonlySet<string> => {
   const codes = new Set<string>();
   let current: unknown = cause;
@@ -230,6 +246,7 @@ const awaitAbort = (signal: AbortSignal): Effect.Effect<void> =>
 
 const fetchFromHttpClientLayer = (
   httpClientLayer: Layer.Layer<HttpClient.HttpClient>,
+  staticOAuthBearer: boolean,
 ): FetchLike => {
   const execute: FetchLike = async (url, init) => {
     const headers = headersFrom(init?.headers);
@@ -262,6 +279,10 @@ const fetchFromHttpClientLayer = (
         headers: responseHeaders,
       });
     }).pipe(Effect.mapError(normalizeHttpClientFailure), Effect.provide(httpClientLayer));
+    // Executor resolves and refreshes OAuth credentials before constructing
+    // this transport. If that stored bearer is rejected, the MCP SDK cannot
+    // complete its interactive fallback in a catalog refresh and would perform
+    // avoidable DCR first. Stop at the authenticated HTTP boundary instead.
     // A 403 carrying an RFC 6750 insufficient_scope challenge is intercepted
     // HERE, below the SDK: with an authProvider the SDK would consume the
     // challenge and re-run auth ("upscoping"), which our static-token
@@ -271,6 +292,12 @@ const fetchFromHttpClientLayer = (
     // consumes promise rejections) so it reaches the invoke/connect catch
     // sites verbatim.
     const promise = Effect.runPromise(effect).then((response) => {
+      if (staticOAuthBearer && response.status === 401) {
+        // oxlint-disable-next-line executor/no-try-catch-or-throw -- boundary: Fetch-compatible adapter can only signal through a rejected promise
+        throw new McpOAuthReauthorizationRequired({
+          message: "MCP OAuth re-authorization required",
+        });
+      }
       if (response.status === 403) {
         const challenge = response.headers.get("www-authenticate");
         if (
@@ -335,7 +362,7 @@ const connectionFailure = (
   message: string,
   cause: unknown,
 ): McpConnectionError | McpOAuthReauthorizationRequired => {
-  if (Predicate.isTagged(cause, "McpOAuthReauthorizationRequired")) {
+  if (hasNestedOAuthReauthorization(cause)) {
     return new McpOAuthReauthorizationRequired({ message: "MCP OAuth re-authorization required" });
   }
   if (Predicate.isTagged(cause, "McpInsufficientScopeError")) {
@@ -487,7 +514,9 @@ export const createMcpConnector = (input: ConnectorInput): McpConnector => {
   const headers = input.headers ?? {};
   const remoteTransport = input.remoteTransport ?? "auto";
   const requestInit = Object.keys(headers).length > 0 ? { headers } : undefined;
-  const fetch = input.httpClientLayer ? fetchFromHttpClientLayer(input.httpClientLayer) : undefined;
+  const fetch = input.httpClientLayer
+    ? fetchFromHttpClientLayer(input.httpClientLayer, input.staticOAuthBearer === true)
+    : undefined;
 
   const endpoint = buildEndpointUrl(input.endpoint, input.queryParams ?? {});
 

packages/plugins/mcp/src/sdk/discover.ts

@@ -114,10 +114,15 @@ export const discoverTools = (
             const httpStatus = Predicate.isTagged(failure, "McpConnectionError")
               ? failure.httpStatus
               : undefined;
+            const reauthorizationRequired = Predicate.isTagged(
+              failure,
+              "McpOAuthReauthorizationRequired",
+            );
             return new McpToolDiscoveryError({
               stage: "connect",
               message: `Failed connecting to MCP server: ${failure.message}`,
               ...(httpStatus !== undefined ? { httpStatus } : {}),
+              ...(reauthorizationRequired ? { reauthorizationRequired: true } : {}),
             });
           }),
         ),

packages/plugins/mcp/src/sdk/errors.ts

@@ -42,6 +42,10 @@ export class McpToolDiscoveryError extends Schema.TaggedErrorClass<McpToolDiscov
     message: Schema.String,
     /** HTTP status from the underlying connect failure, when known. */
     httpStatus: Schema.optional(Schema.Number),
+    /** The MCP OAuth provider reached the interactive authorization boundary.
+     *  Catalog callers use this structural signal to request reconnect without
+     *  parsing or exposing an upstream error message. */
+    reauthorizationRequired: Schema.optional(Schema.Boolean),
   },
   { httpApiStatus: 400 },
 ) {}

packages/plugins/mcp/src/sdk/plugin.test.ts

@@ -103,6 +103,45 @@ const serveCallToolServer = (callTool: CallToolResponder) =>
     }),
   );
 
+const rejectedOAuthDiscoveryLayer = (endpoint: string) => {
+  const issuer = new URL(endpoint).origin;
+  const requests: string[] = [];
+  const layer = Layer.succeed(HttpClient.HttpClient)(
+    HttpClient.make((request: HttpClientRequest.HttpClientRequest) => {
+      requests.push(request.url);
+      const url = new URL(request.url);
+      const response =
+        request.url === endpoint
+          ? new Response("", { status: 401 })
+          : url.pathname === "/.well-known/oauth-protected-resource/mcp"
+            ? Response.json({ resource: endpoint, authorization_servers: [issuer] })
+            : url.pathname === "/.well-known/oauth-authorization-server"
+              ? Response.json({
+                  issuer,
+                  authorization_endpoint: `${issuer}/authorize`,
+                  token_endpoint: `${issuer}/token`,
+                  registration_endpoint: `${issuer}/register`,
+                  response_types_supported: ["code"],
+                  code_challenge_methods_supported: ["S256"],
+                })
+              : url.pathname === "/register"
+                ? Response.json(
+                    {
+                      client_id: "replacement-client",
+                      redirect_uris: ["http://localhost/oauth/callback"],
+                      grant_types: ["authorization_code", "refresh_token"],
+                      response_types: ["code"],
+                      token_endpoint_auth_method: "none",
+                    },
+                    { status: 201 },
+                  )
+                : new Response("unexpected request", { status: 500 });
+      return Effect.succeed(HttpClientResponse.fromWeb(request, response));
+    }),
+  );
+  return { layer, requests };
+};
+
 // `tools/call` responders. Both embed a "do-not-leak" sentinel the assertions
 // confirm never reaches the caller-facing failure.
 const httpStatusCallTool =
@@ -335,6 +374,44 @@ describe("joinToolPath", () => {
 // ---------------------------------------------------------------------------
 
 describe("mcpPlugin", () => {
+  it.effect("surfaces OAuth reauthorization from resolveTools as expired health", () =>
+    Effect.gen(function* () {
+      const endpoint = "https://mcp.example.test/mcp";
+      const plugin = mcpPlugin();
+      const ledger = rejectedOAuthDiscoveryLayer(endpoint);
+      const result = yield* plugin.resolveTools!({
+        config: {
+          transport: "remote",
+          endpoint,
+          remoteTransport: "streamable-http",
+          authenticationTemplate: [{ slug: "oauth2", kind: "oauth2" }],
+        },
+        connection: {
+          owner: "org",
+          integration: IntegrationSlug.make("oauth_mcp"),
+          name: ConnectionName.make("main"),
+        },
+        template: AuthTemplateSlug.make("oauth2"),
+        getValues: () => Effect.succeed({ token: "rejected-token" }),
+        getValue: () => Effect.succeed("rejected-token"),
+        httpClientLayer: ledger.layer,
+        ctx: null as never,
+        integration: null as never,
+        storage: {},
+      });
+
+      expect(result).toMatchObject({
+        tools: [],
+        incomplete: true,
+        health: {
+          status: "expired",
+          detail: expect.stringContaining("reauthorization"),
+        },
+      });
+      expect(ledger.requests.filter((url) => new URL(url).pathname === "/register")).toEqual([]);
+    }),
+  );
+
   it.effect("creates executor with mcp plugin", () =>
     Effect.gen(function* () {
       const executor = yield* createExecutor(

packages/plugins/mcp/src/sdk/plugin.ts

@@ -643,6 +643,7 @@ const buildConnectorInput = (
     queryParams: Object.keys(queryParams).length > 0 ? queryParams : undefined,
     headers: Object.keys(headers).length > 0 ? headers : undefined,
     authProvider,
+    ...(authProvider === undefined ? {} : { staticOAuthBearer: true }),
     httpClientLayer,
   });
 };
@@ -1327,10 +1328,20 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
           }),
         );
         if (Result.isFailure(discovered)) {
+          const reauthorizationRequired = discovered.failure.reauthorizationRequired === true;
           return {
             tools: [] as readonly ToolDef[],
             incomplete: true,
             incompleteReason: discovered.failure.message,
+            ...(reauthorizationRequired
+              ? {
+                  health: {
+                    status: "expired" as const,
+                    checkedAt: Date.now(),
+                    detail: "MCP OAuth reauthorization required",
+                  },
+                }
+              : {}),
           };
         }
         return { tools: discovered.success.tools.map(toToolDef) };
@@ -1339,7 +1350,12 @@ export const mcpPlugin = definePlugin((options?: McpPluginOptions) => {
           attributes: { "mcp.connection.name": String(connection.name) },
         }),
       ) as Effect.Effect<
-        { readonly tools: readonly ToolDef[]; readonly incomplete?: boolean },
+        {
+          readonly tools: readonly ToolDef[];
+          readonly incomplete?: boolean;
+          readonly incompleteReason?: string;
+          readonly health?: HealthCheckResult;
+        },
         StorageFailure
       >,