pi-mcp-client 0.4.0 → 0.5.0

package/dist/index.js

@@ -1879,7 +1879,7 @@ function diagnostic(code, context) {
   const target = server ?? "<server>";
   const hints = {
     configuration_invalid: "Check mcpServers in mcp.json / .mcp.json, including inline server options and environment variables. Move options from any top-level pi section into mcpServers.<server>. Reload Pi after editing.",
-    authentication_required: context.oauth ? `Run /mcp login ${target}.` : "Check the Authorization header, or enable mcpServers.<server>.oauth and authenticate with /mcp login <server>.",
+    authentication_required: context.oauth ? `Run /mcp login ${target}.` : `For OAuth, run /mcp login ${target}. If you use an Authorization header, check its credentials instead.`,
     permission_denied: "Check the account's permissions, OAuth scopes, and service access policy.",
     credential_store_unavailable: "Unlock or enable the OS keyring. Linux requires a Secret Service session; there is no plaintext fallback.",
     secret_lookup_failed: "Check the secret helper's availability, login, exit status, and nonempty stdout. The limit is 64 KiB and at most 10 seconds.",
@@ -2121,7 +2121,6 @@ function object(value) {
 }
 var OPTION_FIELDS = [
   "description",
-  "oauth",
   "oauthClientId",
   "oauthScopes",
   "oauthCallbackPort",
@@ -2138,15 +2137,13 @@ function validateOptions(entry, fail) {
     if (entry[key] !== void 0 && (!Array.isArray(entry[key]) || !entry[key].every((x) => typeof x === "string")))
       fail(key);
   }
-  if (entry.oauthClientId !== void 0 && (entry.oauth !== true || typeof entry.oauthClientId !== "string" || !entry.oauthClientId.trim() || entry.oauthClientId.length > 4096 || /[\u0000-\u001f\u007f]/u.test(entry.oauthClientId)))
-    fail("oauthClientId (requires oauth: true and a nonempty client ID)");
-  if (entry.oauthScopes !== void 0 && (entry.oauth !== true || !Array.isArray(entry.oauthScopes) || entry.oauthScopes.length === 0 || entry.oauthScopes.length > 100 || !entry.oauthScopes.every((scope) => typeof scope === "string" && scope.length <= 256 && /^[\x21\x23-\x5b\x5d-\x7e]+$/u.test(scope)) || new Set(entry.oauthScopes).size !== entry.oauthScopes.length))
-    fail("oauthScopes (requires oauth: true and 1\u2013100 unique OAuth scope tokens)");
-  if (entry.oauthCallbackPort !== void 0 && (entry.oauth !== true || !Number.isInteger(entry.oauthCallbackPort) || Number(entry.oauthCallbackPort) < 1 || Number(entry.oauthCallbackPort) > 65535))
-    fail("oauthCallbackPort (requires oauth: true and a port from 1\u201365535)");
-  for (const key of ["oauth", "disabled"]) {
-    if (entry[key] !== void 0 && typeof entry[key] !== "boolean") fail(key);
-  }
+  if (entry.oauthClientId !== void 0 && (typeof entry.oauthClientId !== "string" || !entry.oauthClientId.trim() || entry.oauthClientId.length > 4096 || /[\u0000-\u001f\u007f]/u.test(entry.oauthClientId)))
+    fail("oauthClientId (requires OAuth and a nonempty client ID)");
+  if (entry.oauthScopes !== void 0 && (!Array.isArray(entry.oauthScopes) || entry.oauthScopes.length === 0 || entry.oauthScopes.length > 100 || !entry.oauthScopes.every((scope) => typeof scope === "string" && scope.length <= 256 && /^[\x21\x23-\x5b\x5d-\x7e]+$/u.test(scope)) || new Set(entry.oauthScopes).size !== entry.oauthScopes.length))
+    fail("oauthScopes (requires OAuth and 1\u2013100 unique OAuth scope tokens)");
+  if (entry.oauthCallbackPort !== void 0 && (!Number.isInteger(entry.oauthCallbackPort) || Number(entry.oauthCallbackPort) < 1 || Number(entry.oauthCallbackPort) > 65535))
+    fail("oauthCallbackPort (requires OAuth and a port from 1\u201365535)");
+  if (entry.disabled !== void 0 && typeof entry.disabled !== "boolean") fail("disabled");
   if (entry.timeoutMs !== void 0 && (!Number.isInteger(entry.timeoutMs) || Number(entry.timeoutMs) < 100 || Number(entry.timeoutMs) > 6e5))
     fail("timeoutMs (100\u2013600000)");
   if (entry.protocol !== void 0 && entry.protocol !== "legacy" && entry.protocol !== "auto")
@@ -2176,6 +2173,8 @@ function parseConnections(value, source) {
     const fail = (field) => {
       throw new Error(`${source}: invalid ${field} for server ${name}.`);
     };
+    if (Object.hasOwn(entry, "oauth"))
+      throw new Error(`${source}: remove oauth from server ${name}; HTTP authentication is automatic.`);
     for (const key of Object.keys(entry)) if (!fields.has(key)) fail(key);
     validateOptions(entry, fail);
     if (entry.type !== void 0 && entry.type !== "stdio" && entry.type !== "http")
@@ -2196,7 +2195,7 @@ function parseConnections(value, source) {
       fail("transport (provide exactly one of command or url)");
     if (entry.type === "stdio" && !entry.command || entry.type === "http" && !entry.url)
       fail("type (must match command or url)");
-    if (entry.command && (entry.oauth || entry.headers))
+    if (entry.command && (entry.headers || entry.oauthClientId !== void 0 || entry.oauthScopes !== void 0 || entry.oauthCallbackPort !== void 0))
       fail("HTTP options on stdio transport");
     if (entry.url && (entry.args || entry.cwd || entry.env))
       fail("stdio options on HTTP transport");
@@ -2245,11 +2244,12 @@ async function configTarget(path) {
   }
 }
 async function updateServerConfig(agentDir, cwd, trusted, mutation, validate) {
-  if (mutation.action !== "toggle" && mutation.scope === "project" && !trusted)
+  const scoped = mutation.action === "add" || mutation.action === "remove";
+  if (scoped && mutation.scope === "project" && !trusted)
     throw new ConfigMutationError("Project configuration requires a trusted project. Use global scope or trust the project first.");
   const paths = [join(agentDir, "mcp.json"), ...trusted ? [join(cwd, ".mcp.json")] : []];
   const targets = await Promise.all(paths.map(configTarget));
-  if (mutation.action !== "toggle" && targets.length === 2 && targets[0] === targets[1])
+  if (scoped && targets.length === 2 && targets[0] === targets[1])
     throw new ConfigMutationError("Global and project configuration share a file; separate them before scoped edits.");
   const locks = [...new Set(targets)].sort();
   const locked = async (index) => {
@@ -2258,8 +2258,8 @@ async function updateServerConfig(agentDir, cwd, trusted, mutation, validate) {
     const documents = await Promise.all(targets.map(readJson));
     const parsed = documents.map((document2, index2) => document2 === void 0 ? /* @__PURE__ */ Object.create(null) : parseConfig(document2, paths[index2]));
     const { server } = mutation;
-    let source = mutation.action === "toggle" ? -1 : mutation.scope === "global" ? 0 : 1;
-    if (mutation.action === "toggle") {
+    let source = scoped ? mutation.scope === "global" ? 0 : 1 : -1;
+    if (!scoped) {
       for (const [index2, config2] of parsed.entries()) if (Object.hasOwn(config2, server)) source = index2;
       if (source < 0) throw new ConfigMutationError("Server is no longer configured. Run /mcp reload.");
     }
@@ -2339,12 +2339,15 @@ function resolveServer(config, cwd) {
       throw new Error("MCP URLs must use HTTP(S), without credentials or fragments.");
     result.url = url.href;
   }
-  if (result.oauth && Object.keys(result.headers ?? {}).some(
+  if ((result.oauthClientId !== void 0 || result.oauthScopes !== void 0 || result.oauthCallbackPort !== void 0) && Object.keys(result.headers ?? {}).some(
     (key) => key.toLowerCase() === "authorization"
   ))
     throw new Error("Use OAuth or an Authorization header, not both.");
   return result;
 }
+function usesOAuth(config) {
+  return Boolean(config?.url) && !Object.keys(config?.headers ?? {}).some((name) => name.toLowerCase() === "authorization");
+}
 function fingerprint(value) {
   const canonical = (item) => Array.isArray(item) ? item.map(canonical) : object(item) ? Object.fromEntries(
     Object.keys(item).sort().map((key) => [key, canonical(item[key])])
@@ -2566,7 +2569,7 @@ function searchCapabilities(tools, resources, query, server, limit = DEFAULT_SEA
 }
 
 // src/config-commands.ts
-var ADD_USAGE = "Usage: /mcp add --scope global|project [--replace] [--transport http|stdio] [--header 'Name: value'] [--env KEY=value] [--oauth] [--oauth-client-id ID] [--oauth-scope SCOPE] [--oauth-callback-port PORT] <server> <url> OR <server> -- <command> [args...]. Put options before the server name.";
+var ADD_USAGE = "Usage: /mcp add --scope global|project [--replace] [--transport http|stdio] [--header 'Name: value'] [--env KEY=value] [--oauth-client-id ID] [--oauth-scope SCOPE] [--oauth-callback-port PORT] <server> <url> OR <server> -- <command> [args...]. Put options before the server name.";
 var REMOVE_USAGE = "Usage: /mcp remove --scope global|project <server>. Credentials are retained; log out first if you want to remove them.";
 function commandWords(input) {
   const words = [];
@@ -2627,10 +2630,8 @@ function parseConfigCommand(input) {
       replace = true;
       continue;
     }
-    if (flag === "--oauth" && action === "add") {
-      definition.oauth = true;
-      continue;
-    }
+    if (flag === "--oauth")
+      throw new ConfigMutationError("Remove --oauth; HTTP authentication is automatic.");
     const value = words[index++];
     if (value === void 0 || value.startsWith("--")) fail();
     if (flag === "--scope") {
@@ -2667,7 +2668,7 @@ function parseConfigCommand(input) {
     if (transport === "http") fail();
     definition.command = words[++index];
     definition.args = words.slice(index + 1);
-    if (!definition.command || definition.oauth || definition.oauthClientId || definition.oauthScopes || definition.oauthCallbackPort || definition.headers) fail();
+    if (!definition.command || definition.oauthClientId || definition.oauthScopes || definition.oauthCallbackPort || definition.headers) fail();
   } else {
     if (transport === "stdio" || index + 1 !== words.length || definition.env) fail();
     definition.url = words[index];
@@ -2689,7 +2690,7 @@ function configCommandCompletions(input, servers) {
   const args = /^--scope\s+(global|project)\s+([^\s]*)$/u.exec(rest);
   if (!args) return [];
   const [, scope, partial] = args;
-  const values = action === "remove" ? servers.sort() : ["--replace", "--transport", "--header", "--env", "--oauth", "--oauth-client-id", "--oauth-scope", "--oauth-callback-port"];
+  const values = action === "remove" ? servers.sort() : ["--replace", "--transport", "--header", "--env", "--oauth-client-id", "--oauth-scope", "--oauth-callback-port"];
   return values.filter((value) => value.startsWith(partial)).map((value) => ({
     value: `${action} --scope ${scope} ${value}`,
     label: value
@@ -2777,7 +2778,6 @@ function oauthCallbackHtml(status) {
 }
 
 // src/auth.ts
-var REDIRECT = "http://127.0.0.1:19847/callback";
 function callbackUrl(options = {}) {
   return `http://127.0.0.1:${options.oauthCallbackPort ?? 19847}/callback`;
 }
@@ -2796,7 +2796,7 @@ function parseCallback(value, redirect, state) {
   return params;
 }
 function credentialKey(url, clientId) {
-  return fingerprint({ url, redirect: REDIRECT, clientId });
+  return fingerprint({ url, clientId });
 }
 var credentialEpochs = /* @__PURE__ */ new Map();
 async function credentialStore(url, clientId) {
@@ -2821,6 +2821,17 @@ async function credentialStore(url, clientId) {
     throw failure("credential_store_unavailable", { operation: "auth" });
   }
 }
+function clientMetadata(options) {
+  return {
+    client_name: "Pi MCP Client",
+    redirect_uris: [callbackUrl(options)],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+    application_type: "native",
+    ...options.oauthScopes ? { scope: options.oauthScopes.join(" ") } : {}
+  };
+}
 var OAuthProvider = class {
   constructor(url, store, redirect, clientId, options = {}) {
     this.url = url;
@@ -2828,15 +2839,7 @@ var OAuthProvider = class {
     this.redirect = redirect;
     this.clientId = clientId;
     this.redirectUrl = callbackUrl(options);
-    this.clientMetadata = {
-      client_name: "Pi MCP Client",
-      redirect_uris: [this.redirectUrl],
-      grant_types: ["authorization_code", "refresh_token"],
-      response_types: ["code"],
-      token_endpoint_auth_method: "none",
-      application_type: "native",
-      ...options.oauthScopes ? { scope: options.oauthScopes.join(" ") } : {}
-    };
+    this.clientMetadata = clientMetadata(options);
     this.key = credentialKey(url, clientId);
     this.epoch = credentialEpochs.get(this.key) ?? 0;
     const raw = store.read();
@@ -2876,7 +2879,7 @@ var OAuthProvider = class {
     const stored = Object.hasOwn(this.data.clients, ctx.issuer) ? this.data.clients[ctx.issuer] : void 0;
     if (!this.clientId) {
       const registration = this.data.registrations?.[ctx.issuer];
-      if (this.redirect && stored && ((registration?.redirect ?? REDIRECT) !== this.redirectUrl || registration?.scope !== this.clientMetadata.scope))
+      if (this.redirect && stored && (registration?.redirect !== this.redirectUrl || registration?.scope !== this.clientMetadata.scope))
         return void 0;
       return stored;
     }
@@ -2943,6 +2946,49 @@ var OAuthProvider = class {
     this.save();
   }
 };
+async function connectionAuthProvider(config, storeFactory = credentialStore) {
+  if (!usesOAuth(config)) return void 0;
+  let initialized = false;
+  const create = async () => {
+    const provider = new OAuthProvider(
+      config.url,
+      await storeFactory(config.url, config.oauthClientId),
+      void 0,
+      config.oauthClientId,
+      config
+    );
+    initialized = true;
+    return provider;
+  };
+  let pending;
+  const get = () => pending ??= create();
+  return {
+    redirectUrl: callbackUrl(config),
+    clientMetadata: clientMetadata(config),
+    state: async () => (await get()).state(),
+    clientInformation: async (ctx) => {
+      const info = (await get()).clientInformation(ctx);
+      if (!info) throw failure("authentication_required", { operation: "connect", oauth: true });
+      return info;
+    },
+    saveClientInformation: async (info, ctx) => (await get()).saveClientInformation(info, ctx),
+    tokens: async (ctx) => {
+      try {
+        return (await get()).tokens(ctx);
+      } catch (error) {
+        if (!initialized && !ctx && error instanceof DiagnosticError && error.diagnostic.code === "credential_store_unavailable") return void 0;
+        throw error;
+      }
+    },
+    saveTokens: async (tokens2) => (await get()).saveTokens(tokens2),
+    saveCodeVerifier: async (value) => (await get()).saveCodeVerifier(value),
+    codeVerifier: async () => (await get()).codeVerifier(),
+    redirectToAuthorization: async (url) => (await get()).redirectToAuthorization(url),
+    saveDiscoveryState: async (value) => (await get()).saveDiscoveryState(value),
+    discoveryState: async () => pending ? (await pending).discoveryState() : void 0,
+    invalidateCredentials: async (scope) => (await get()).invalidateCredentials(scope)
+  };
+}
 async function logout(url, store, signal, clientId) {
   let tokens2;
   let client;
@@ -3175,11 +3221,11 @@ ${parameter.description}` : ""}`
   ].join("\n\n");
 }
 function oauthSettings(config, cwd) {
-  const resolved = resolveServer({ url: config.url, oauth: true, oauthClientId: config.oauthClientId }, cwd);
+  const resolved = resolveServer({ url: config.url, oauthClientId: config.oauthClientId }, cwd);
   return { url: resolved.url, clientId: resolved.oauthClientId };
 }
 async function authenticationSummary(config, cwd, storeFactory = credentialStore) {
-  if (!config.oauth) return config.command ? "Server-managed (stdio)" : Object.keys(config.headers ?? {}).length ? "Headers (externally managed)" : "None configured";
+  if (!usesOAuth(config)) return config.command ? "Server-managed (stdio)" : "Headers (externally managed)";
   const method = config.oauthClientId === void 0 ? "OAuth" : "OAuth (pre-registered public client)";
   try {
     const { url, clientId } = oauthSettings(config, cwd);
@@ -3195,8 +3241,8 @@ function inspectServer(name, config, status, authentication) {
     `Server: ${name}`,
     `Transport: ${config.command ? "stdio" : "HTTP"}`,
     `Protocol: ${config.protocol ?? "auto"}`,
-    `OAuth: ${config.oauth ? "enabled" : "disabled"}`,
-    ...config.oauth ? [
+    `OAuth: ${usesOAuth(config) ? "automatic" : "not used"}`,
+    ...usesOAuth(config) ? [
       `Requested scopes: ${config.oauthScopes?.map(line).join(", ") ?? "SDK/server defaults"}`,
       `OAuth callback: http://127.0.0.1:${config.oauthCallbackPort ?? 19847}/callback`
     ] : [],
@@ -3341,7 +3387,7 @@ function waitFor2(promise, signal) {
     if (signal.aborted) abort();
   });
 }
-var connectSdk = async (_name, config, signal, onToolsChanged, onResourcesChanged) => {
+var createSdkConnector = (storeFactory = credentialStore) => async (_name, config, signal, onToolsChanged, onResourcesChanged) => {
   const timeout = config.timeoutMs ?? 15e3;
   const client = new Client(
     { name: "pi-mcp-client", version: "0.1.0" },
@@ -3372,7 +3418,7 @@ var connectSdk = async (_name, config, signal, onToolsChanged, onResourcesChange
     stderr: "pipe"
   }) : new StreamableHTTPClientTransport(new URL(config.url), {
     requestInit: { headers: config.headers },
-    authProvider: config.oauth ? new OAuthProvider(config.url, await credentialStore(config.url, config.oauthClientId), void 0, config.oauthClientId, config) : void 0,
+    authProvider: await connectionAuthProvider(config, storeFactory),
     // Bound HTTP responses (including OAuth), but not established SSE streams.
     // The SDK bounds ordinary MCP requests with their request timeout.
     fetch: async (input, init) => {
@@ -3418,6 +3464,7 @@ var connectSdk = async (_name, config, signal, onToolsChanged, onResourcesChange
     throw error;
   }
 };
+var connectSdk = createSdkConnector();
 var McpRuntime = class {
   constructor(config, cwd, cacheDir, connect = connectSdk) {
     this.config = config;
@@ -3543,7 +3590,7 @@ var McpRuntime = class {
         diagnose(error, {
           server: name,
           operation: "connect",
-          oauth: config.oauth,
+          oauth: usesOAuth(config),
           signal: this.lifetime.signal
         })
       );
@@ -3776,7 +3823,7 @@ var McpRuntime = class {
       this.state(name).error = void 0;
       return result;
     } catch (error) {
-      const value = diagnose(error, { server: name, operation: "read", oauth: config.oauth, signal: combined });
+      const value = diagnose(error, { server: name, operation: "read", oauth: usesOAuth(config), signal: combined });
       this.state(name).error = value;
       throw new DiagnosticError(value);
     }
@@ -3876,7 +3923,7 @@ var McpRuntime = class {
       const value = diagnose(error, {
         server: tool.server,
         operation: "call",
-        oauth: config.oauth,
+        oauth: usesOAuth(config),
         signal
       });
       this.state(tool.server).error = value;
@@ -3974,7 +4021,7 @@ var McpRuntime = class {
     return error instanceof ToolContractError ? diagnostic("tool_changed", { server: name, operation: "search" }) : diagnose(error, {
       server: name,
       operation: "search",
-      oauth: this.config[name]?.oauth,
+      oauth: this.config[name] && usesOAuth(this.config[name]),
       signal: this.lifetime.signal
     });
   }
@@ -4253,7 +4300,7 @@ function formatBlock(text, block, theme) {
   ).join("");
 }
 function formatOutput(text, blocks, theme) {
-  if (!blocks) return formatBlock(text, {}, theme);
+  if (!blocks) return plain(text);
   let cursor = 0;
   let extraBytes = 0;
   let extraLines = 0;
@@ -4449,7 +4496,7 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
           return errorResult(error, {
             server: tool.server,
             operation: "call",
-            oauth: config[tool.server]?.oauth,
+            oauth: usesOAuth(config[tool.server]),
             signal: ctx.signal?.aborted ? ctx.signal : signal
           });
         }
@@ -4501,7 +4548,8 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     const next = new McpRuntime(
       nextConfig,
       ctx.cwd,
-      join4(agentDir, "cache", "pi-mcp-client")
+      join4(agentDir, "cache", "pi-mcp-client"),
+      createSdkConnector(storeFactory)
     );
     const active = new Set(pi.getActiveTools());
     const retained = [...exposure.definitions.values()].filter((tool) => {
@@ -4528,7 +4576,7 @@ Text output is limited to 2000 lines or 50 KiB; larger results are saved to a pr
     configError = void 0;
     try {
       config = await loadConfig(agentDir, ctx.cwd, ctx.isProjectTrusted());
-      runtime = new McpRuntime(config, ctx.cwd, join4(agentDir, "cache", "pi-mcp-client"));
+      runtime = new McpRuntime(config, ctx.cwd, join4(agentDir, "cache", "pi-mcp-client"), createSdkConnector(storeFactory));
       resourceNotifications(runtime, ctx);
     } catch (error) {
       configError = new DiagnosticError(diagnose(error, { operation: "configuration" }));
@@ -4754,7 +4802,7 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
         const result = errorResult(error, {
           server: args.complete?.server ?? args.read?.server ?? args.server,
           operation: hasComplete ? "complete" : hasRead ? "read" : "search",
-          oauth: config[args.complete?.server ?? args.read?.server ?? args.server ?? ""]?.oauth,
+          oauth: usesOAuth(config[args.complete?.server ?? args.read?.server ?? args.server ?? ""]),
           signal: ctx.signal?.aborted ? ctx.signal : signal
         });
         if (args.read) {
@@ -4854,7 +4902,7 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
           return;
         }
         if (action === "logout" && server && !extra.length && Object.hasOwn(config, server)) {
-          if (!config[server].oauth) {
+          if (!usesOAuth(config[server])) {
             if (ctx.hasUI) ctx.ui.notify(
               `${server}: no managed OAuth credentials. Header and server credentials are externally managed; configuration was not changed.`,
               "info"
@@ -4866,7 +4914,7 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
           if (generation !== sessionGeneration)
             throw new CommandUsageError("The Pi session changed during logout.");
           const related = Object.keys(config).filter((name) => {
-            if (!config[name].oauth) return false;
+            if (!usesOAuth(config[name])) return false;
             try {
               const other = oauthSettings(config[name], ctx.cwd);
               return other.url === url && other.clientId === clientId;
@@ -4938,11 +4986,13 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
             throw new CommandUsageError(
               "OAuth requires an interactive session. Use an Authorization header for headless access."
             );
-          if (!config[server].oauth || !config[server].url)
-            throw new CommandUsageError(
-              "Enable oauth in this HTTP server's mcpServers definition in mcp.json first."
-            );
+          if (!config[server].url)
+            throw new CommandUsageError("OAuth login requires an HTTP server; stdio authentication is managed by the server.");
+          if (Object.keys(config[server].headers ?? {}).some((name) => name.toLowerCase() === "authorization"))
+            throw new CommandUsageError("This server uses an Authorization header. Remove it from the server definition before using /mcp login, or keep using header authentication.");
           const { url, clientId } = oauthSettings(config[server], ctx.cwd);
+          const options2 = config[server];
+          const loginRuntime = current();
           const open = async (target) => {
             const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
             const result = await pi.exec(command, [target], { timeout: 5e3 }).catch(() => void 0);
@@ -4954,8 +5004,10 @@ Variables: ${(candidate.variables ?? []).join(", ") || "none"}. Supply known val
           loginController = controller;
           const signal = AbortSignal.any([controller.signal, ...ctx.signal ? [ctx.signal] : []]);
           try {
+            signal.throwIfAborted();
             const store = await storeFactory(url, clientId);
-            const options2 = config[server];
+            if (generation !== sessionGeneration || current() !== loginRuntime)
+              throw failure("cancelled", { server, operation: "auth" });
             const summary = `Requested scopes: ${options2.oauthScopes?.join(", ") ?? "SDK/server defaults"}
 Callback: http://127.0.0.1:${options2.oauthCallbackPort ?? 19847}/callback`;
             if (extra[0] === "--no-browser") {
@@ -4999,8 +5051,8 @@ Opening browser. Esc to cancel.`
               if (!ok)
                 throw authError ?? failure("cancelled", { server, operation: "auth" });
             } else await authenticate(url, open, signal, store, clientId, options2);
-            if (generation !== sessionGeneration) throw failure("cancelled", { server, operation: "auth" });
-            await current().reconnect(server);
+            if (generation !== sessionGeneration || current() !== loginRuntime) throw failure("cancelled", { server, operation: "auth" });
+            await loginRuntime.reconnect(server);
           } finally {
             if (loginController === controller) loginController = void 0;
           }
@@ -5023,7 +5075,7 @@ Opening browser. Esc to cancel.`
           diagnose(error, {
             server,
             operation: ["reload", "get", "enable", "disable", "add", "remove"].includes(action) ? "configuration" : action === "tools" ? "search" : ["login", "logout"].includes(action) ? "auth" : ["subscribe", "unsubscribe"].includes(action) ? "subscribe" : action === "refresh" ? "refresh" : "reconnect",
-            oauth: config[server]?.oauth,
+            oauth: usesOAuth(config[server]),
             signal: ctx.signal
           })
         );

package/docs/authentication.md

@@ -0,0 +1,175 @@
+# Authentication
+
+[Back to the README](../README.md)
+
+You manage authentication through `/mcp login` and `/mcp logout`. The assistant
+can't initiate an OAuth login: only your explicit login command opens the browser.
+For externally managed bearer tokens, use
+[headers and secret commands](configuration.md#secret-commands) instead.
+
+## Sign in with OAuth
+
+Add the HTTP server, then log in:
+
+```text
+/mcp add --scope global slack https://mcp.slack.com/mcp
+/mcp login slack
+```
+
+Login uses the effective server definition (the trusted project override, if
+present; otherwise the global definition) and starts the SDK's OAuth discovery
+and authorization flow. It doesn't change configuration files. Adding a server
+still doesn't connect or open a browser.
+
+HTTP servers use automatic authentication by default:
+
+- Configured Authorization headers take precedence over OAuth.
+- Otherwise, connections reuse stored OAuth tokens when available. The SDK
+  handles authentication challenges and refreshes existing grants.
+- Without a grant, an authentication challenge asks you to run `/mcp login`.
+  Discovery and tool calls never register a new client or open a browser.
+- A missing or locked keyring doesn't block public servers. If the server
+  requires OAuth, an unavailable keyring is an error; no credentials are stored
+  outside the OS credential store.
+
+The `oauth` configuration field and `--oauth` switch aren't supported. Remove
+these from existing definitions and commands; HTTP authentication is automatic.
+
+If the server uses an Authorization header, login asks you to remove that header
+before switching to OAuth; it never replaces existing header credentials.
+Stdio servers manage their own authentication and don't support OAuth login.
+
+The extension supports public clients with dynamic registration or a
+pre-registered client ID. Both use PKCE and a loopback callback at
+`http://127.0.0.1:19847/callback` by default. Normal login opens a local listener
+that your browser must be able to reach.
+
+Authentication times out after two minutes; you can cancel it with Escape in the
+terminal UI. Explicit login always starts a fresh authorization flow, even if a
+refresh token is already stored. The browser callback page identifies **Pi MCP
+Client** and asks you to return to Pi; receiving a callback doesn't yet mean the
+token exchange succeeded.
+
+OAuth tokens and client registrations are stored in the operating system
+credential store, bound to the server URL, configured client ID (if any), and
+authorization-server issuer. There is no plaintext credential fallback. PKCE
+verifiers and callback state stay in memory. Linux requires a working Secret
+Service/keyring session.
+
+### Upgrade from earlier versions
+
+Credentials now use an identity based only on the server URL and optional client
+ID. Earlier credential-store entries aren't migrated or deleted. Run
+`/mcp login <server>` again after upgrading; revoke old grants at the service if
+needed. Changing scopes or the callback port doesn't select a different store.
+
+## Use a pre-registered client
+
+For a server without dynamic registration, register a **public/native** client
+with the service, using the exact callback URL and token endpoint authentication
+method `none`. Then configure its client ID:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauthClientId": "${EXAMPLE_OAUTH_CLIENT_ID}"
+    }
+  }
+}
+```
+
+Run `/mcp reload`, then `/mcp login example`. The configured ID is used for login,
+token refresh, and revocation; the extension never falls back to dynamic
+registration if it is rejected. `/mcp get example` identifies the client as
+pre-registered without printing the ID.
+
+Changing the client ID selects separate credentials and requires a new login.
+Log out before changing or removing the ID if you want to delete its old
+credentials. After the first successful grant, a pre-registered client is pinned
+to its authorization-server issuer. If that issuer changes, verify the server
+configuration before logging out and logging in again to trust the replacement.
+
+## Set scopes and callback ports
+
+Configure scopes and a callback port in the server definition:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauthScopes": ["read", "write"],
+      "oauthCallbackPort": 19848
+    }
+  }
+}
+```
+
+Or set them when adding the server:
+
+```text
+/mcp add --scope global --oauth-scope read --oauth-scope write --oauth-callback-port 19848 example https://mcp.example.com/mcp
+```
+
+The callback becomes `http://127.0.0.1:19848/callback`. Pre-registered clients must
+allow that exact URL. The listener stays bound to loopback; arbitrary callback
+hosts and paths aren't supported. If the port is occupied, choose another port or
+use manual login.
+
+Scopes are case-sensitive OAuth tokens, each up to 256 characters, without spaces,
+quotes, or backslashes. Omit `oauthScopes` to retain SDK/server-driven selection;
+an empty array is rejected. The SDK may also request `offline_access` when the
+service advertises refresh-token support. Requested scopes aren't a guarantee of
+granted permissions or a per-tool permission policy.
+
+After changing these options, run `/mcp reload`, then `/mcp login example`.
+Changing configuration never starts authorization or revokes existing grants.
+Scopes and callback ports don't select separate credential stores: definitions
+sharing a URL and client ID still share credentials. Explicit login renews a
+dynamic registration when its requested options change. `/mcp get example` shows
+the requested scopes and callback address without connecting.
+
+## Sign in remotely or without launching a browser
+
+When Pi runs over SSH, or you don't want it to launch a browser, use:
+
+```text
+/mcp login example --no-browser
+```
+
+1. Open the authorization URL shown in Pi's interactive dialog in your browser.
+2. Complete sign-in. The browser may show a connection error at the loopback
+   callback address; this is expected when the browser and Pi run on different
+   machines.
+3. Copy the full callback URL from the browser's address bar and paste it into
+   the **Callback URL** dialog in Pi, not into chat or a slash command.
+
+Manual login doesn't open a browser or bind a callback port. The extension
+validates the callback address, state, and authorization response before
+exchanging the code. It doesn't write authorization URLs or pasted callbacks to
+session entries, catalogs, notifications, or logs. Treat the callback URL as
+sensitive; your browser history and clipboard may still contain it.
+
+`--no-browser` still requires an interactive UI and an available OS credential
+store. It isn't unattended authentication: print and JSON modes refuse OAuth
+login. Use externally managed bearer headers for unattended access. Confidential
+clients requiring a client secret aren't supported yet.
+
+## Sign out
+
+Run `/mcp logout <server>` to remove stored tokens and client registrations. Logout
+also closes connections and deactivates tools for OAuth servers sharing
+the same URL and configured client ID, since they share credentials. Configuration
+and enabled state stay unchanged. Disabled servers accept logout too. Header and
+server-managed credentials remain untouched.
+
+Local removal happens before a bounded attempt to revoke tokens at the original
+authorization server. The result distinguishes accepted revocation, unsupported
+revocation, and unconfirmed revocation. When revocation isn't confirmed, remove the
+grant at the service if needed. Repeating logout is safe. Other running Pi sessions
+may need to reconnect; logout cannot recall requests already sent to a server.
+
+Removing a server definition doesn't remove its credentials. Log out before
+[removing the definition](commands.md#add-and-remove-servers) if you want both.