@myspec/mcp-server 0.1.5-next.75 → 0.1.6-next.77

package/README.md

@@ -21,11 +21,36 @@ Run with `npx @myspec/mcp-server [command]` (or `myspec-mcp [command]` when inst
 serve                     Start MCP server over stdio
 login                     Sign in via browser loopback OAuth
 login --paste             Sign in by pasting a one-time code
-login --provider <google|github|gitlab|linear|atlassian>
+login --org <slug>        Sign in and pin that organization
 logout                    Revoke refresh token and clear local credentials
 reverse --root <dir>      Connect to ai-agent and expose local_fs tools
 ```
 
+### Active organization
+
+Every MySpec access token carries the slug of one **active organization**, and
+both the platform API and the ai-agent require it — a token without it is
+rejected everywhere (`missing required claims (sub, org)` from the platform,
+`MISSING_ORG_CLAIM` from the ai-agent).
+
+`login` pins one for you: automatically when you belong to a single
+organization, and by asking when you belong to several. Pass `--org <slug>` to
+skip the question — required in a non-interactive shell, and the way to switch
+the CLI to a different organization later:
+
+```bash
+npx -y @myspec/mcp-server login --org my-team
+```
+
+The chosen slug is printed at the end of a successful sign-in
+(`Active organization: my-team`).
+
+**Exit codes differ by mode.** Without `--org`, a problem in the organization
+step is a warning and the sign-in still succeeds — the credential is valid and
+you can pin an org later. With `--org`, it is fatal and the CLI exits non-zero,
+because `login --org x && reverse` must not fall through to whichever
+organization happened to already be pinned.
+
 The only URL option is `--user-auth-url <url>` (default `https://auth.myspec.dev`),
 accepted by every command. The webapp URL is derived from it (`auth.` → `app.`,
 `dev-auth.` → `dev-app.`, `localhost:8787` → `localhost:5173`), and the remaining

package/dist/index.js

@@ -491,6 +491,264 @@ function isFsNotFound(err) {
   return typeof err === "object" && err !== null && err.code === "ENOENT";
 }
 
+// src/auth/token-manager.ts
+var EXPIRY_SKEW_MS = 3e4;
+var TokenManager = class {
+  store;
+  fetchImpl;
+  now;
+  envFallback;
+  cached = null;
+  refreshInFlight = null;
+  constructor(deps) {
+    this.store = deps.store;
+    this.fetchImpl = deps.fetchImpl ?? fetch;
+    this.now = deps.now ?? Date.now;
+    this.envFallback = deps.envFallback ?? null;
+  }
+  async getValidAccessToken() {
+    const creds = await this.ensureLoaded();
+    if (creds.expiresAt > this.now() + EXPIRY_SKEW_MS) {
+      return creds.accessToken;
+    }
+    const refreshed = await this.refresh(creds);
+    return refreshed.accessToken;
+  }
+  async getCredentials() {
+    return this.ensureLoaded();
+  }
+  async forceRefresh() {
+    const creds = await this.ensureLoaded();
+    const refreshed = await this.refresh(creds);
+    return refreshed.accessToken;
+  }
+  async clear() {
+    this.cached = null;
+    await this.store.clear();
+  }
+  async ensureLoaded() {
+    if (this.cached) {
+      return this.cached;
+    }
+    const loaded = await this.store.load();
+    if (!loaded) {
+      throw new NeedsLoginError();
+    }
+    this.cached = loaded;
+    return loaded;
+  }
+  async refresh(creds) {
+    if (this.refreshInFlight) {
+      return this.refreshInFlight;
+    }
+    this.refreshInFlight = this.doRefresh(creds).finally(() => {
+      this.refreshInFlight = null;
+    });
+    return this.refreshInFlight;
+  }
+  async doRefresh(creds) {
+    try {
+      return await this.performRefresh(creds);
+    } catch (err) {
+      if (err instanceof RefreshRejectedError && this.envFallback && this.envFallback.refreshToken !== creds.refreshToken) {
+        const bootstrap = {
+          accessToken: "",
+          refreshToken: this.envFallback.refreshToken,
+          expiresAt: 0,
+          userAuthUrl: this.envFallback.userAuthUrl,
+          platformUrl: creds.platformUrl,
+          webappUrl: creds.webappUrl,
+          aiAgentMcpReverseUrl: creds.aiAgentMcpReverseUrl,
+          user: creds.user
+        };
+        try {
+          return await this.performRefresh(bootstrap);
+        } catch (retryErr) {
+          await this.invalidateOnAuthFailure(retryErr);
+          throw retryErr;
+        }
+      }
+      await this.invalidateOnAuthFailure(err);
+      throw err;
+    }
+  }
+  async invalidateOnAuthFailure(err) {
+    if (err instanceof NeedsLoginError) {
+      this.cached = null;
+      await this.store.clear();
+    }
+  }
+  async performRefresh(creds) {
+    const url = `${creds.userAuthUrl}/api/auth/token/refresh`;
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: creds.refreshToken })
+    });
+    if (response.status === 400 || response.status === 401 || response.status === 403 || response.status === 422) {
+      throw new RefreshRejectedError(
+        "Refresh token rejected. Run `npx @myspec/mcp-server login` to sign in again."
+      );
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new HttpStatusError(response.status, body, `Token refresh failed: HTTP ${String(response.status)}`);
+    }
+    const payload = await response.json().catch(() => null);
+    if (!payload || typeof payload.accessToken !== "string" || typeof payload.refreshToken !== "string" || typeof payload.expiresIn !== "number") {
+      throw new NeedsLoginError(
+        "Token refresh response was malformed. Run `npx @myspec/mcp-server login` to sign in again."
+      );
+    }
+    const next = {
+      ...creds,
+      accessToken: payload.accessToken,
+      refreshToken: payload.refreshToken,
+      expiresAt: this.now() + payload.expiresIn * 1e3
+    };
+    this.cached = next;
+    await this.store.save(next);
+    return next;
+  }
+};
+var RefreshRejectedError = class extends NeedsLoginError {
+};
+
+// src/auth/organization.ts
+import readline3 from "readline";
+function readOrgClaim(accessToken) {
+  const payload = accessToken.split(".")[1];
+  if (payload === void 0) {
+    return void 0;
+  }
+  try {
+    const json = Buffer.from(payload, "base64url").toString("utf-8");
+    const claims = JSON.parse(json);
+    const org = claims.org;
+    return typeof org === "string" && org.length > 0 ? org : void 0;
+  } catch {
+    return void 0;
+  }
+}
+var NO_ACTIVE_ORG_HINT = "Your CLI session has no active organization, so the access token is missing the `org` claim that the platform API and ai-agent require. Run `npx @myspec/mcp-server login --org <slug>` to pin one.";
+async function listOrganizations(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const response = await fetchImpl(`${opts.userAuthUrl}/api/auth/organization/list`, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${opts.accessToken}` }
+  });
+  if (!response.ok) {
+    const body2 = await response.text().catch(() => "");
+    throw new HttpStatusError(
+      response.status,
+      body2,
+      `Could not list your organizations: HTTP ${String(response.status)}`
+    );
+  }
+  const body = await response.json().catch(() => null);
+  if (!Array.isArray(body)) {
+    throw new Error("Could not list your organizations: unexpected response shape.");
+  }
+  return body.flatMap((raw) => {
+    const org = raw;
+    if (typeof org.id !== "string" || typeof org.slug !== "string") {
+      return [];
+    }
+    return [
+      {
+        id: org.id,
+        slug: org.slug,
+        name: typeof org.name === "string" ? org.name : org.slug
+      }
+    ];
+  });
+}
+async function setActiveOrganization(opts) {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const response = await fetchImpl(`${opts.userAuthUrl}/api/auth/organization/set-active`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${opts.accessToken}`,
+      "Content-Type": "application/json",
+      Origin: opts.webappUrl
+    },
+    body: JSON.stringify({ organizationId: opts.organizationId })
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    const reason = response.status === 403 ? "that organization may have been deleted, or you are no longer a member" : `HTTP ${String(response.status)}`;
+    throw new HttpStatusError(
+      response.status,
+      body,
+      `Could not switch to the selected organization: ${reason}.`
+    );
+  }
+}
+async function chooseOrganization(organizations, requestedSlug, prompt) {
+  if (organizations.length === 0) {
+    return null;
+  }
+  if (requestedSlug !== void 0) {
+    const wanted = requestedSlug.toLowerCase();
+    const match = organizations.find((org) => org.slug.toLowerCase() === wanted);
+    if (!match) {
+      const slugs = organizations.map((org) => org.slug).join(", ");
+      throw new Error(
+        `You are not a member of an organization with slug "${requestedSlug}". Available: ${slugs}.`
+      );
+    }
+    return match;
+  }
+  const only = organizations[0];
+  if (organizations.length === 1 && only) {
+    return only;
+  }
+  return prompt(organizations);
+}
+async function promptForOrganization(organizations, deps = {}) {
+  const input = deps.input ?? process.stdin;
+  const output = deps.output ?? process.stderr;
+  if (input.isTTY !== true) {
+    return null;
+  }
+  output.write("You belong to several organizations. Which one should the CLI use?\n");
+  organizations.forEach((org, index) => {
+    output.write(`  ${String(index + 1)}) ${org.name} (${org.slug})
+`);
+  });
+  const rl = readline3.createInterface({ input, output });
+  try {
+    for (; ; ) {
+      const answer = await new Promise((resolve3) => {
+        const onClose = () => {
+          resolve3(null);
+        };
+        rl.once("close", onClose);
+        rl.question(`Enter a number [1-${String(organizations.length)}]: `, (value) => {
+          rl.removeListener("close", onClose);
+          resolve3(value);
+        });
+      });
+      if (answer === null) {
+        return null;
+      }
+      const trimmed = answer.trim();
+      const picked = /^\d+$/.test(trimmed) ? organizations[Number.parseInt(trimmed, 10) - 1] : void 0;
+      if (picked) {
+        return picked;
+      }
+      output.write("Not a valid choice.\n");
+    }
+  } finally {
+    rl.close();
+    input.pause();
+  }
+}
+function nonInteractiveOrgHint(organizations) {
+  const slugs = organizations.map((org) => org.slug).join(", ");
+  return `You belong to several organizations and stdin is not interactive, so the CLI cannot ask which one to use. Re-run with \`npx @myspec/mcp-server login --org <slug>\` (available: ${slugs}).`;
+}
+
 // src/config.ts
 function resolveConfig(sources = {}) {
   const env = sources.env ?? process.env;
@@ -654,6 +912,108 @@ async function runLogin(options, deps = {}) {
   await store.save(enriched);
   log(`Signed in as ${enriched.user.email}.`);
   log(`Credentials saved to ${store.path()}`);
+  await ensureActiveOrganization({
+    credentials: enriched,
+    webappUrl: config.webappUrl,
+    requestedSlug: options.org,
+    store,
+    log,
+    deps
+  });
+}
+async function ensureActiveOrganization(args) {
+  const { credentials, webappUrl, requestedSlug, store, log, deps } = args;
+  const currentOrg = readOrgClaim(credentials.accessToken);
+  const alreadyPinned = currentOrg !== void 0 && (requestedSlug === void 0 || sameSlug(requestedSlug, currentOrg));
+  if (alreadyPinned) {
+    log(`Active organization: ${currentOrg}`);
+    return;
+  }
+  const failed = (message) => {
+    if (requestedSlug !== void 0) {
+      throw new ConfigError(message);
+    }
+    log(`Warning: ${message}`);
+  };
+  const listOrgs = deps.listOrgs ?? listOrganizations;
+  const setActiveOrg = deps.setActiveOrg ?? setActiveOrganization;
+  const prompt = deps.prompt ?? promptForOrganization;
+  const refreshTokens = deps.refreshTokens ?? defaultRefreshTokens;
+  let organizations;
+  try {
+    organizations = await listOrgs({
+      userAuthUrl: credentials.userAuthUrl,
+      accessToken: credentials.accessToken,
+      webappUrl
+    });
+  } catch (err) {
+    failed(`${errorMessage(err)} ${orgFallbackHint(currentOrg)}`);
+    return;
+  }
+  if (organizations.length === 0) {
+    failed(
+      `You do not belong to any organization yet, so the CLI cannot obtain a usable access token. Create a workspace at ${webappUrl}/onboarding, then run \`npx @myspec/mcp-server login\` again.`
+    );
+    return;
+  }
+  let target;
+  try {
+    target = await chooseOrganization(organizations, requestedSlug, (orgs) => {
+      return prompt(orgs);
+    });
+  } catch (err) {
+    failed(errorMessage(err));
+    return;
+  }
+  if (!target) {
+    failed(nonInteractiveOrgHint(organizations));
+    return;
+  }
+  let refreshedToken;
+  try {
+    await setActiveOrg({
+      userAuthUrl: credentials.userAuthUrl,
+      accessToken: credentials.accessToken,
+      webappUrl,
+      organizationId: target.id
+    });
+    refreshedToken = await refreshTokens(store);
+  } catch (err) {
+    failed(`${errorMessage(err)} ${orgFallbackHint(currentOrg)}`);
+    return;
+  }
+  const mintedOrg = readOrgClaim(refreshedToken);
+  if (mintedOrg === void 0 || !sameSlug(mintedOrg, target.slug)) {
+    failed(
+      `Switched to "${target.slug}", but the new access token reports ${mintedOrg === void 0 ? "no organization" : `"${mintedOrg}"`}. Try again, or pick another with \`npx @myspec/mcp-server login --org <slug>\`.`
+    );
+    return;
+  }
+  log(`Active organization: ${mintedOrg}`);
+}
+function defaultRefreshTokens(store) {
+  const tokenManager = new TokenManager({ store: keepCredentialsOnFailure(store) });
+  return tokenManager.forceRefresh();
+}
+function keepCredentialsOnFailure(store) {
+  return {
+    load: () => store.load(),
+    save: (creds) => store.save(creds),
+    clear: () => Promise.resolve(),
+    path: () => store.path()
+  };
+}
+function sameSlug(a, b) {
+  return a.toLowerCase() === b.toLowerCase();
+}
+function orgFallbackHint(currentOrg) {
+  if (currentOrg !== void 0) {
+    return `The CLI is still using the "${currentOrg}" organization.`;
+  }
+  return "The saved access token has no `org` claim, so `serve` and `reverse` will be rejected. Re-run `npx @myspec/mcp-server login --org <slug>`.";
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
 }
 async function discoverAfterLogin(credentials, webappUrl, discover = discoverConfig, log = () => void 0) {
   try {
@@ -695,129 +1055,6 @@ async function runLogout() {
   process.stderr.write("Signed out and cleared local credentials.\n");
 }
 
-// src/auth/token-manager.ts
-var EXPIRY_SKEW_MS = 3e4;
-var TokenManager = class {
-  store;
-  fetchImpl;
-  now;
-  envFallback;
-  cached = null;
-  refreshInFlight = null;
-  constructor(deps) {
-    this.store = deps.store;
-    this.fetchImpl = deps.fetchImpl ?? fetch;
-    this.now = deps.now ?? Date.now;
-    this.envFallback = deps.envFallback ?? null;
-  }
-  async getValidAccessToken() {
-    const creds = await this.ensureLoaded();
-    if (creds.expiresAt > this.now() + EXPIRY_SKEW_MS) {
-      return creds.accessToken;
-    }
-    const refreshed = await this.refresh(creds);
-    return refreshed.accessToken;
-  }
-  async getCredentials() {
-    return this.ensureLoaded();
-  }
-  async forceRefresh() {
-    const creds = await this.ensureLoaded();
-    const refreshed = await this.refresh(creds);
-    return refreshed.accessToken;
-  }
-  async clear() {
-    this.cached = null;
-    await this.store.clear();
-  }
-  async ensureLoaded() {
-    if (this.cached) {
-      return this.cached;
-    }
-    const loaded = await this.store.load();
-    if (!loaded) {
-      throw new NeedsLoginError();
-    }
-    this.cached = loaded;
-    return loaded;
-  }
-  async refresh(creds) {
-    if (this.refreshInFlight) {
-      return this.refreshInFlight;
-    }
-    this.refreshInFlight = this.doRefresh(creds).finally(() => {
-      this.refreshInFlight = null;
-    });
-    return this.refreshInFlight;
-  }
-  async doRefresh(creds) {
-    try {
-      return await this.performRefresh(creds);
-    } catch (err) {
-      if (err instanceof RefreshRejectedError && this.envFallback && this.envFallback.refreshToken !== creds.refreshToken) {
-        const bootstrap = {
-          accessToken: "",
-          refreshToken: this.envFallback.refreshToken,
-          expiresAt: 0,
-          userAuthUrl: this.envFallback.userAuthUrl,
-          platformUrl: creds.platformUrl,
-          webappUrl: creds.webappUrl,
-          aiAgentMcpReverseUrl: creds.aiAgentMcpReverseUrl,
-          user: creds.user
-        };
-        try {
-          return await this.performRefresh(bootstrap);
-        } catch (retryErr) {
-          await this.invalidateOnAuthFailure(retryErr);
-          throw retryErr;
-        }
-      }
-      await this.invalidateOnAuthFailure(err);
-      throw err;
-    }
-  }
-  async invalidateOnAuthFailure(err) {
-    if (err instanceof NeedsLoginError) {
-      this.cached = null;
-      await this.store.clear();
-    }
-  }
-  async performRefresh(creds) {
-    const url = `${creds.userAuthUrl}/api/auth/token/refresh`;
-    const response = await this.fetchImpl(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ refreshToken: creds.refreshToken })
-    });
-    if (response.status === 400 || response.status === 401 || response.status === 403 || response.status === 422) {
-      throw new RefreshRejectedError(
-        "Refresh token rejected. Run `npx @myspec/mcp-server login` to sign in again."
-      );
-    }
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      throw new HttpStatusError(response.status, body, `Token refresh failed: HTTP ${String(response.status)}`);
-    }
-    const payload = await response.json().catch(() => null);
-    if (!payload || typeof payload.accessToken !== "string" || typeof payload.refreshToken !== "string" || typeof payload.expiresIn !== "number") {
-      throw new NeedsLoginError(
-        "Token refresh response was malformed. Run `npx @myspec/mcp-server login` to sign in again."
-      );
-    }
-    const next = {
-      ...creds,
-      accessToken: payload.accessToken,
-      refreshToken: payload.refreshToken,
-      expiresAt: this.now() + payload.expiresIn * 1e3
-    };
-    this.cached = next;
-    await this.store.save(next);
-    return next;
-  }
-};
-var RefreshRejectedError = class extends NeedsLoginError {
-};
-
 // src/platform/client.ts
 import { createHash } from "crypto";
 
@@ -3977,7 +4214,7 @@ async function handleList(args, opts) {
   try {
     await walk(realPath, "");
   } catch (err) {
-    return structuredError("list_dir_failed", errorMessage(err));
+    return structuredError("list_dir_failed", errorMessage2(err));
   }
   return structuredOk({ entries, truncated });
 }
@@ -3998,7 +4235,7 @@ async function handleRead(args, opts) {
   try {
     stat2 = await fs4.stat(realPath);
   } catch (err) {
-    return structuredError("stat_failed", errorMessage(err));
+    return structuredError("stat_failed", errorMessage2(err));
   }
   if (!stat2.isFile()) {
     return structuredError("not_a_file", `Not a regular file: ${args.path}`);
@@ -4014,7 +4251,7 @@ async function handleRead(args, opts) {
   try {
     raw = await fs4.readFile(realPath);
   } catch (err) {
-    return structuredError("read_failed", errorMessage(err));
+    return structuredError("read_failed", errorMessage2(err));
   }
   const probe = raw.subarray(0, Math.min(READ_FILE_BINARY_PROBE_BYTES, raw.length));
   if (probe.includes(0)) {
@@ -4221,7 +4458,7 @@ async function nodeGrep(searchRoot, realRoot, pattern, opts) {
   try {
     regex = opts.isRegex ? new RegExp(pattern, opts.caseSensitive ? "" : "i") : new RegExp(escapeRegExp(pattern), opts.caseSensitive ? "" : "i");
   } catch (err) {
-    throw new InvalidRegexError(errorMessage(err));
+    throw new InvalidRegexError(errorMessage2(err));
   }
   const matches = [];
   let truncated = false;
@@ -4295,7 +4532,7 @@ async function nodeGrep(searchRoot, realRoot, pattern, opts) {
 function escapeRegExp(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function errorMessage(err) {
+function errorMessage2(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function mapPathError(err) {
@@ -4308,7 +4545,7 @@ function mapPathError(err) {
   if (err.code === "ENOENT") {
     return structuredError("not_found", "Path does not exist");
   }
-  return structuredError("resolve_failed", errorMessage(err));
+  return structuredError("resolve_failed", errorMessage2(err));
 }
 function mapPackError(err) {
   if (err instanceof PackCacheMissError) {
@@ -4323,7 +4560,7 @@ function mapPackError(err) {
   if (err instanceof AbsolutePathError || err instanceof PathOutsideRootError) {
     return mapPathError(err);
   }
-  return structuredError("pack_failed", errorMessage(err));
+  return structuredError("pack_failed", errorMessage2(err));
 }
 function registerLocalFsTools(server, opts) {
   const packCache = new PackCache();
@@ -4402,7 +4639,7 @@ function registerLocalFsTools(server, opts) {
 `);
       return result;
     } catch (err) {
-      const msg = errorMessage(err);
+      const msg = errorMessage2(err);
       const elapsedMs = Math.round(performance.now() - started);
       process.stdout.write(`[tool] ${name}  -> threw  ${String(elapsedMs)}ms  ${msg}
 `);
@@ -4481,7 +4718,8 @@ async function runReverse(opts) {
   const realRoot = await canonicaliseRoot(opts.root);
   const rootLabel = basename3(realRoot);
   process.stderr.write(
-    `myspec-mcp reverse: granting read access to ${realRoot}Press Ctrl-C to stop. Auto-reconnect enabled.
+    `myspec-mcp reverse: granting read access to ${realRoot}
+Press Ctrl-C to stop. Auto-reconnect enabled.
 `
   );
   let backoffMs = RECONNECT_BACKOFF_INITIAL_MS;
@@ -4502,6 +4740,11 @@ Run \`npx @myspec/mcp-server login\` (or set MYSPEC_REFRESH_TOKEN) and try again
       );
       return;
     }
+    if (readOrgClaim(accessToken) === void 0) {
+      process.stderr.write(`myspec-mcp reverse: ${NO_ACTIVE_ORG_HINT}
+`);
+      return;
+    }
     try {
       outcome = await runOneConnection({
         realRoot,
@@ -4512,9 +4755,16 @@ Run \`npx @myspec/mcp-server login\` (or set MYSPEC_REFRESH_TOKEN) and try again
       });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`myspec-mcp reverse: connect attempt ${String(attempt)} failed: ${message}
-`);
-      outcome = { terminal: false, reason: `connect_error: ${message}`, upMs: 0, code: 0 };
+      process.stderr.write(
+        `myspec-mcp reverse: connect attempt ${String(attempt)} failed: ${message}
+`
+      );
+      outcome = {
+        terminal: false,
+        reason: `connect_error: ${message}`,
+        upMs: 0,
+        code: isTokenRejection(err) ? 4001 : 0
+      };
     }
     if (outcome.upMs >= HEALTHY_CONNECTION_THRESHOLD_MS) {
       backoffMs = RECONNECT_BACKOFF_INITIAL_MS;
@@ -4523,7 +4773,7 @@ Run \`npx @myspec/mcp-server login\` (or set MYSPEC_REFRESH_TOKEN) and try again
     if (outcome.code === 4001) {
       if (opts.onAuthFailed && !authRetried) {
         process.stderr.write(
-          "myspec-mcp reverse: server rejected token (4001); force-refreshing and retrying once...\n"
+          "myspec-mcp reverse: server rejected the token; force-refreshing and retrying once...\n"
         );
         try {
           await opts.onAuthFailed();
@@ -4539,7 +4789,9 @@ Run \`npx @myspec/mcp-server login\` (or set MYSPEC_REFRESH_TOKEN) and try again
         }
       }
       process.stderr.write(
-        "myspec-mcp reverse: token rejected after refresh attempt; run `npx @myspec/mcp-server login` and retry.\n"
+        `myspec-mcp reverse: token rejected after refresh attempt; run \`npx @myspec/mcp-server login\` and retry.
+If you belong to more than one organization: ${NO_ACTIVE_ORG_HINT}
+`
       );
       return;
     }
@@ -4550,6 +4802,9 @@ Run \`npx @myspec/mcp-server login\` (or set MYSPEC_REFRESH_TOKEN) and try again
       );
       return;
     }
+    if (opts.maxAttempts !== void 0 && attempt >= opts.maxAttempts) {
+      return;
+    }
     process.stderr.write(
       `myspec-mcp reverse: reconnecting in ${String(Math.round(backoffMs / 1e3))}s...
 `
@@ -4631,18 +4886,61 @@ async function runOneConnection(opts) {
     });
   });
 }
+var HandshakeError = class extends Error {
+  status;
+  /** Response body, truncated. The agent explains the refusal here. */
+  body;
+  constructor(status, body) {
+    const suffix = body ? ` \u2014 ${body}` : "";
+    super(`WebSocket upgrade rejected: HTTP ${String(status)}${suffix}`);
+    this.name = "HandshakeError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var HANDSHAKE_BODY_LIMIT = 512;
+var TOKEN_REJECTION_PATTERN = /INVALID_TOKEN|TOKEN_EXPIRED|INVALID_ISSUER|missing bearer/i;
+function isTokenRejection(err) {
+  return err instanceof HandshakeError && err.status === 401 && TOKEN_REJECTION_PATTERN.test(err.body);
+}
 function waitForOpen(ws) {
   return new Promise((resolve3, reject) => {
-    const onOpen = () => {
+    const cleanup = () => {
+      ws.removeListener("open", onOpen);
       ws.removeListener("error", onError);
+      ws.removeListener("unexpected-response", onUnexpectedResponse);
+    };
+    const onOpen = () => {
+      cleanup();
       resolve3();
     };
     const onError = (err) => {
-      ws.removeListener("open", onOpen);
+      cleanup();
       reject(err);
     };
+    const onUnexpectedResponse = (request, response) => {
+      cleanup();
+      ws.on("error", () => void 0);
+      const status = response.statusCode ?? 0;
+      const socket = response.socket;
+      let body = "";
+      const settle = () => {
+        request.destroy?.();
+        socket.destroy();
+        reject(new HandshakeError(status, body.trim()));
+      };
+      response.setEncoding("utf-8");
+      response.on("data", (chunk) => {
+        if (body.length < HANDSHAKE_BODY_LIMIT) {
+          body = (body + chunk).slice(0, HANDSHAKE_BODY_LIMIT);
+        }
+      });
+      response.once("end", settle);
+      response.once("error", settle);
+    };
     ws.once("open", onOpen);
     ws.once("error", onError);
+    ws.once("unexpected-response", onUnexpectedResponse);
   });
 }
 function sleep2(ms) {
@@ -4714,6 +5012,9 @@ function printHelp() {
     "  serve                   Start MCP server over stdio",
     "  login                   Sign in via browser (chooser page on the webapp)",
     "  login --paste           Sign in by pasting a one-time code",
+    "  login --org <slug>      Sign in and pin that organization. Tokens only work",
+    "                          when an organization is active; the CLI asks when you",
+    "                          belong to several and this flag is not given.",
     "  logout                  Revoke refresh token and clear local credentials",
     "  reverse --root <dir>    Connect to ai-agent and expose local_fs tools.",
     "                          The agent WebSocket URL is discovered from the webapp",
@@ -4756,6 +5057,12 @@ function readVersion() {
     return "unknown";
   }
 }
+function assertOrgFlagHasValue(flags) {
+  const orgFlag = flags.get("org");
+  if (orgFlag === true || orgFlag === "") {
+    throw new ConfigError("`--org` needs an organization slug, e.g. `--org my-team`.");
+  }
+}
 async function main(argv = process.argv.slice(2)) {
   const { command, flags } = parseArgs(argv);
   switch (command) {
@@ -4766,9 +5073,11 @@ async function main(argv = process.argv.slice(2)) {
       process.stderr.write(readVersion() + "\n");
       return;
     case "login":
+      assertOrgFlagHasValue(flags);
       await runLogin({
         paste: flagBool(flags, "paste"),
-        userAuthUrl: flagString(flags, "user-auth-url")
+        userAuthUrl: flagString(flags, "user-auth-url"),
+        org: flagString(flags, "org")
       });
       return;
     case "logout":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myspec/mcp-server",
-  "version": "0.1.5-next.75",
+  "version": "0.1.6-next.77",
   "description": "MySpec MCP server — exposes MySpec platform projects, files and attachments to MCP-aware clients via OAuth-authenticated access tokens.",
   "type": "module",
   "repository": {