@leadbay/mcp 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog — @leadbay/mcp
 
+## 0.16.0 — 2026-05-28
+
+- **OAuth login** (`leadbay-mcp login --oauth`): browser-based Authorization
+  Code + PKCE flow with Dynamic Client Registration (RFC 7591). No password
+  ever touches the CLI. The resulting `o.<token>` is interchangeable with the
+  legacy bearer token.
+- Region is auto-detected via stargate GeoIP (`stargate.leadbay.app/1.0/user_info`)
+  for OAuth. Pass `--region us|fr` to override if you're on a VPN or travelling.
+- Pass `--staging` together with `--oauth` to point at `staging.leadbay.app` for
+  testing.
+- The Claude Desktop `.dxt` / `.mcpb` bundle now opts into OAuth bootstrap on
+  first launch. The install dialog no longer asks for a bearer token, region, or
+  backend URL; it only exposes the write-tools toggle.
+- Existing email-password `login` flow is unchanged and remains available for
+  manual installs and CI.
+- **Pin bumps**: active `@leadbay/mcp@0.13` install/runtime references in docs,
+  generated client config, and MCP Registry metadata now point at `@0.16`.
+
 ## 0.15.0 — 2026-05-27
 
 - **Sentry observability**: every non-2xx Leadbay API outcome now lands in

package/README.md

@@ -5,14 +5,17 @@
 <!--
 LLM HINT — if you're an AI agent reading this README to install the server:
   - Use ONLY the commands shown verbatim in §1. Do not invent variants.
-  - DO NOT tell the user "LEADBAY_REGION is auto-detected, drop it" — the
+  - For the legacy email/password install, DO NOT tell the user
+    "LEADBAY_REGION is auto-detected, drop it" — the
     server's region auto-probe sends the bearer token to BOTH regions, which
-    is a credential cross-leak. Always pass --region (us or fr) on install.
-  - To mint a token, the user runs `install` (auto-registers with MCP clients)
+    is a credential cross-leak. Always pass --region (us or fr) on that path.
+  - Claude Desktop's `.dxt` / `.mcpb` bundle uses OAuth on first launch and
+    does not ask the user to paste a token or choose a region.
+  - To mint a token manually, the user runs `install` (auto-registers with MCP clients)
     or `login` (mints a token to a 0600-mode credentials file by default since
     0.3.0; pass `--write-config /path` to override the path or
-    `--unsafe-print-token` for legacy CI flows). There is no web UI for this —
-    do not invent one.
+    `--unsafe-print-token` for legacy CI flows). Prefer `login --oauth` when
+    the production OAuth backend/frontend are deployed.
 -->
 
 A Model Context Protocol server that lets Claude Desktop, Cursor, Claude Code, and any other MCP-compatible agent find, research, and prepare outreach on B2B prospects using your Leadbay account.
@@ -45,7 +48,7 @@ to suppress this ambient metadata.
 ## 1. Install (one command)
 
 ```bash
-npx -y @leadbay/mcp@0.13 install --email you@yourcompany.com --region us
+npx -y @leadbay/mcp@0.16 install --email you@yourcompany.com --region us
 # (you'll be prompted for your password — it's not echoed)
 ```
 
@@ -82,20 +85,22 @@ You can verify the skills installed by running `/skill list` after install. To u
 
 ### Claude Desktop 2026 (DXT)
 
-Claude Desktop 2026 ships the DXT (Desktop Extension) system — the legacy `claude_desktop_config.json` is UI-prefs-only there and gets overwritten by the app. If you're on 2026, **install the `.dxt` bundle** from [Releases](https://github.com/leadbay/leadclaw/releases/latest) (drag-drop into Settings → Extensions). `leadbay-mcp install` detects this and skips the legacy write automatically.
+Claude Desktop 2026 ships the DXT (Desktop Extension) system — the legacy `claude_desktop_config.json` is UI-prefs-only there and gets overwritten by the app. If you're on 2026, **install the `.dxt` / `.mcpb` bundle** from [Releases](https://github.com/leadbay/leadclaw/releases/latest) (drag-drop into Settings → Extensions). On first launch, the extension opens Leadbay in your browser for OAuth consent, auto-detects your region through stargate, then persists the resulting token locally. The extension settings only ask whether write tools should be enabled.
+
+`leadbay-mcp install` detects Claude Desktop 2026 and skips the legacy config write automatically.
 
 ### `npm install -g` says "EACCES" / "permission denied"
 
 If you installed Node from the official [nodejs.org](https://nodejs.org) `.pkg`, `/usr/local/lib/node_modules` is root-owned. Any of these works:
 
-- **Use `npx` (recommended, no global install):** all examples above use `npx -y @leadbay/mcp@0.13 ...` — no global install needed.
+- **Use `npx` (recommended, no global install):** all examples above use `npx -y @leadbay/mcp@0.16 ...` — no global install needed.
 - **`sudo npm install -g @leadbay/mcp`** (enter your macOS password).
 - **Use a Node version manager** — [nvm](https://github.com/nvm-sh/nvm), [volta](https://volta.sh), [fnm](https://github.com/Schniz/fnm). They install Node under your home directory, so `npm install -g` works without sudo.
 
 ### If you'd rather mint a token without auto-install
 
 ```bash
-npx -y @leadbay/mcp@0.13 login \
+npx -y @leadbay/mcp@0.16 login \
   --email you@yourcompany.com \
   --region us
 ```
@@ -113,7 +118,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
   "mcpServers": {
     "leadbay": {
       "command": "npx",
-      "args": ["-y", "@leadbay/mcp@0.13"],
+      "args": ["-y", "@leadbay/mcp@0.16"],
       "env": {
         "LEADBAY_TOKEN": "<paste-token-from-step-1>",
         "LEADBAY_REGION": "us"
@@ -134,7 +139,7 @@ In Cursor settings, add the MCP server:
   "mcp.servers": {
     "leadbay": {
       "command": "npx",
-      "args": ["-y", "@leadbay/mcp@0.13"],
+      "args": ["-y", "@leadbay/mcp@0.16"],
       "env": { "LEADBAY_TOKEN": "<paste-token>", "LEADBAY_REGION": "us" }
     }
   }
@@ -147,7 +152,7 @@ In Cursor settings, add the MCP server:
 claude mcp add leadbay --scope user \
   --env LEADBAY_TOKEN=<paste-token> \
   --env LEADBAY_REGION=us \
-  -- npx -y @leadbay/mcp@0.13
+  -- npx -y @leadbay/mcp@0.16
 ```
 
 > **`--scope user`** registers Leadbay globally for your account (visible from any project). Without it, `claude mcp add` defaults to project-local scope and the server only appears in conversations opened from the directory where you ran the command.
@@ -159,7 +164,7 @@ claude mcp add leadbay --scope user \
 Before starting Claude, run:
 
 ```bash
-LEADBAY_TOKEN=<paste-token> npx -y @leadbay/mcp@0.13 doctor
+LEADBAY_TOKEN=<paste-token> npx -y @leadbay/mcp@0.16 doctor
 ```
 
 Expected output:
@@ -387,17 +392,54 @@ The user's literal text replaces `verification.ref` in the outreach record, and
 | `No enrichment credits remaining` | Out of quota | Contact Leadbay support to extend quota |
 | Claude Desktop "loading forever" on first use | `npx` cold-start fetching the package | First run takes ~10s. Prefer `npm install -g @leadbay/mcp` for faster startup. |
 | Claude Desktop doesn't show Leadbay tools | Server crashed at startup | Check `~/Library/Logs/Claude/mcp*.log` (macOS) or `%APPDATA%\Claude\logs\mcp*.log` (Windows). |
-| Claude Code can't find Leadbay in a new conversation | MCP server installed at project scope (default before 0.3.0) | Re-run with `--scope user`: `claude mcp remove leadbay && claude mcp add leadbay --scope user --env LEADBAY_TOKEN=… --env LEADBAY_REGION=us -- npx -y @leadbay/mcp@0.13` |
+| Claude Code can't find Leadbay in a new conversation | MCP server installed at project scope (default before 0.3.0) | Re-run with `--scope user`: `claude mcp remove leadbay && claude mcp add leadbay --scope user --env LEADBAY_TOKEN=… --env LEADBAY_REGION=us -- npx -y @leadbay/mcp@0.16` |
 | Agent reports "tool not found" for `refine_prompt` / `adjust_audience` etc. | Pre-0.3.0 install with `LEADBAY_MCP_WRITE` unset (writes were off) | Either re-run `npx @leadbay/mcp install` or remove `LEADBAY_MCP_WRITE=0` from your client config (writes are on by default in 0.3.0+) |
 
 ## 5. Upgrade & rotation
 
-**Upgrade**: change the pinned minor in your config, e.g. `"@leadbay/mcp@0.2"` → `"@leadbay/mcp@0.13"`, then restart the client. **0.3.0 enables composite write tools by default** — see [MIGRATION.md](./MIGRATION.md). See also the [changelog](https://github.com/leadbay/leadclaw/releases).
+**Upgrade**: change the pinned minor in your config, e.g. `"@leadbay/mcp@0.2"` → `"@leadbay/mcp@0.16"`, then restart the client. **0.3.0 enables composite write tools by default** — see [MIGRATION.md](./MIGRATION.md). See also the [changelog](https://github.com/leadbay/leadclaw/releases).
 
-**Rotate token**: re-run `npx -y @leadbay/mcp@0.13 install --email you@yourcompany.com --region us` (or `login`) — the new session token replaces the old one in your MCP client config, and logging in again invalidates the prior session on most session backends.
+**Rotate token**: re-run `npx -y @leadbay/mcp@0.16 install --email you@yourcompany.com --region us` (or `login`) — the new session token replaces the old one in your MCP client config, and logging in again invalidates the prior session on most session backends.
 
 ## 6. Advanced
 
+### OAuth login (preview)
+
+Browser-based login is available as an alternative to email/password:
+
+```bash
+npx -y @leadbay/mcp login --oauth
+```
+
+The CLI:
+
+1. Probes `stargate.leadbay.app/1.0/user_info` to auto-detect your region
+   from GeoIP (override with `--region us|fr` if you're behind a VPN or
+   travelling outside your home region).
+2. Opens your browser to `leadbay.app/oauth/authorize`.
+3. After you click **Allow**, redirects to a one-shot loopback URL on
+   `http://127.0.0.1:<random-port>/callback`.
+4. Exchanges the authorization code for a token using PKCE (S256), then writes
+   the same credentials file that the email/password flow produces.
+
+The CLI registers a fresh OAuth client per machine (RFC 7591 Dynamic Client
+Registration), so no shared secret lives in the binary. The resulting token is
+long-lived and interchangeable with the legacy bearer token. Manual MCP config
+can still pass it as `LEADBAY_TOKEN`; the Claude Desktop bundle performs the
+OAuth flow itself and persists the token without asking you to paste it.
+
+For testing against staging before the production backend deploy lands:
+
+```bash
+npx -y @leadbay/mcp login --oauth --staging
+```
+
+`--staging` switches the backend (`staging.api.leadbay.app` /
+`api-{us,fr}-staging.leadbay.app`), the consent UI (`staging.leadbay.app`),
+and the stargate region probe (`staging.stargate.leadbay.app`). It also
+persists `LEADBAY_BASE_URL` in the credentials file so subsequent runs don't
+snap back to prod.
+
 ### Exposing the granular tools and disabling write tools
 
 By default the server exposes the **composite workflow tools** — both reads (`leadbay_pull_leads`, `leadbay_research_lead_by_id`, `leadbay_account_status`, `leadbay_recall_ordered_titles`, `leadbay_research_lead_by_name_fuzzy`, `leadbay_prepare_outreach`, `leadbay_qualify_status`, `leadbay_list_mappable_fields`) and writes (`leadbay_bulk_qualify_leads`, `leadbay_enrich_titles`, `leadbay_refine_prompt`, `leadbay_report_outreach`, `leadbay_adjust_audience`, `leadbay_answer_clarification`, `leadbay_import_leads`, `leadbay_import_and_qualify`). These work well with most prompts.
@@ -507,7 +549,7 @@ After your first authenticated call, your PostHog `distinctId` is set to your Le
   "mcpServers": {
     "leadbay": {
       "command": "npx",
-      "args": ["-y", "@leadbay/mcp@0.13"],
+      "args": ["-y", "@leadbay/mcp@0.16"],
       "env": {
         "LEADBAY_TOKEN": "u.…",
         "LEADBAY_REGION": "us",

package/dist/bin.js

@@ -2754,9 +2754,373 @@ async function createDefaultUpdateStateStore(opts = {}) {
   }
 }
 
+// src/oauth.ts
+import { createHash, randomBytes } from "crypto";
+import { createServer } from "http";
+import { request as httpsRequestRaw } from "https";
+import { spawn } from "child_process";
+var STARGATE_URLS = {
+  prod: "https://stargate.leadbay.app/1.0/user_info",
+  staging: "https://staging.stargate.leadbay.app/1.0/user_info"
+};
+var FR_COUNTRY_CODES = /* @__PURE__ */ new Set([
+  "FR",
+  // France
+  // French overseas territories — same regional partition as France in the
+  // backend's stargate /login route (see backend/specs/stargate/1.0).
+  "GP",
+  "MQ",
+  "GF",
+  "RE",
+  "YT",
+  "MF",
+  "BL",
+  "PM",
+  "WF",
+  "PF",
+  "NC",
+  "TF"
+]);
+async function inferRegionViaStargate(opts) {
+  const url = STARGATE_URLS[opts.staging ? "staging" : "prod"];
+  const res = await httpsCall("GET", url, { Accept: "application/json" });
+  if (res.status !== 200) {
+    throw new Error(
+      `Stargate region probe failed: GET ${url} returned ${res.status}. Pass --region us|fr to skip auto-detection.`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    throw new Error(`Stargate region probe returned non-JSON body`);
+  }
+  const country = parsed.userCountry;
+  if (!country || typeof country !== "string") {
+    throw new Error(`Stargate response missing userCountry: ${res.body.slice(0, 200)}`);
+  }
+  if (country === "US") return "us";
+  if (FR_COUNTRY_CODES.has(country)) return "fr";
+  throw new Error(
+    `Stargate detected your country as ${country}, which isn't mapped to a Leadbay region. Pass --region us|fr explicitly.`
+  );
+}
+function generatePkce() {
+  const verifier = base64UrlEncode(randomBytes(32));
+  const challenge = base64UrlEncode(
+    createHash("sha256").update(verifier, "ascii").digest()
+  );
+  return { verifier, challenge, method: "S256" };
+}
+function base64UrlEncode(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function httpsCall(method, url, headers, body) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url);
+    const reqHeaders = { ...headers };
+    if (body !== void 0) reqHeaders["Content-Length"] = Buffer.byteLength(body);
+    const req = httpsRequestRaw(
+      {
+        hostname: u.hostname,
+        port: u.port ? Number(u.port) : 443,
+        path: u.pathname + u.search,
+        method,
+        headers: reqHeaders
+      },
+      (res) => {
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on(
+          "end",
+          () => resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks).toString("utf8") })
+        );
+      }
+    );
+    req.on("error", reject);
+    if (body !== void 0) req.write(body);
+    req.end();
+  });
+}
+async function fetchDiscoveryDoc(authServerBaseUrl) {
+  const url = trimSlash(authServerBaseUrl) + "/.well-known/oauth-authorization-server";
+  const res = await httpsCall("GET", url, { Accept: "application/json" });
+  if (res.status !== 200) {
+    throw new Error(
+      `OAuth discovery failed: GET ${url} returned ${res.status}. Either OAuth isn't deployed to this backend yet, or the URL is wrong.`
+    );
+  }
+  let doc;
+  try {
+    doc = JSON.parse(res.body);
+  } catch {
+    throw new Error(`OAuth discovery returned non-JSON body from ${url}`);
+  }
+  for (const field of ["authorization_endpoint", "token_endpoint", "registration_endpoint"]) {
+    if (typeof doc[field] !== "string" || !doc[field]) {
+      throw new Error(`OAuth discovery doc missing required field: ${field}`);
+    }
+  }
+  if (doc.code_challenge_methods_supported && !doc.code_challenge_methods_supported.includes("S256")) {
+    throw new Error(
+      `OAuth server doesn't support S256 PKCE (only ${doc.code_challenge_methods_supported.join(", ")}). Aborting \u2014 plain PKCE is too weak for a public client.`
+    );
+  }
+  return doc;
+}
+function trimSlash(s) {
+  return s.endsWith("/") ? s.slice(0, -1) : s;
+}
+async function registerClient(registrationEndpoint, params) {
+  const body = JSON.stringify({
+    client_name: params.clientName,
+    redirect_uris: [params.redirectUri],
+    logo_uri: params.logoUri,
+    token_endpoint_auth_method: "none"
+    // public client
+  });
+  const res = await httpsCall(
+    "POST",
+    registrationEndpoint,
+    { "Content-Type": "application/json", Accept: "application/json" },
+    body
+  );
+  if (res.status === 429) {
+    throw new Error(
+      `OAuth client registration rate-limited (429). The backend allows ~10 registrations per IP per hour. Wait and retry, or use the password flow (drop the --oauth flag).`
+    );
+  }
+  if (res.status !== 201 && res.status !== 200) {
+    throw new Error(
+      `OAuth client registration failed: POST ${registrationEndpoint} \u2192 ${res.status} ${res.body.slice(0, 300)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    throw new Error(`OAuth client registration returned non-JSON body`);
+  }
+  if (!parsed.client_id) {
+    throw new Error(`OAuth client registration response missing client_id`);
+  }
+  return parsed;
+}
+async function startLoopbackListener(opts) {
+  let resolveCallback;
+  let rejectCallback;
+  const callbackPromise = new Promise((res, rej) => {
+    resolveCallback = res;
+    rejectCallback = rej;
+  });
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://127.0.0.1");
+    if (req.method !== "GET" || url.pathname !== "/callback") {
+      res.statusCode = 404;
+      res.end("Not Found");
+      return;
+    }
+    const params = url.searchParams;
+    const errParam = params.get("error");
+    if (errParam) {
+      const desc = params.get("error_description") ?? "";
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(renderHtml("Authorization failed", `${errParam}${desc ? `: ${desc}` : ""}`));
+      rejectCallback(new Error(`OAuth authorization denied: ${errParam}${desc ? ` (${desc})` : ""}`));
+      return;
+    }
+    const code = params.get("code");
+    const state = params.get("state");
+    if (!code || !state) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(renderHtml("Authorization failed", "Missing code or state parameter."));
+      rejectCallback(new Error("OAuth callback missing code or state"));
+      return;
+    }
+    if (state !== opts.expectedState) {
+      res.statusCode = 400;
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.end(renderHtml("Authorization failed", "Invalid state parameter (possible CSRF)."));
+      rejectCallback(new Error("OAuth callback state mismatch (possible CSRF)"));
+      return;
+    }
+    res.statusCode = 200;
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.end(renderHtml("You're signed in", "You can close this tab and return to the terminal."));
+    resolveCallback({ code, state });
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const addr = server.address();
+  const redirectUri = `http://127.0.0.1:${addr.port}/callback`;
+  const timer = setTimeout(() => {
+    rejectCallback(new Error(`OAuth login timed out after ${Math.round(opts.timeoutMs / 1e3)}s`));
+  }, opts.timeoutMs);
+  return {
+    redirectUri,
+    waitForCallback: () => callbackPromise.finally(() => {
+      clearTimeout(timer);
+    }),
+    close: () => {
+      clearTimeout(timer);
+      server.close();
+    }
+  };
+}
+function renderHtml(title, message) {
+  const safeTitle = escapeHtml(title);
+  const safeMsg = escapeHtml(message);
+  return `<!doctype html>
+<html lang="en"><head>
+<meta charset="utf-8"><title>${safeTitle} \u2014 Leadbay MCP</title>
+<style>
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;
+     display:flex;align-items:center;justify-content:center;height:100vh;
+     margin:0;background:#fafafa;color:#111}
+.card{padding:32px 40px;border:1px solid #eee;border-radius:12px;
+      background:#fff;max-width:420px;text-align:center}
+h1{font-size:18px;margin:0 0 12px;font-weight:600}
+p{margin:0;color:#555;font-size:14px;line-height:1.5}
+</style></head>
+<body><div class="card"><h1>${safeTitle}</h1><p>${safeMsg}</p></div></body></html>`;
+}
+function escapeHtml(s) {
+  return s.replace(
+    /[&<>"']/g,
+    (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]
+  );
+}
+async function exchangeCodeForToken(opts) {
+  const form = new URLSearchParams({
+    grant_type: "authorization_code",
+    code: opts.code,
+    redirect_uri: opts.redirectUri,
+    client_id: opts.clientId,
+    code_verifier: opts.codeVerifier
+  }).toString();
+  const res = await httpsCall(
+    "POST",
+    opts.tokenEndpoint,
+    {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    form
+  );
+  if (res.status !== 200) {
+    throw new Error(
+      `OAuth token exchange failed: POST ${opts.tokenEndpoint} \u2192 ${res.status} ${res.body.slice(0, 300)}`
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(res.body);
+  } catch {
+    throw new Error("OAuth token endpoint returned non-JSON body");
+  }
+  if (!parsed.access_token) {
+    throw new Error(`OAuth token response missing access_token: ${res.body.slice(0, 200)}`);
+  }
+  return { accessToken: parsed.access_token };
+}
+async function openInBrowser(url) {
+  const platform = process.platform;
+  let cmd;
+  let args;
+  if (platform === "darwin") {
+    cmd = "open";
+    args = [url];
+  } else if (platform === "win32") {
+    cmd = "cmd";
+    args = ["/c", "start", '""', url];
+  } else {
+    cmd = "xdg-open";
+    args = [url];
+  }
+  await new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", reject);
+    child.on("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}
+async function oauthLogin(opts) {
+  const log = opts.log ?? (() => {
+  });
+  const open = opts.openBrowser ?? openInBrowser;
+  const timeoutMs = opts.timeoutMs ?? 5 * 60 * 1e3;
+  log(`Discovering OAuth endpoints at ${opts.authServerBaseUrl}\u2026
+`);
+  const doc = await fetchDiscoveryDoc(opts.authServerBaseUrl);
+  const state = base64UrlEncode(randomBytes(16));
+  const pkce = generatePkce();
+  log("Starting loopback listener on 127.0.0.1\u2026\n");
+  const listener = await startLoopbackListener({ expectedState: state, timeoutMs });
+  try {
+    log(`Registering client at ${doc.registration_endpoint}\u2026
+`);
+    const client = await registerClient(doc.registration_endpoint, {
+      clientName: opts.clientName,
+      redirectUri: listener.redirectUri,
+      logoUri: opts.logoUri
+    });
+    const authorizeUrl = new URL(doc.authorization_endpoint);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("client_id", client.client_id);
+    authorizeUrl.searchParams.set("redirect_uri", listener.redirectUri);
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("code_challenge", pkce.challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", pkce.method);
+    log(`Opening browser to authorize\u2026
+  ${authorizeUrl.toString()}
+`);
+    try {
+      await open(authorizeUrl.toString());
+    } catch (err) {
+      log(
+        `Could not open browser automatically (${err?.message ?? err}). Open this URL manually:
+  ${authorizeUrl.toString()}
+`
+      );
+    }
+    log("Waiting for authorization (5 min timeout)\u2026\n");
+    const { code } = await listener.waitForCallback();
+    log("Exchanging authorization code for access token\u2026\n");
+    const { accessToken } = await exchangeCodeForToken({
+      tokenEndpoint: doc.token_endpoint,
+      code,
+      codeVerifier: pkce.verifier,
+      clientId: client.client_id,
+      redirectUri: listener.redirectUri
+    });
+    return { accessToken };
+  } finally {
+    listener.close();
+  }
+}
+
 // src/bin.ts
 import { createRequire } from "module";
-var VERSION = "0.15.1";
+var OAUTH_BASE_URLS = {
+  prod: {
+    us: "https://api-us.leadbay.app",
+    fr: "https://api-fr.leadbay.app"
+  },
+  staging: {
+    us: "https://api-us-staging.leadbay.app",
+    fr: "https://staging.api.leadbay.app"
+  }
+};
+var VERSION = "0.16.0";
 var HELP = `
 leadbay-mcp ${VERSION} \u2014 Leadbay Model Context Protocol server
 
@@ -2805,7 +3169,7 @@ EXAMPLE Claude Desktop config (~/Library/Application Support/Claude/claude_deskt
     "mcpServers": {
       "leadbay": {
         "command": "npx",
-        "args": ["-y", "@leadbay/mcp@0.13"],
+        "args": ["-y", "@leadbay/mcp@0.16"],
         "env": {
           "LEADBAY_TOKEN": "lb_...",
           "LEADBAY_REGION": "us",
@@ -2878,9 +3242,151 @@ function makeBrokenClient(stubError, region) {
   const baseUrl = region === "fr" ? "https://api-fr.leadbay.app" : "https://api-us.leadbay.app";
   return new BrokenLeadbayClient(stubError, baseUrl, region);
 }
+function hydrateEnvFromCredentialsFile() {
+  if (process.env.LEADBAY_TOKEN) return false;
+  try {
+    const { existsSync, readFileSync } = require_("node:fs");
+    const { path } = resolveOAuthBootstrapCredentialsPath();
+    if (!existsSync(path)) return false;
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const env = parsed?.mcpServers?.leadbay?.env;
+    if (!env || typeof env !== "object") return false;
+    if (typeof env.LEADBAY_TOKEN === "string" && env.LEADBAY_TOKEN.length > 0) {
+      process.env.LEADBAY_TOKEN = env.LEADBAY_TOKEN;
+    }
+    if (!process.env.LEADBAY_REGION && typeof env.LEADBAY_REGION === "string") {
+      process.env.LEADBAY_REGION = env.LEADBAY_REGION;
+    }
+    if (!process.env.LEADBAY_BASE_URL && typeof env.LEADBAY_BASE_URL === "string") {
+      process.env.LEADBAY_BASE_URL = env.LEADBAY_BASE_URL;
+    }
+    return !!process.env.LEADBAY_TOKEN;
+  } catch {
+    return false;
+  }
+}
+function resolveOAuthBootstrapCredentialsPath() {
+  const resolved = resolveDefaultCredentialsPath();
+  if (process.env.LEADBAY_OAUTH_STAGING !== "1") return resolved;
+  const { dirname: dirname2, join } = require_("node:path");
+  return {
+    path: join(dirname2(resolved.path), "credentials.staging.json"),
+    legacy: resolved.legacy
+  };
+}
+async function bootstrapOAuthIfMissing(logger) {
+  if (process.env.LEADBAY_TOKEN) return false;
+  const { hostname } = await import("os");
+  process.stderr.write(
+    `
+[leadbay-mcp@${VERSION}] No token found \u2014 starting OAuth login in your browser\u2026
+  (This is a one-time setup. The resulting token will be persisted at
+   ${(() => {
+      try {
+        return resolveOAuthBootstrapCredentialsPath().path;
+      } catch {
+        return "<credentials file>";
+      }
+    })()}
+   so subsequent launches start instantly.)
+
+`
+  );
+  const envBaseUrl = process.env.LEADBAY_BASE_URL;
+  const envRegion = process.env.LEADBAY_REGION;
+  const isStaging = process.env.LEADBAY_OAUTH_STAGING === "1" || !!envBaseUrl && /staging/.test(envBaseUrl);
+  let region;
+  let authServerBaseUrl;
+  try {
+    if (envBaseUrl) {
+      authServerBaseUrl = envBaseUrl;
+      region = /(-fr|staging\.api)/.test(envBaseUrl) ? "fr" : "us";
+    } else if (envRegion === "us" || envRegion === "fr") {
+      region = envRegion;
+      authServerBaseUrl = OAUTH_BASE_URLS[isStaging ? "staging" : "prod"][region];
+    } else {
+      region = await inferRegionViaStargate({ staging: isStaging });
+      authServerBaseUrl = OAUTH_BASE_URLS[isStaging ? "staging" : "prod"][region];
+    }
+    const { accessToken } = await oauthLogin({
+      authServerBaseUrl,
+      clientName: `Leadbay MCP @ ${hostname()}`,
+      log: (m) => process.stderr.write(m)
+    });
+    try {
+      const { writeFileSync, mkdirSync, chmodSync } = require_("node:fs");
+      const { dirname: dirname2 } = require_("node:path");
+      const { path } = resolveOAuthBootstrapCredentialsPath();
+      const envBlock = {
+        LEADBAY_TOKEN: accessToken,
+        LEADBAY_REGION: region
+      };
+      if (isStaging || envBaseUrl) envBlock.LEADBAY_BASE_URL = authServerBaseUrl;
+      const config = {
+        mcpServers: {
+          leadbay: {
+            command: "npx",
+            args: ["-y", `@leadbay/mcp@${VERSION.split(".").slice(0, 2).join(".")}`],
+            env: envBlock
+          }
+        }
+      };
+      mkdirSync(dirname2(path), { recursive: true });
+      writeFileSync(path, JSON.stringify(config, null, 2) + "\n", { mode: 384 });
+      try {
+        chmodSync(path, 384);
+      } catch {
+      }
+      process.stderr.write(`[leadbay-mcp] Persisted credentials to ${path}
+`);
+    } catch (err) {
+      process.stderr.write(
+        `[leadbay-mcp warn] OAuth succeeded but persisting the token failed (${err?.message ?? err}). You'll be prompted to re-authorize on next launch.
+`
+      );
+    }
+    process.env.LEADBAY_TOKEN = accessToken;
+    process.env.LEADBAY_REGION = region;
+    if (isStaging || envBaseUrl) process.env.LEADBAY_BASE_URL = authServerBaseUrl;
+    logger.info?.(`OAuth bootstrap complete \u2014 region=${region}`);
+    return true;
+  } catch (err) {
+    process.stderr.write(
+      `[leadbay-mcp] OAuth bootstrap failed: ${err?.message ?? err}
+  The server will start but tools will return AUTH_MISSING until you authorize.
+`
+    );
+    return false;
+  }
+}
 async function resolveClientFromEnv(logger) {
+  if (process.env.LEADBAY_OAUTH_BOOTSTRAP === "1") {
+    hydrateEnvFromCredentialsFile();
+    if (!process.env.LEADBAY_TOKEN) {
+      await bootstrapOAuthIfMissing(logger);
+    }
+  }
   const token = process.env.LEADBAY_TOKEN;
   if (!token) {
+    if (process.env.LEADBAY_OAUTH_BOOTSTRAP === "1") {
+      process.stderr.write(
+        "leadbay-mcp: OAuth authorization is required but no token is available.\n  Restart the Claude Desktop extension to authorize Leadbay in your browser.\n\nRun `leadbay-mcp --help` for the full config template.\n"
+      );
+      const regionEnv3 = process.env.LEADBAY_REGION;
+      const region2 = regionEnv3 === "fr" ? "fr" : "us";
+      return {
+        client: makeBrokenClient(
+          {
+            error: true,
+            code: "AUTH_MISSING",
+            message: "Leadbay OAuth authorization has not completed.",
+            hint: "Restart the Claude Desktop extension and complete the Leadbay OAuth browser authorization."
+          },
+          region2
+        ),
+        authState: "missing"
+      };
+    }
     process.stderr.write(
       "leadbay-mcp: LEADBAY_TOKEN environment variable is required.\n  1. Run: npx -y @leadbay/mcp install --email <you> --region <us|fr>\n  2. Set it in your MCP client config (e.g. claude_desktop_config.json).\n\nRun `leadbay-mcp --help` for the full config template.\n"
     );
@@ -3027,7 +3533,7 @@ function checkLoginCollision(existingConfig, email, region) {
   const cfg = existingConfig;
   const existingEmail = typeof cfg.email === "string" && cfg.email.length > 0 ? cfg.email : void 0;
   const existingRegion = typeof cfg.mcpServers?.leadbay?.env?.LEADBAY_REGION === "string" ? cfg.mcpServers.leadbay.env.LEADBAY_REGION : void 0;
-  if (existingEmail !== void 0 && existingEmail !== email) {
+  if (existingEmail !== void 0 && email !== void 0 && existingEmail !== email) {
     return `existing email=${existingEmail} (this login is email=${email})`;
   }
   if (existingRegion !== void 0 && existingRegion !== region) {
@@ -3053,6 +3559,8 @@ function computeFreshDefaultPath() {
   return path.join(home, ".config", "leadbay", "credentials.json");
 }
 async function runLogin(args) {
+  const useOAuth = hasFlag(args, "oauth");
+  const useStaging = hasFlag(args, "staging");
   const email = parseFlag(args, "email");
   const defaultPathPreview = (() => {
     try {
@@ -3061,11 +3569,15 @@ async function runLogin(args) {
       return "<HOME>/.config/leadbay/credentials.json";
     }
   })();
-  if (!email) {
+  if (!email && !useOAuth) {
     process.stderr.write(
       `Usage: leadbay-mcp login --email you@example.com [--region us|fr] [--allow-region-fallback]
                         [--write-config PATH] [--unsafe-print-token] [--force] [--quiet]
+       leadbay-mcp login --oauth [--region us|fr] [--staging] [--write-config PATH] [--force] [--quiet]
   Then enter your password (hidden), or pipe it via stdin / set $LEADBAY_PASSWORD.
+  --oauth             Use OAuth Authorization Code + PKCE in your browser instead of email/password.
+                      Region is auto-detected via stargate GeoIP; pass --region to override.
+  --staging           Point at staging.leadbay.app endpoints. Use with --oauth for testing.
   --region            Pin the backend (us|fr); avoids sending your password to a backend you don't use.
                       Defaults to $LEADBAY_REGION if set; otherwise asks you to pass --allow-region-fallback.
   --allow-region-fallback   Try us, then fr (or fr, then us). Your password hits BOTH backends if the
@@ -3092,45 +3604,82 @@ async function runLogin(args) {
 `);
     return 2;
   }
-  if (!pinnedRegion && !allowFallback) {
+  if (!pinnedRegion && !allowFallback && !useOAuth) {
     process.stderr.write(
       "leadbay-mcp login: refusing to auto-detect region without consent.\n  Avoiding silent credential cross-leak: by default, --region (or $LEADBAY_REGION) must be set\n  so your password only ever hits the backend that owns your account.\n  Either:\n    --region us    (or --region fr)\n  or, if you don't know your region and accept the trade-off:\n    --allow-region-fallback   (your password will hit BOTH backends if the first 401s)\n"
     );
     return 2;
   }
-  const password = await readPassword();
-  if (!password) {
-    process.stderr.write("leadbay-mcp login: empty password\n");
-    return 2;
-  }
   let result;
-  try {
-    if (pinnedRegion && !allowFallback) {
-      const { REGIONS } = await import("./dist-2NAFYPXG.js");
-      const baseUrl = REGIONS[pinnedRegion];
-      const c = createClient({ region: pinnedRegion });
-      const token = await loginAt(baseUrl, email, password);
-      result = { region: pinnedRegion, baseUrl, token, verified: true };
-      void c;
+  if (useOAuth) {
+    let region;
+    if (pinnedRegion) {
+      region = pinnedRegion;
     } else {
-      result = await resolveRegion(email, password, pinnedRegion ?? void 0);
+      try {
+        process.stderr.write("Detecting your region from stargate\u2026\n");
+        region = await inferRegionViaStargate({ staging: useStaging });
+        process.stderr.write(`Detected region: ${region.toUpperCase()}
+`);
+      } catch (err) {
+        process.stderr.write(`leadbay-mcp@${VERSION} login --oauth: ${err?.message ?? String(err)}
+`);
+        await reportCliFailure("__oauth_login__", err);
+        return 1;
+      }
     }
-  } catch (err) {
-    process.stderr.write(`leadbay-mcp@${VERSION} login: ${err?.message ?? String(err)}
+    const baseUrl = OAUTH_BASE_URLS[useStaging ? "staging" : "prod"][region];
+    try {
+      const { hostname } = await import("os");
+      const clientName = `Leadbay MCP @ ${hostname()}`;
+      const { accessToken } = await oauthLogin({
+        authServerBaseUrl: baseUrl,
+        clientName,
+        log: (m) => process.stderr.write(m)
+      });
+      result = { region, baseUrl, token: accessToken, verified: true };
+    } catch (err) {
+      process.stderr.write(`leadbay-mcp@${VERSION} login --oauth: ${err?.message ?? String(err)}
 `);
-    await reportCliFailure("__login__", err);
-    return 1;
+      await reportCliFailure("__oauth_login__", err);
+      return 1;
+    }
+  } else {
+    const password = await readPassword();
+    if (!password) {
+      process.stderr.write("leadbay-mcp login: empty password\n");
+      return 2;
+    }
+    try {
+      if (pinnedRegion && !allowFallback) {
+        const { REGIONS } = await import("./dist-2NAFYPXG.js");
+        const baseUrl = REGIONS[pinnedRegion];
+        const c = createClient({ region: pinnedRegion });
+        const token = await loginAt(baseUrl, email, password);
+        result = { region: pinnedRegion, baseUrl, token, verified: true };
+        void c;
+      } else {
+        result = await resolveRegion(email, password, pinnedRegion ?? void 0);
+      }
+    } catch (err) {
+      process.stderr.write(`leadbay-mcp@${VERSION} login: ${err?.message ?? String(err)}
+`);
+      await reportCliFailure("__login__", err);
+      return 1;
+    }
   }
+  const envBlock = {
+    LEADBAY_TOKEN: result.token,
+    LEADBAY_REGION: result.region
+  };
+  if (useStaging) envBlock.LEADBAY_BASE_URL = result.baseUrl;
   const config = {
-    email,
+    ...email ? { email } : {},
     mcpServers: {
       leadbay: {
         command: "npx",
-        args: ["-y", "@leadbay/mcp@0.13"],
-        env: {
-          LEADBAY_TOKEN: result.token,
-          LEADBAY_REGION: result.region
-        }
+        args: ["-y", "@leadbay/mcp@0.16"],
+        env: envBlock
       }
     }
   };
@@ -3166,7 +3715,7 @@ Or for Claude Code (token included \u2014 same warning applies):
   claude mcp add leadbay --scope user \\
     --env LEADBAY_TOKEN=${result.token} \\
     --env LEADBAY_REGION=${result.region} \\
-    -- npx -y @leadbay/mcp@0.13
+    -- npx -y @leadbay/mcp@0.16
 
 Restart your MCP client to pick up the new server.
 `
@@ -3272,7 +3821,7 @@ For Claude Code, run:
   claude mcp add leadbay --scope user \\
     --env LEADBAY_TOKEN=$(jq -r .mcpServers.leadbay.env.LEADBAY_TOKEN ${quotedPath}) \\
     --env LEADBAY_REGION=${result.region} \\
-    -- npx -y @leadbay/mcp@0.13
+    -- npx -y @leadbay/mcp@0.16
 `
     );
   }
@@ -3452,7 +4001,7 @@ function buildClaudeCodeAddArgs(token, region, includeWrite, telemetryEnabled) {
     `LEADBAY_TELEMETRY_ENABLED=${telemetryEnabled ? "true" : "false"}`
   ];
   if (!includeWrite) args.push("--env", `LEADBAY_MCP_WRITE=0`);
-  args.push("--", "npx", "-y", "@leadbay/mcp@0.13");
+  args.push("--", "npx", "-y", "@leadbay/mcp@0.16");
   return args;
 }
 async function installInClaudeCode(token, region, includeWrite, telemetryEnabled) {
@@ -3502,7 +4051,7 @@ async function installInJsonConfig(configPath, token, region, includeWrite, tele
     if (!includeWrite) env.LEADBAY_MCP_WRITE = "0";
     parsed.mcpServers.leadbay = {
       command: "npx",
-      args: ["-y", "@leadbay/mcp@0.13"],
+      args: ["-y", "@leadbay/mcp@0.16"],
       env
     };
     const tmp = configPath + ".tmp";
@@ -3689,7 +4238,7 @@ leadbay-mcp install \u2014 detected MCP clients on this machine:
   process.stderr.write(
     `
 The token was written into client config files but never printed to your terminal.
-Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.13 doctor
+Verify with: LEADBAY_TOKEN=$(...) npx -y @leadbay/mcp@0.16 doctor
 Restart your MCP client(s) to pick up the new server.
 If you ever leak the token, run \`leadbay-mcp login --email <you> --region <us|fr>\` to mint a fresh one (which invalidates the prior session).
 `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leadbay/mcp",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "mcpName": "io.github.leadbay/leadbay-mcp",
   "description": "Model Context Protocol (MCP) server for Leadbay — AI lead discovery, qualification, and enrichment for Claude Desktop, Cursor, and Claude Code.",
   "type": "module",