@stigmer/runner 3.1.6 → 3.1.7

package/dist/.build-fingerprint

@@ -1 +1 @@
-{"hash":"1a646fa123b0f5ef","builtAt":"2026-07-07T14:07:11.073Z","fileCount":243}
+{"hash":"4c57edff0c688075","builtAt":"2026-07-07T15:43:06.051Z","fileCount":244}

package/dist/activities/discover-mcp-server.js

@@ -23,6 +23,7 @@ import { activityStarted, activityFinished } from "../idle-watchdog.js";
 import { StigmerClient } from "../client/stigmer-client.js";
 import { mcpServerToResolved } from "../shared/mcp-resolver.js";
 import { toMcpClientConfig } from "../shared/mcp-manager.js";
+import { detectOAuthChallenge } from "../shared/mcp-oauth-detect.js";
 const SESSION_INIT_TIMEOUT_MS = 270_000;
 const PLATFORM_INJECTABLE_MAP = {
     STIGMER_SERVER_ADDRESS: "STIGMER_MCP_PUBLIC_ENDPOINT",
@@ -228,6 +229,16 @@ async function connectAndDiscover(slug, connectionConfig) {
             }
         });
     }
+    catch (err) {
+        // The MCP client surfaces a 401 OAuth challenge as an opaque aggregate
+        // ("unhandled errors in a TaskGroup"). For HTTP servers, re-probe once to
+        // see if the endpoint is actually asking for OAuth and, if so, replace the
+        // useless error with an actionable one. Non-OAuth failures rethrow as-is.
+        const oauthError = await classifyHttpOAuthFailure(slug, connectionConfig);
+        if (oauthError)
+            throw oauthError;
+        throw err;
+    }
     finally {
         await client.close().catch((err) => {
             console.warn(`[DiscoverMcpServer] Error closing MCP client for '${slug}': ` +
@@ -236,6 +247,18 @@ async function connectAndDiscover(slug, connectionConfig) {
     }
     return { tools, resourceTemplates };
 }
+/**
+ * If the server uses HTTP transport, probe its endpoint to classify a discovery
+ * failure as an OAuth challenge. Returns the actionable error to throw, or
+ * `null` for stdio servers and non-OAuth failures (caller rethrows original).
+ */
+async function classifyHttpOAuthFailure(slug, connectionConfig) {
+    const connection = connectionConfig[slug];
+    if (!connection || connection.transport !== "http" || !connection.url) {
+        return null;
+    }
+    return detectOAuthChallenge(connection.url, connection.headers, slug);
+}
 async function withTimeout(ms, serverSlug, fn) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {

package/dist/activities/discover-mcp-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"discover-mcp-server.js","sourceRoot":"","sources":["../../src/activities/discover-mcp-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"discover-mcp-server.js","sourceRoot":"","sources":["../../src/activities/discover-mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/shared/mcp-oauth-detect.d.ts

@@ -0,0 +1,53 @@
+/**
+ * OAuth-challenge classification for HTTP MCP endpoints.
+ *
+ * When an HTTP MCP endpoint requires OAuth (per the MCP Authorization spec /
+ * RFC 9728), an unauthenticated or statically-tokened request is answered with
+ * `401` and a `WWW-Authenticate: Bearer ...` header pointing at OAuth protected
+ * resource metadata. The MCP client SDK surfaces this only as an opaque
+ * aggregate error ("unhandled errors in a TaskGroup"), which tells the user
+ * nothing.
+ *
+ * This module turns that opaque failure into a precise, actionable signal: it
+ * re-probes the endpoint once (only on the failure path, so the happy path pays
+ * nothing) and, if it sees an OAuth challenge, returns an {@link
+ * OAuthRequiredError} whose message tells the user to connect via OAuth instead
+ * of a manual token.
+ *
+ * Kept transport-library-agnostic (uses global `fetch`) so it is reusable by
+ * connect-time discovery, execution-time error enrichment, and any other caller
+ * that holds an MCP endpoint URL + headers.
+ */
+/**
+ * Raised when an HTTP MCP endpoint answers with an OAuth authentication
+ * challenge. The message is self-contained and user-facing: it survives the
+ * Temporal boundary and is shown by the connect error wrappers verbatim.
+ *
+ * The literal phrase "requires OAuth" is a stable marker the Go/Java connect
+ * wrappers match to avoid appending a generic "check your credentials" suffix.
+ */
+export declare class OAuthRequiredError extends Error {
+    readonly serverSlug: string;
+    readonly resourceMetadataUrl?: string | undefined;
+    constructor(serverSlug: string, resourceMetadataUrl?: string | undefined);
+}
+/**
+ * Whether a `WWW-Authenticate` header value is an OAuth challenge.
+ *
+ * The MCP auth spec emits `Bearer realm="OAuth", resource_metadata="..."`. We
+ * require the `Bearer` scheme plus either an OAuth realm or a resource-metadata
+ * pointer, so a plain `Bearer` 401 from a static-token API (an invalid key, not
+ * an OAuth requirement) is not misclassified.
+ */
+export declare function isOAuthChallenge(wwwAuthenticate: string): boolean;
+/** Extract the `resource_metadata` URL from a `WWW-Authenticate` value, if present. */
+export declare function parseResourceMetadataUrl(wwwAuthenticate: string): string | undefined;
+/**
+ * Probe an HTTP MCP endpoint once to decide whether its failure is an OAuth
+ * challenge. Returns an {@link OAuthRequiredError} to throw, or `null` when the
+ * endpoint is not asking for OAuth (so the caller rethrows the original error).
+ *
+ * Never throws: any probe/network failure returns `null` so this classification
+ * step can never mask or replace the original discovery error.
+ */
+export declare function detectOAuthChallenge(url: string, headers: Record<string, string> | undefined, slug: string): Promise<OAuthRequiredError | null>;

package/dist/shared/mcp-oauth-detect.js

@@ -0,0 +1,99 @@
+/**
+ * OAuth-challenge classification for HTTP MCP endpoints.
+ *
+ * When an HTTP MCP endpoint requires OAuth (per the MCP Authorization spec /
+ * RFC 9728), an unauthenticated or statically-tokened request is answered with
+ * `401` and a `WWW-Authenticate: Bearer ...` header pointing at OAuth protected
+ * resource metadata. The MCP client SDK surfaces this only as an opaque
+ * aggregate error ("unhandled errors in a TaskGroup"), which tells the user
+ * nothing.
+ *
+ * This module turns that opaque failure into a precise, actionable signal: it
+ * re-probes the endpoint once (only on the failure path, so the happy path pays
+ * nothing) and, if it sees an OAuth challenge, returns an {@link
+ * OAuthRequiredError} whose message tells the user to connect via OAuth instead
+ * of a manual token.
+ *
+ * Kept transport-library-agnostic (uses global `fetch`) so it is reusable by
+ * connect-time discovery, execution-time error enrichment, and any other caller
+ * that holds an MCP endpoint URL + headers.
+ */
+const OAUTH_PROBE_TIMEOUT_MS = 10_000;
+/**
+ * Raised when an HTTP MCP endpoint answers with an OAuth authentication
+ * challenge. The message is self-contained and user-facing: it survives the
+ * Temporal boundary and is shown by the connect error wrappers verbatim.
+ *
+ * The literal phrase "requires OAuth" is a stable marker the Go/Java connect
+ * wrappers match to avoid appending a generic "check your credentials" suffix.
+ */
+export class OAuthRequiredError extends Error {
+    serverSlug;
+    resourceMetadataUrl;
+    constructor(serverSlug, resourceMetadataUrl) {
+        super(`MCP server '${serverSlug}' requires OAuth: its endpoint returned an ` +
+            `authentication challenge (HTTP 401). A manually-entered API token will ` +
+            `not work here — connect it with the OAuth "Sign in" flow instead.`);
+        this.serverSlug = serverSlug;
+        this.resourceMetadataUrl = resourceMetadataUrl;
+        this.name = "OAuthRequiredError";
+    }
+}
+/**
+ * Whether a `WWW-Authenticate` header value is an OAuth challenge.
+ *
+ * The MCP auth spec emits `Bearer realm="OAuth", resource_metadata="..."`. We
+ * require the `Bearer` scheme plus either an OAuth realm or a resource-metadata
+ * pointer, so a plain `Bearer` 401 from a static-token API (an invalid key, not
+ * an OAuth requirement) is not misclassified.
+ */
+export function isOAuthChallenge(wwwAuthenticate) {
+    const value = wwwAuthenticate.toLowerCase();
+    if (!value.includes("bearer"))
+        return false;
+    return value.includes("oauth") || value.includes("resource_metadata");
+}
+/** Extract the `resource_metadata` URL from a `WWW-Authenticate` value, if present. */
+export function parseResourceMetadataUrl(wwwAuthenticate) {
+    const match = /resource_metadata="([^"]+)"/i.exec(wwwAuthenticate);
+    return match?.[1];
+}
+/**
+ * Probe an HTTP MCP endpoint once to decide whether its failure is an OAuth
+ * challenge. Returns an {@link OAuthRequiredError} to throw, or `null` when the
+ * endpoint is not asking for OAuth (so the caller rethrows the original error).
+ *
+ * Never throws: any probe/network failure returns `null` so this classification
+ * step can never mask or replace the original discovery error.
+ */
+export async function detectOAuthChallenge(url, headers, slug) {
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+                ...(headers ?? {}),
+            },
+            // A minimal MCP initialize request — enough to trigger the endpoint's
+            // auth check without establishing a session.
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "initialize",
+                params: {},
+            }),
+            signal: AbortSignal.timeout(OAUTH_PROBE_TIMEOUT_MS),
+        });
+        if (response.status !== 401)
+            return null;
+        const wwwAuthenticate = response.headers.get("www-authenticate") ?? "";
+        if (!isOAuthChallenge(wwwAuthenticate))
+            return null;
+        return new OAuthRequiredError(slug, parseResourceMetadataUrl(wwwAuthenticate));
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=mcp-oauth-detect.js.map

package/dist/shared/mcp-oauth-detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-oauth-detect.js","sourceRoot":"","sources":["../../src/shared/mcp-oauth-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAEtC;;;;;;;GAOG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEzB;IACA;IAFlB,YACkB,UAAkB,EAClB,mBAA4B;QAE5C,KAAK,CACH,eAAe,UAAU,6CAA6C;YACpE,yEAAyE;YACzE,mEAAmE,CACtE,CAAC;QAPc,eAAU,GAAV,UAAU,CAAQ;QAClB,wBAAmB,GAAnB,mBAAmB,CAAS;QAO5C,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,eAAuB;IACtD,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;AACxE,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,wBAAwB,CACtC,eAAuB;IAEvB,MAAM,KAAK,GAAG,8BAA8B,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IACnE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAW,EACX,OAA2C,EAC3C,IAAY;IAEZ,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,MAAM,EAAE,qCAAqC;gBAC7C,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;aACnB;YACD,sEAAsE;YACtE,6CAA6C;YAC7C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,EAAE,EAAE,CAAC;gBACL,MAAM,EAAE,YAAY;gBACpB,MAAM,EAAE,EAAE;aACX,CAAC;YACF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,sBAAsB,CAAC;SACpD,CAAC,CAAC;QAEH,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,IAAI,CAAC;QAEzC,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QACvE,IAAI,CAAC,gBAAgB,CAAC,eAAe,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpD,OAAO,IAAI,kBAAkB,CAC3B,IAAI,EACJ,wBAAwB,CAAC,eAAe,CAAC,CAC1C,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.1.6",
+  "version": "3.1.7",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "@opentelemetry/sdk-metrics": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.1.6",
+    "@stigmer/protos": "3.1.7",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",

package/src/activities/discover-mcp-server.ts

@@ -24,6 +24,7 @@ import { activityStarted, activityFinished } from "../idle-watchdog.js";
 import { StigmerClient } from "../client/stigmer-client.js";
 import { mcpServerToResolved } from "../shared/mcp-resolver.js";
 import { toMcpClientConfig } from "../shared/mcp-manager.js";
+import { detectOAuthChallenge } from "../shared/mcp-oauth-detect.js";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import type { Config } from "../config.js";
 
@@ -374,6 +375,14 @@ async function connectAndDiscover(
         );
       }
     });
+  } catch (err) {
+    // The MCP client surfaces a 401 OAuth challenge as an opaque aggregate
+    // ("unhandled errors in a TaskGroup"). For HTTP servers, re-probe once to
+    // see if the endpoint is actually asking for OAuth and, if so, replace the
+    // useless error with an actionable one. Non-OAuth failures rethrow as-is.
+    const oauthError = await classifyHttpOAuthFailure(slug, connectionConfig);
+    if (oauthError) throw oauthError;
+    throw err;
   } finally {
     await client.close().catch((err: unknown) => {
       console.warn(
@@ -386,6 +395,22 @@ async function connectAndDiscover(
   return { tools, resourceTemplates };
 }
 
+/**
+ * If the server uses HTTP transport, probe its endpoint to classify a discovery
+ * failure as an OAuth challenge. Returns the actionable error to throw, or
+ * `null` for stdio servers and non-OAuth failures (caller rethrows original).
+ */
+async function classifyHttpOAuthFailure(
+  slug: string,
+  connectionConfig: ReturnType<typeof toMcpClientConfig>,
+): Promise<Error | null> {
+  const connection = connectionConfig[slug];
+  if (!connection || connection.transport !== "http" || !connection.url) {
+    return null;
+  }
+  return detectOAuthChallenge(connection.url, connection.headers, slug);
+}
+
 async function withTimeout<T>(
   ms: number,
   serverSlug: string,

package/src/shared/__tests__/mcp-oauth-detect.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for the HTTP MCP OAuth-challenge classifier.
+ *
+ * Verifies that `detectOAuthChallenge` recognizes a real MCP OAuth challenge
+ * (401 + `WWW-Authenticate: Bearer ...` per RFC 9728), and does NOT misfire on
+ * a plain invalid-token 401, a success, a non-OAuth error, or a network fault —
+ * so it can only ever turn an opaque failure into a clearer one, never mask a
+ * different cause.
+ */
+
+import { afterEach, describe, it, expect, vi } from "vitest";
+import {
+  OAuthRequiredError,
+  detectOAuthChallenge,
+  isOAuthChallenge,
+  parseResourceMetadataUrl,
+} from "../mcp-oauth-detect.js";
+
+function mockFetchOnce(response: {
+  status: number;
+  wwwAuthenticate?: string;
+}): void {
+  const headers = new Headers();
+  if (response.wwwAuthenticate !== undefined) {
+    headers.set("www-authenticate", response.wwwAuthenticate);
+  }
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () =>
+      new Response(null, { status: response.status, headers }),
+    ),
+  );
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("isOAuthChallenge", () => {
+  it("matches the MCP auth spec Bearer + OAuth realm challenge", () => {
+    expect(
+      isOAuthChallenge('Bearer realm="OAuth", resource_metadata="https://x/.well-known/oauth-protected-resource"'),
+    ).toBe(true);
+  });
+
+  it("matches a Bearer challenge that only advertises resource_metadata", () => {
+    expect(
+      isOAuthChallenge('Bearer resource_metadata="https://x/.well-known/oauth-protected-resource"'),
+    ).toBe(true);
+  });
+
+  it("does not match a plain Bearer 401 (invalid API key, not an OAuth requirement)", () => {
+    expect(isOAuthChallenge('Bearer error="invalid_token"')).toBe(false);
+  });
+
+  it("does not match a non-Bearer scheme", () => {
+    expect(isOAuthChallenge('Basic realm="oauth"')).toBe(false);
+  });
+
+  it("is empty-safe", () => {
+    expect(isOAuthChallenge("")).toBe(false);
+  });
+});
+
+describe("parseResourceMetadataUrl", () => {
+  it("extracts the resource_metadata URL", () => {
+    expect(
+      parseResourceMetadataUrl(
+        'Bearer realm="OAuth", resource_metadata="https://mcp.notion.com/.well-known/oauth-protected-resource/mcp"',
+      ),
+    ).toBe("https://mcp.notion.com/.well-known/oauth-protected-resource/mcp");
+  });
+
+  it("returns undefined when absent", () => {
+    expect(parseResourceMetadataUrl('Bearer realm="OAuth"')).toBeUndefined();
+  });
+});
+
+describe("detectOAuthChallenge", () => {
+  it("returns an OAuthRequiredError for a 401 OAuth challenge", async () => {
+    mockFetchOnce({
+      status: 401,
+      wwwAuthenticate:
+        'Bearer realm="OAuth", resource_metadata="https://mcp.notion.com/.well-known/oauth-protected-resource/mcp"',
+    });
+
+    const result = await detectOAuthChallenge("https://mcp.notion.com/mcp", {}, "notion");
+
+    expect(result).toBeInstanceOf(OAuthRequiredError);
+    expect(result?.serverSlug).toBe("notion");
+    expect(result?.resourceMetadataUrl).toBe(
+      "https://mcp.notion.com/.well-known/oauth-protected-resource/mcp",
+    );
+    // The message is self-contained and carries the "requires OAuth" marker the
+    // connect wrappers key on.
+    expect(result?.message).toContain("requires OAuth");
+    expect(result?.message).toContain("notion");
+  });
+
+  it("returns null for a 401 that is NOT an OAuth challenge (invalid static token)", async () => {
+    mockFetchOnce({ status: 401, wwwAuthenticate: 'Bearer error="invalid_token"' });
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("returns null on a non-401 response", async () => {
+    mockFetchOnce({ status: 200 });
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("returns null (never throws) when the probe itself fails", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new Error("network down");
+      }),
+    );
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("forwards the resolved headers to the probe request", async () => {
+    const fetchMock = vi.fn(
+      async (_url: string | URL, _init?: RequestInit) =>
+        new Response(null, { status: 200 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await detectOAuthChallenge(
+      "https://api.example.com/mcp",
+      { Authorization: "Bearer stale-token" },
+      "example",
+    );
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect((init?.headers as Record<string, string>).Authorization).toBe(
+      "Bearer stale-token",
+    );
+    expect(init?.method).toBe("POST");
+  });
+});

package/src/shared/mcp-oauth-detect.ts

@@ -0,0 +1,112 @@
+/**
+ * OAuth-challenge classification for HTTP MCP endpoints.
+ *
+ * When an HTTP MCP endpoint requires OAuth (per the MCP Authorization spec /
+ * RFC 9728), an unauthenticated or statically-tokened request is answered with
+ * `401` and a `WWW-Authenticate: Bearer ...` header pointing at OAuth protected
+ * resource metadata. The MCP client SDK surfaces this only as an opaque
+ * aggregate error ("unhandled errors in a TaskGroup"), which tells the user
+ * nothing.
+ *
+ * This module turns that opaque failure into a precise, actionable signal: it
+ * re-probes the endpoint once (only on the failure path, so the happy path pays
+ * nothing) and, if it sees an OAuth challenge, returns an {@link
+ * OAuthRequiredError} whose message tells the user to connect via OAuth instead
+ * of a manual token.
+ *
+ * Kept transport-library-agnostic (uses global `fetch`) so it is reusable by
+ * connect-time discovery, execution-time error enrichment, and any other caller
+ * that holds an MCP endpoint URL + headers.
+ */
+
+const OAUTH_PROBE_TIMEOUT_MS = 10_000;
+
+/**
+ * Raised when an HTTP MCP endpoint answers with an OAuth authentication
+ * challenge. The message is self-contained and user-facing: it survives the
+ * Temporal boundary and is shown by the connect error wrappers verbatim.
+ *
+ * The literal phrase "requires OAuth" is a stable marker the Go/Java connect
+ * wrappers match to avoid appending a generic "check your credentials" suffix.
+ */
+export class OAuthRequiredError extends Error {
+  constructor(
+    public readonly serverSlug: string,
+    public readonly resourceMetadataUrl?: string,
+  ) {
+    super(
+      `MCP server '${serverSlug}' requires OAuth: its endpoint returned an ` +
+        `authentication challenge (HTTP 401). A manually-entered API token will ` +
+        `not work here — connect it with the OAuth "Sign in" flow instead.`,
+    );
+    this.name = "OAuthRequiredError";
+  }
+}
+
+/**
+ * Whether a `WWW-Authenticate` header value is an OAuth challenge.
+ *
+ * The MCP auth spec emits `Bearer realm="OAuth", resource_metadata="..."`. We
+ * require the `Bearer` scheme plus either an OAuth realm or a resource-metadata
+ * pointer, so a plain `Bearer` 401 from a static-token API (an invalid key, not
+ * an OAuth requirement) is not misclassified.
+ */
+export function isOAuthChallenge(wwwAuthenticate: string): boolean {
+  const value = wwwAuthenticate.toLowerCase();
+  if (!value.includes("bearer")) return false;
+  return value.includes("oauth") || value.includes("resource_metadata");
+}
+
+/** Extract the `resource_metadata` URL from a `WWW-Authenticate` value, if present. */
+export function parseResourceMetadataUrl(
+  wwwAuthenticate: string,
+): string | undefined {
+  const match = /resource_metadata="([^"]+)"/i.exec(wwwAuthenticate);
+  return match?.[1];
+}
+
+/**
+ * Probe an HTTP MCP endpoint once to decide whether its failure is an OAuth
+ * challenge. Returns an {@link OAuthRequiredError} to throw, or `null` when the
+ * endpoint is not asking for OAuth (so the caller rethrows the original error).
+ *
+ * Never throws: any probe/network failure returns `null` so this classification
+ * step can never mask or replace the original discovery error.
+ */
+export async function detectOAuthChallenge(
+  url: string,
+  headers: Record<string, string> | undefined,
+  slug: string,
+): Promise<OAuthRequiredError | null> {
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        ...(headers ?? {}),
+      },
+      // A minimal MCP initialize request — enough to trigger the endpoint's
+      // auth check without establishing a session.
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {},
+      }),
+      signal: AbortSignal.timeout(OAUTH_PROBE_TIMEOUT_MS),
+    });
+
+    if (response.status !== 401) return null;
+
+    const wwwAuthenticate = response.headers.get("www-authenticate") ?? "";
+    if (!isOAuthChallenge(wwwAuthenticate)) return null;
+
+    return new OAuthRequiredError(
+      slug,
+      parseResourceMetadataUrl(wwwAuthenticate),
+    );
+  } catch {
+    return null;
+  }
+}