mixdog 1.2.1 → 1.2.3

package/src/runtime/agent/orchestrator/mcp/client-handshake.mjs

@@ -6,6 +6,7 @@
 import { markServiceUnreachable, isConnRefuseError } from '../../../shared/service-discovery.mjs';
 import { MCP_MAX_TIMER_MS, resolveMcpStartupTimeoutMs } from './client-config.mjs';
 import { appendMcpStderrTail } from './client-transport.mjs';
+import { MCP_OAUTH_TIMEOUT_MS } from './oauth.mjs';
 
 // tools/list pagination bounds: a server that never stops handing out cursors
 // (or repeats one) cannot loop the client forever.
@@ -53,6 +54,15 @@ function startupTimeoutError(name, startupTimeoutMs) {
   return err;
 }
 
+const oauthLoginError = () => new Error('MCP OAuth login failed, cancelled, or timed out');
+
+/** Code of a connect cancelled (login cancel, disconnect, shutdown) before any
+ *  interactive login started. */
+export const MCP_CONNECT_CANCELLED = 'EMCPCONNECTCANCELLED';
+function connectCancelledError(name) {
+  return Object.assign(new Error(`MCP server "${name}" connect cancelled`), { code: MCP_CONNECT_CANCELLED });
+}
+
 /**
  * Bound the connect + listTools handshake so a slow/hung server can't stall
  * boot or the first turn. On expiry the pending transport/child is torn down
@@ -73,17 +83,43 @@ export async function runBoundedHandshake({
 }) {
   const startupTimeoutMs = resolveMcpStartupTimeoutMs(cfg);
   const guard = { timer: null, timedOut: false };
+  let rejectDeadline;
+  // True once an interactive login actually started (the server challenged
+  // and a browser sign-in was allowed).
+  let loginStarted = false;
+  const armDeadline = (ms, error = () => startupTimeoutError(name, ms)) => {
+    if (guard.timer) clearTimeout(guard.timer);
+    guard.timer = setTimeout(() => {
+      guard.timedOut = true;
+      rejectDeadline(error());
+    }, ms);
+  };
+  const deadline = new Promise((_, reject) => {
+    rejectDeadline = reject;
+  });
+  // A closed OAuth connection (login cancel, disconnect, shutdown) settles a
+  // handshake that would otherwise wait forever (an SSE stream closed while
+  // starting never settles). The SDK also closes the transport — and with it
+  // the OAuth connection — right before rethrowing a connect failure of its
+  // own (e.g. connection refused): deferring past the pending microtasks lets
+  // that real failure settle the race first.
+  const cancelOAuth = () =>
+    setImmediate(() => rejectDeadline(loginStarted ? oauthLoginError() : connectCancelledError(name)));
+  transport.oauth?.signal.addEventListener('abort', cancelOAuth, { once: true });
+  if (transport.oauth?.signal.aborted) cancelOAuth();
+  if (startupTimeoutMs > 0) armDeadline(startupTimeoutMs);
+  // Human authorization gets a separate, finite budget. The ordinary startup
+  // budget still applies until the server actually challenges authentication.
+  if (transport.oauth) {
+    transport.oauth.onStart = () => {
+      loginStarted = true;
+      armDeadline(MCP_OAUTH_TIMEOUT_MS, oauthLoginError);
+    };
+  }
   const handshake = performHandshake(client, transport, {
-    timeout: startupTimeoutMs > 0 ? startupTimeoutMs : MCP_MAX_TIMER_MS,
+    timeout: !transport.oauth && startupTimeoutMs > 0 ? startupTimeoutMs : MCP_MAX_TIMER_MS,
   });
   try {
-    if (startupTimeoutMs <= 0) return await handshake;
-    const deadline = new Promise((_, rej) => {
-      guard.timer = setTimeout(() => {
-        guard.timedOut = true;
-        rej(startupTimeoutError(name, startupTimeoutMs));
-      }, startupTimeoutMs);
-    });
     return await Promise.race([handshake, deadline]);
   } catch (err) {
     // A discovery-advert port that fails to connect is a corpse (recycled
@@ -92,7 +128,7 @@ export async function runBoundedHandshake({
     // ONLY — a startup/handshake timeout is a slow-but-alive server.
     if (autoDetectAdvert && isConnRefuseError(err))
       markServiceUnreachable(autoDetectAdvert.service, autoDetectAdvert.port);
-    if (guard.timedOut) {
+    if (guard.timedOut || transport.oauth?.signal.aborted) {
       // Tear down the pending transport/child so a hung handshake never
       // leaks a stdio process or socket — fire-and-forget (like the
       // tool-call timeout path) so a slow tree-kill never delays this
@@ -100,7 +136,7 @@ export async function runBoundedHandshake({
       try {
         closeServer({ client, transport }).catch(() => {});
       } catch {
-        /* ignore */
+        // Teardown is best effort: the handshake failure below is what gets reported.
       }
       // Never let the late handshake settle into an unhandled rejection.
       handshake.catch(() => {});
@@ -112,6 +148,9 @@ export async function runBoundedHandshake({
     }
     throw tail ? new Error(appendMcpStderrTail(String(err), tail)) : err;
   } finally {
+    transport.oauth?.finishConnect();
     if (guard.timer) clearTimeout(guard.timer);
+    transport.oauth?.signal.removeEventListener('abort', cancelOAuth);
+    if (transport.oauth) transport.oauth.onStart = () => {};
   }
 }

package/src/runtime/agent/orchestrator/mcp/client-transport.mjs

@@ -4,6 +4,7 @@
  * WebSocket, or a stdio child.
  */
 import { readServicePort } from '../../../shared/service-discovery.mjs';
+import { createMcpOAuth } from './oauth.mjs';
 import {
   AUTO_DETECT_PORTS,
   expandEnvVars,
@@ -11,6 +12,7 @@ import {
   mcpUrlForLog,
   normalizeMcpTransportUrl,
   resolveMcpHttpHeaders,
+  resolveMcpOAuthUrl,
   resolveMcpStdioEnvironment,
   resolveMcpTransportKind,
   scrubMcpConnectionMessage,
@@ -49,6 +51,19 @@ function requestInitFor(cfg) {
   return headers && Object.keys(headers).length > 0 ? { requestInit: { headers } } : undefined;
 }
 
+// Configured authentication stays authoritative even when its variables are
+// unset or resolve empty: the server then fails as configured instead of
+// turning into an OAuth login.
+export function hasConfiguredMcpAuth(cfg) {
+  const configured = (value) =>
+    value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length > 0;
+  return (
+    Boolean(String(cfg.bearer_token_env_var || '').trim()) ||
+    configured(cfg.headers) ||
+    configured(cfg.env_http_headers)
+  );
+}
+
 // The SDK's WebSocket transport opens its socket without a way to set request
 // headers. This subclass changes only socket creation: Node's WebSocket takes
 // `{ protocols, headers }`; the guard and event wiring match the stock start().
@@ -88,7 +103,7 @@ function createHeaderWebSocketTransport(Base, messageSchema, url, headers) {
  *  transports. `strictEnv` (the caller passes it for plugin-declared servers)
  *  makes unset variables without a default fail the server; otherwise they
  *  expand to empty and are reported in `warnings` (names only). */
-export function createMcpTransport({ name, cfg, sdk, log, strictEnv }) {
+export function createMcpTransport({ name, cfg, sdk, log, strictEnv, oauthOptions }) {
   const { StdioClientTransport, StreamableHTTPClientTransport, SSEClientTransport, WebSocketClientTransport } = sdk;
   const kind = resolveMcpTransportKind(cfg);
   const warnings = [];
@@ -113,11 +128,33 @@ export function createMcpTransport({ name, cfg, sdk, log, strictEnv }) {
   }
   if (kind === 'http' || kind === 'sse') {
     const Transport = kind === 'http' ? StreamableHTTPClientTransport : SSEClientTransport;
-    const url = normalizeMcpTransportUrl(expandEnvVars(String(cfg.url ?? '')), kind);
+    const url = resolveMcpOAuthUrl(cfg);
     const opts = requestInitFor(cfg);
+    // Explicit authentication remains authoritative (including custom API-key
+    // headers). Never forward those credentials to OAuth discovery endpoints.
+    let transport;
+    const oauth = hasConfiguredMcpAuth(cfg)
+      ? null
+      : createMcpOAuth({
+          url,
+          serverName: name,
+          ...oauthOptions,
+          // SSE advertises its POST endpoint on the authenticated event stream.
+          // No other path on the origin is allowed to receive this server's token.
+          isTransportEndpoint: (input) => kind === 'sse' && transport?._endpoint?.href === new URL(input).href,
+        });
+    transport = new Transport(new URL(url), oauth ? { fetch: oauth.fetch } : opts);
+    if (oauth) {
+      transport.oauth = oauth;
+      const close = transport.close.bind(transport);
+      transport.close = async () => {
+        oauth.close();
+        await close();
+      };
+    }
     log(`[mcp-client] Connecting "${name}" via ${kind.toUpperCase()}: ${mcpUrlForLog(url)}\n`);
     return {
-      transport: opts ? new Transport(new URL(url), opts) : new Transport(new URL(url)),
+      transport,
       autoDetectAdvert: null,
       stderrTail: noStderrTail,
       warnings,

package/src/runtime/agent/orchestrator/mcp/client.mjs

@@ -24,13 +24,22 @@ import { currentToolExecutionOwner } from '../../../shared/tool-execution-owner.
 import { positiveInt } from '../../../shared/numbers.mjs';
 import {
   providerSafeMcpToolName,
+  resolveMcpOAuthUrl,
   resolveMcpRequestTimeouts,
   resolveMcpTransportKind,
   scrubMcpConnectionMessage,
+  scrubMcpSecrets,
 } from './client-config.mjs';
 import { createLazyOutputValidator } from './lazy-output-validator.mjs';
-import { appendMcpStderrTail, createMcpTransport } from './client-transport.mjs';
-import { listAllMcpTools, runBoundedHandshake } from './client-handshake.mjs';
+import { appendMcpStderrTail, createMcpTransport, hasConfiguredMcpAuth } from './client-transport.mjs';
+import { listAllMcpTools, MCP_CONNECT_CANCELLED, runBoundedHandshake } from './client-handshake.mjs';
+import {
+  clearMcpOAuth,
+  hasStoredMcpOAuthTokens,
+  isMcpOAuthReauthenticationRequired,
+  MCP_OAUTH_CALLBACK_NOT_PENDING,
+} from './oauth.mjs';
+export { probeMcpServerAuth } from './oauth-probe.mjs';
 
 // Config interpretation (transport kind, URL policy, env expansion, headers,
 // timeouts, log scrubbing) lives in client-config.mjs; re-exported so every
@@ -103,6 +112,20 @@ function mcpLog(line) {
   if (process.env.MIXDOG_QUIET_MCP_LOG) return;
   process.stderr.write(line);
 }
+// OAuth tokens belong to the live connection, not to its config: a server may
+// echo the request (Authorization included) into an error body or result.
+function oauthSecrets(...transports) {
+  return transports.flatMap((transport) => transport?.oauth?.secrets() || []);
+}
+function scrubMcpOAuthError(error, cfg, secrets) {
+  if (secrets.length === 0) return error;
+  if (!(error instanceof Error)) return new Error(scrubMcpConnectionMessage(String(error), cfg, secrets));
+  error.message = scrubMcpConnectionMessage(error.message, cfg, secrets);
+  if (typeof error.stack === 'string') error.stack = scrubMcpConnectionMessage(error.stack, cfg, secrets);
+  // A JSON-RPC error carries the server's own payload (McpError.data).
+  if (error.data !== undefined) error.data = scrubMcpSecrets(error.data, secrets);
+  return error;
+}
 
 async function loadMcpSdk() {
   mcpSdkPromise ??= Promise.all([
@@ -148,14 +171,16 @@ export async function connectMcpServers(config, options = {}) {
   });
   // Connect all servers in PARALLEL: a slow/hung server (bounded by its
   // per-server startup timeout) must never delay the others' handshakes.
-  const settled = await Promise.allSettled(entries.map(([name, cfg]) => connectServer(name, cfg, scopeId, genAtStart)));
+  const settled = await Promise.allSettled(
+    entries.map(([name, cfg]) => connectServer(name, cfg, scopeId, genAtStart, options))
+  );
   settled.forEach((res, i) => {
     if (res.status !== 'rejected') return;
     const [name, cfg] = entries[i];
     const rawMessage = res.reason instanceof Error ? res.reason.message : String(res.reason);
     const msg = scrubMcpConnectionMessage(rawMessage, cfg);
     mcpLog(`[mcp-client] Failed to connect "${name}": ${msg}\n`);
-    failures.push({ name, msg });
+    failures.push({ name, msg, ...(res.reason?.authRequired ? { authRequired: true } : {}) });
   });
   if (failures.length > 0) {
     const detail = failures.map((f) => `${f.name}: ${f.msg}`).join('; ');
@@ -330,7 +355,7 @@ export function getMcpServerInstructionsMap(scopeId = DEFAULT_MCP_SCOPE_ID) {
 // shutdown generation captured BEFORE the caller queued/closed anything: a
 // disconnectAll() landing during the close (or the connect) bumps it, and the
 // replacement must then never register (no resurrection after shutdown).
-async function replaceServerConnection(scopeId, name, current, cfg, genAtStart) {
+async function replaceServerConnection(scopeId, name, current, cfg, genAtStart, options = {}) {
   const registryKey = mcpServerRegistryKey(scopeId, name);
   if (current) {
     await _closeServer(current);
@@ -343,10 +368,12 @@ async function replaceServerConnection(scopeId, name, current, cfg, genAtStart)
   try {
     // connectServer re-checks the same generation after loading the SDK and
     // again right before registering, so a shutdown mid-handshake also aborts.
-    await connectServer(name, cfg, scopeId, genAtStart);
+    await connectServer(name, cfg, scopeId, genAtStart, options);
   } catch (reason) {
     const rawMessage = reason instanceof Error ? reason.message : String(reason);
-    throw new Error(scrubMcpConnectionMessage(rawMessage, cfg));
+    const error = new Error(scrubMcpConnectionMessage(rawMessage, cfg));
+    if (reason?.authRequired) error.authRequired = true;
+    throw error;
   }
 }
 
@@ -356,6 +383,7 @@ async function replaceServerConnection(scopeId, name, current, cfg, genAtStart)
 // connect per server is ever running (no doubly registered transports).
 async function runExclusiveServerOp(registryKey, task) {
   for (let pending = reconnects.wait(registryKey); pending; pending = reconnects.wait(registryKey)) {
+    // Only waiting for the reconnect to settle; its failure belongs to its caller.
     await pending.catch(() => {});
   }
   return reconnects.run(registryKey, task);
@@ -396,7 +424,7 @@ async function reconnectMcpServer(scopeId, serverName, failedServer) {
  * rejects (credential-scrubbed message) when the connect fails, leaving the
  * server unregistered.
  */
-export async function reconnectSingleMcpServer(scopeId, name, cfg = undefined) {
+export async function reconnectSingleMcpServer(scopeId, name, cfg = undefined, options = {}) {
   const normalized = normalizeMcpScopeId(scopeId);
   _knownMcpScopes.add(normalized);
   const registryKey = mcpServerRegistryKey(normalized, name);
@@ -415,7 +443,7 @@ export async function reconnectSingleMcpServer(scopeId, name, cfg = undefined) {
       closeCallAdmission(normalized, name, `MCP ${name} disabled`);
       return false;
     }
-    await replaceServerConnection(normalized, name, current, nextCfg, genAtStart);
+    await replaceServerConnection(normalized, name, current, nextCfg, genAtStart, options);
     return true;
   });
 }
@@ -438,96 +466,101 @@ export async function executeMcpTool(name, args, options = {}) {
     definition?.mcpOperation
       ? _callMcpFeatureWithTimeout(target, definition.mcpOperation, args, callSignal)
       : _callToolWithTimeout(target, toolName, args, callSignal);
+  let retryServer = null;
+  const secrets = () => oauthSecrets(server.transport, retryServer?.transport);
   const gate = callAdmissionFor(server);
-  return gate.run(
-    options?.ownerKey || currentToolExecutionOwner(),
-    async () => {
-      // The gate stops forwarding the caller's abort once this task is
-      // admitted, so the task itself observes the signal for its whole run.
-      if (callSignal?.aborted) {
-        throw mcpAbortError(
-          callSignal,
-          `MCP tool call aborted before dispatch (server="${serverName}", tool="${toolName}")`
-        );
-      }
-      let result;
-      try {
-        result = await dispatch(server);
-      } catch (firstErr) {
-        const firstMsg = firstErr instanceof Error ? firstErr.message : String(firstErr);
-        if (isMcpCallAbortError(firstErr) || callSignal?.aborted) {
-          // A cancelled call is not a transport failure: reconnecting and
-          // replaying it would duplicate the side effect the caller just
-          // walked away from.
-          mcpLog(`[mcp-client] Tool call aborted by caller for "${serverName}/${toolName}".\n`);
-          throw firstErr;
-        }
-        if (isMcpToolCallTimeoutError(firstErr)) {
-          mcpLog(`[mcp-client] Tool call timed out; skipping reconnect retry for "${serverName}/${toolName}".\n`);
-          throw firstErr;
-        }
-        const serverDead = server.liveness?.alive === false;
-        if (!serverDead && isMcpServerResponseError(firstErr)) {
-          // The server answered (JSON-RPC error): it is alive — nothing to
-          // reconnect, and the call already ran its course.
-          throw firstErr;
-        }
-        // Only a failure that proves the request never left this process
-        // may be replayed; anything else may already have run server-side.
-        const undelivered = isMcpUndeliveredError(firstErr);
-        const deadTail = serverDead ? server.stderrTail?.() : '';
-        mcpLog(`[mcp-client] Tool call failed, attempting shared reconnect...\n`);
-        let retryServer;
-        try {
-          // The reconnect is SHARED (singleflight): the race only stops
-          // THIS caller from waiting on it — the reconnect keeps running
-          // for its other waiters. Without this, an abort mid-reconnect
-          // could not settle the call and the admission slot stayed held
-          // until the reconnect finished, or forever if it hung.
-          retryServer = await raceMcpAbort(
-            reconnectMcpServer(scopeId, serverName, server),
-            callSignal,
-            `MCP tool call aborted during reconnect (server="${serverName}", tool="${toolName}")`
-          );
-        } catch (reconnectErr) {
-          if (isMcpCallAbortError(reconnectErr) || callSignal?.aborted) throw reconnectErr;
-          const reconnectMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
-          throw new Error(
-            appendMcpStderrTail(`Tool call failed: ${firstMsg}; reconnect also failed: ${reconnectMsg}`, deadTail)
-          );
-        }
-        if (!undelivered) {
-          throw new Error(
-            appendMcpStderrTail(
-              `Tool call failed: ${firstMsg}; MCP server "${serverName}" was reconnected for the next call, but this call was not replayed because the request may already have reached the server`,
-              deadTail
-            )
-          );
-        }
-        // A reconnect that outlived the caller's abort must not dispatch the
-        // retry: that would run the side effect after cancellation.
+  return gate
+    .run(
+      options?.ownerKey || currentToolExecutionOwner(),
+      async () => {
+        // The gate stops forwarding the caller's abort once this task is
+        // admitted, so the task itself observes the signal for its whole run.
         if (callSignal?.aborted) {
           throw mcpAbortError(
             callSignal,
-            `MCP tool call aborted after reconnect (server="${serverName}", tool="${toolName}")`
+            `MCP tool call aborted before dispatch (server="${serverName}", tool="${toolName}")`
           );
         }
+        let result;
         try {
-          result = await dispatch(retryServer);
-        } catch (retryErr) {
-          if (isMcpCallAbortError(retryErr) || callSignal?.aborted) throw retryErr;
-          const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
-          throw new Error(`Tool call failed: ${firstMsg}; retry after reconnect also failed: ${retryMsg}`);
+          result = await dispatch(server);
+        } catch (firstErr) {
+          const firstMsg = firstErr instanceof Error ? firstErr.message : String(firstErr);
+          if (isMcpCallAbortError(firstErr) || callSignal?.aborted) {
+            // A cancelled call is not a transport failure: reconnecting and
+            // replaying it would duplicate the side effect the caller just
+            // walked away from.
+            mcpLog(`[mcp-client] Tool call aborted by caller for "${serverName}/${toolName}".\n`);
+            throw firstErr;
+          }
+          if (isMcpToolCallTimeoutError(firstErr)) {
+            mcpLog(`[mcp-client] Tool call timed out; skipping reconnect retry for "${serverName}/${toolName}".\n`);
+            throw firstErr;
+          }
+          const serverDead = server.liveness?.alive === false;
+          if (!serverDead && isMcpServerResponseError(firstErr)) {
+            // The server answered (JSON-RPC error): it is alive — nothing to
+            // reconnect, and the call already ran its course.
+            throw firstErr;
+          }
+          // Only a failure that proves the request never left this process
+          // may be replayed; anything else may already have run server-side.
+          const undelivered = isMcpUndeliveredError(firstErr);
+          const deadTail = serverDead ? server.stderrTail?.() : '';
+          mcpLog(`[mcp-client] Tool call failed, attempting shared reconnect...\n`);
+          try {
+            // The reconnect is SHARED (singleflight): the race only stops
+            // THIS caller from waiting on it — the reconnect keeps running
+            // for its other waiters. Without this, an abort mid-reconnect
+            // could not settle the call and the admission slot stayed held
+            // until the reconnect finished, or forever if it hung.
+            retryServer = await raceMcpAbort(
+              reconnectMcpServer(scopeId, serverName, server),
+              callSignal,
+              `MCP tool call aborted during reconnect (server="${serverName}", tool="${toolName}")`
+            );
+          } catch (reconnectErr) {
+            if (isMcpCallAbortError(reconnectErr) || callSignal?.aborted) throw reconnectErr;
+            const reconnectMsg = reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr);
+            throw new Error(
+              appendMcpStderrTail(`Tool call failed: ${firstMsg}; reconnect also failed: ${reconnectMsg}`, deadTail)
+            );
+          }
+          if (!undelivered) {
+            throw new Error(
+              appendMcpStderrTail(
+                `Tool call failed: ${firstMsg}; MCP server "${serverName}" was reconnected for the next call, but this call was not replayed because the request may already have reached the server`,
+                deadTail
+              )
+            );
+          }
+          // A reconnect that outlived the caller's abort must not dispatch the
+          // retry: that would run the side effect after cancellation.
+          if (callSignal?.aborted) {
+            throw mcpAbortError(
+              callSignal,
+              `MCP tool call aborted after reconnect (server="${serverName}", tool="${toolName}")`
+            );
+          }
+          try {
+            result = await dispatch(retryServer);
+          } catch (retryErr) {
+            if (isMcpCallAbortError(retryErr) || callSignal?.aborted) throw retryErr;
+            const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+            throw new Error(`Tool call failed: ${firstMsg}; retry after reconnect also failed: ${retryMsg}`);
+          }
         }
+        const normalized = normalizeToolEnvelope(await normalizeMcpToolResult(scrubMcpSecrets(result, secrets())));
+        const text = capMcpResult(normalized.result);
+        return normalized.explicitSuccess ? makeToolEnvelope(text, [], { explicitSuccess: true }) : text;
+      },
+      {
+        signal: callSignal,
       }
-      const normalized = normalizeToolEnvelope(await normalizeMcpToolResult(result));
-      const text = capMcpResult(normalized.result);
-      return normalized.explicitSuccess ? makeToolEnvelope(text, [], { explicitSuccess: true }) : text;
-    },
-    {
-      signal: callSignal,
-    }
-  );
+    )
+    .catch((error) => {
+      throw scrubMcpOAuthError(error, server.cfg, secrets());
+    });
 }
 
 const MCP_FEATURE_REQUESTS = {
@@ -903,6 +936,7 @@ export function raceMcpAbort(promise, signal, message) {
   if (!signal) return promise;
   allowConcurrentAbortListeners(signal);
   if (signal.aborted) {
+    // The abort wins; the abandoned promise's late rejection must not go unhandled.
     void Promise.resolve(promise).catch(() => {});
     return Promise.reject(mcpAbortError(signal, message));
   }
@@ -1090,6 +1124,7 @@ export async function disconnectAll(options = undefined) {
       /* ignore */
     }
     try {
+      entry.transport.oauth?.close();
       void entry.client.close().catch(() => {
         /* ignore */
       });
@@ -1118,6 +1153,9 @@ export async function disconnectAll(options = undefined) {
 export async function disconnectMcpServer(name, options = {}) {
   const scopeId = normalizeMcpScopeId(options);
   const registryKey = mcpServerRegistryKey(scopeId, name);
+  // An exclusive reconnect may currently be waiting for human authorization.
+  // Cancel before queueing the disconnect behind that operation.
+  cancelMcpLogin(name, options);
   return runExclusiveServerOp(registryKey, async () => {
     const server = servers.get(registryKey);
     if (!server) return false;
@@ -1132,6 +1170,73 @@ export async function disconnectMcpServer(name, options = {}) {
     return true;
   });
 }
+/**
+ * Cancel the interactive OAuth login of a connect of `name` still in its
+ * handshake; that connect then fails. Callers that queue behind the connect
+ * (disable, remove) call this first so they never wait out the login.
+ */
+export function cancelMcpLogin(name, options = {}) {
+  const scopeId = normalizeMcpScopeId(options);
+  for (const entry of _pendingConnects) {
+    if (entry.scopeId === scopeId && entry.name === name) entry.transport.oauth?.close();
+  }
+}
+/**
+ * Answer the interactive OAuth login of a connect of `name` still in its
+ * handshake with the redirect URL pasted from the browser (remote / headless
+ * sign-in); that connect then proceeds as after the loopback callback. Throws
+ * a fixed message, never the pasted URL, for an invalid paste (the login stays
+ * pending) or when no login is waiting.
+ */
+export function completeMcpLogin(name, callbackUrl, options = {}) {
+  const scopeId = normalizeMcpScopeId(options);
+  for (const entry of _pendingConnects) {
+    if (entry.scopeId === scopeId && entry.name === name && entry.transport.oauth?.loginStarted) {
+      entry.transport.oauth.completeCallback(callbackUrl);
+      return;
+    }
+  }
+  throw new Error(MCP_OAUTH_CALLBACK_NOT_PENDING);
+}
+/** Whether a connect of `name` still in its handshake is waiting for an
+ *  interactive (browser) OAuth login. */
+export function isMcpLoginPending(name, options = {}) {
+  const scopeId = normalizeMcpScopeId(options);
+  for (const entry of _pendingConnects) {
+    if (entry.scopeId === scopeId && entry.name === name && entry.transport.oauth?.loginStarted) return true;
+  }
+  return false;
+}
+/**
+ * Stored OAuth sign-in state of an HTTP/SSE server without configured
+ * authentication: `{ signedIn }` (tokens stored for its exact URL), or null
+ * for servers that never use MCP OAuth.
+ */
+export function getMcpServerOAuthState(cfg) {
+  let url;
+  try {
+    url = resolveMcpOAuthUrl(cfg);
+  } catch {
+    return null;
+  }
+  if (!url || hasConfiguredMcpAuth(cfg)) return null;
+  return { signedIn: hasStoredMcpOAuthTokens(url) };
+}
+/**
+ * Log out of an HTTP/SSE server URL: delete the OAuth tokens and client
+ * registration stored for it, shared by every server configured with that
+ * exact URL, and drop them from live connections.
+ */
+export async function clearMcpServerOAuth(cfg) {
+  let url;
+  try {
+    url = resolveMcpOAuthUrl(cfg);
+  } catch {
+    // A config without a valid remote URL never connected, so never logged in.
+    return;
+  }
+  if (url) await clearMcpOAuth({ url });
+}
 /**
  * Close a single server: for stdio transports first shut down the full child
  * process tree (close stdin -> grace -> tree kill) so wrapper chains such as
@@ -1143,6 +1248,7 @@ async function _closeServer(server) {
   // A deliberate close is not a crash: suppress the unexpected-close report.
   if (server?.liveness) server.liveness.closing = true;
   const transport = server?.transport;
+  transport?.oauth?.close();
   // Live stdio transports expose the spawned ChildProcess on _process.
   if (transport?._process) {
     try {
@@ -1165,7 +1271,8 @@ async function connectServer(
   name,
   cfg,
   scopeId = DEFAULT_MCP_SCOPE_ID,
-  genAtStart = currentConnectAbortGeneration(scopeId)
+  genAtStart = currentConnectAbortGeneration(scopeId),
+  options = {}
 ) {
   scopeId = normalizeMcpScopeId(scopeId);
   _knownMcpScopes.add(scopeId);
@@ -1182,8 +1289,14 @@ async function connectServer(
     sdk,
     log: mcpLog,
     strictEnv: cfg?._mixdogStrictEnv === true,
+    // Only an explicit sign-in (beginMcpOAuthLogin) is interactive; it may
+    // supply its own browser launcher to capture the authorization URL.
+    oauthOptions: {
+      interactive: options.interactive === true,
+      ...(typeof options.openBrowser === 'function' ? { openBrowser: options.openBrowser } : {}),
+    },
   });
-  const liveness = trackMcpLiveness(client, name, cfg, stderrTail);
+  const liveness = trackMcpLiveness(client, name, cfg, stderrTail, transport);
   const pending = { scopeId, name, client, transport };
   _pendingConnects.add(pending);
   try {
@@ -1237,6 +1350,22 @@ async function connectServer(
     }
     _invalidateMcpToolFieldMemo();
     mcpLog(`[mcp] connected: ${tools.length} tools — ${tools.map((t) => t.name).join(', ')}\n`);
+  } catch (error) {
+    await _closeServer({ client, transport, liveness });
+    const scrubbed = scrubMcpOAuthError(error, cfg, oauthSecrets(transport));
+    // A server that only needs an OAuth sign-in is not a broken server: the
+    // sign-in was required, or an explicit one did not complete (cancelled,
+    // denied, timed out or a failed exchange after it started, or cancelled
+    // before it could). A failure after the sign-in obtained tokens is real.
+    const signInIncomplete =
+      transport.oauth &&
+      (isMcpOAuthReauthenticationRequired(error) ||
+        (transport.oauth.loginStarted && !transport.oauth.loginCompleted) ||
+        (transport.oauth.interactive && error?.code === MCP_CONNECT_CANCELLED));
+    if (signInIncomplete && scrubbed && typeof scrubbed === 'object') {
+      scrubbed.authRequired = true;
+    }
+    throw scrubbed;
   } finally {
     _pendingConnects.delete(pending);
   }
@@ -1249,7 +1378,7 @@ async function connectServer(
  * records the last error (parse/send hiccups do not mean the server died).
  * Handlers already installed on the client are chained, not replaced.
  */
-function trackMcpLiveness(client, name, cfg, stderrTail) {
+function trackMcpLiveness(client, name, cfg, stderrTail, transport) {
   const liveness = { alive: true, closing: false, closedAt: 0, lastError: '' };
   const priorClose = client.onclose;
   const priorError = client.onerror;
@@ -1263,7 +1392,11 @@ function trackMcpLiveness(client, name, cfg, stderrTail) {
     if (typeof priorClose === 'function') priorClose.apply(client, args);
   };
   client.onerror = (error, ...rest) => {
-    liveness.lastError = scrubMcpConnectionMessage(error instanceof Error ? error.message : String(error), cfg);
+    liveness.lastError = scrubMcpConnectionMessage(
+      error instanceof Error ? error.message : String(error),
+      cfg,
+      oauthSecrets(transport)
+    );
     if (typeof priorError === 'function') priorError.call(client, error, ...rest);
   };
   return liveness;
@@ -1316,6 +1449,7 @@ export function setMcpScopeRoot(scopeId, root) {
     if (server.cfg?._mixdogRootsFollowScope !== true) continue;
     Promise.resolve()
       .then(() => server.client?.sendRootsListChanged?.())
+      // A server that rejects the roots notification keeps its previous roots.
       .catch(() => {});
   }
 }
@@ -1383,7 +1517,7 @@ async function runToolRefresh(registryKey, live, name, cfg, capabilities) {
     _invalidateMcpToolFieldMemo();
   } catch (error) {
     mcpLog(
-      `[mcp-client] Failed to refresh tools for "${name}": ${scrubMcpConnectionMessage(error?.message || error, cfg)}\n`
+      `[mcp-client] Failed to refresh tools for "${name}": ${scrubMcpConnectionMessage(error?.message || error, cfg, oauthSecrets(live.transport))}\n`
     );
   }
 }
@@ -1419,7 +1553,7 @@ export function _registerMcpServerForTest(scopeId, name, rawTools = [], options
     capabilities,
     liveness: { alive: true, closing: false, closedAt: 0, lastError: '' },
     stderrTail: typeof options.stderrTail === 'function' ? options.stderrTail : () => '',
-    transport: null,
+    transport: options.transport || null,
     client: {
       callTool:
         typeof options.callTool === 'function'