@myspec/mcp-server 0.2.0-next.78 → 0.2.0-next.80

package/README.md

@@ -20,12 +20,130 @@ Run with `npx @myspec/mcp-server [command]` (or `myspec-mcp [command]` when inst
 (default)                 Start MCP server over stdio
 serve                     Start MCP server over stdio
 login                     Sign in via browser loopback OAuth
-login --paste             Sign in by pasting a one-time code
+login --paste             Same as login, but never auto-opens a browser
 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
 ```
 
+### Signing in from another device (`--paste`)
+
+`login` opens a browser on this machine and catches the callback on a local
+loopback port. When the browser lives somewhere else — a remote dev box, a
+container, a phone — use `--paste`: the same flow, minus the auto-open.
+
+```bash
+npx -y @myspec/mcp-server login --paste
+```
+
+Open the printed URL wherever you can. If the page cannot reach this CLI, it
+shows a token in a box that looks like `<code>.<state>`. Copy **the whole
+value, including the dot** and paste it back into the terminal. Two traps:
+
+- The page's copy button is labelled "Copy code" and the page URL contains a
+  bare `?code=`. Neither of those bare values works — the CLI rejects them with
+  `Pasted token is missing a state suffix`.
+- The code expires **60 seconds after you finish signing in** — not 60 seconds
+  after the token appears. user-auth starts that clock before redirecting to
+  the page, and the page then spends part of it trying to reach this CLI
+  (instant if the port refuses the connection, but up to the browser's connect
+  timeout if it is filtered). So paste it the moment it appears; a stale one
+  fails with `OAuth code exchange failed: HTTP 401`. The CLI's own deadline is
+  minutes long, which is time to *reach* the token, not to use it.
+
+> **Do not open the sign-in URL on a machine where you do not trust everything
+> else running on it.** The page attempts a callback to `127.0.0.1:<port>` on
+> whichever machine opens the URL, and anything listening on that port can take
+> the one-time code and exchange it for an access **and** refresh token —
+> keeping access until you run `logout`. The CLI prints the same warning with
+> the actual port, before the URL.
+
+### API tokens (unattended setup)
+
+`login` is interactive — it opens a browser. For anything that has to start
+without a person present (a server, a container, a CI job, a shared machine),
+use an API token instead.
+
+**1. Create the token.** In the MySpec webapp, open the avatar menu → **API
+tokens** → **Create token**. Choose the organization it should act in, whether
+it may write or only read, and an expiry. The token is shown **once**; it
+cannot be retrieved afterwards.
+
+**2. Configure it.** Credentials live in two files under `~/.myspec/`, both of
+which the server needs:
+
+`~/.myspec/oauth_creds.json` — the secret, **mode 0600** (the store refuses any
+file readable by group or other):
+
+```json
+{ "apiToken": "msp_pat_…" }
+```
+
+`~/.myspec/settings.json` — which auth server to talk to:
+
+```json
+{ "userAuthUrl": "https://auth.myspec.dev" }
+```
+
+```bash
+chmod 600 ~/.myspec/oauth_creds.json
+```
+
+`accessToken`, `expiresAt` and the discovered service URLs are filled in
+automatically on first use, and an API-token credential needs no `user` block —
+the owner is resolved server-side at exchange.
+
+There is **no environment variable for an API token** — these files are the
+only way to configure one.
+
+**3. Verify it.** The token is exchanged for a short-lived access token on
+every run, so a token that works here works in the server:
+
+```bash
+curl -sS -X POST "https://auth.myspec.dev/api/auth/token/exchange" \
+  -H "x-api-key: msp_pat_…" -w '\n%{http_code}\n'
+```
+
+`200` with an `accessToken` in the body means it is good. Otherwise:
+
+| Status | Meaning |
+|---|---|
+| `401` | Unknown, revoked or expired token — deliberately indistinguishable. Create a new one. |
+| `403` | The token's organization is gone, or its owner is no longer a member of it. Create a token for an organization you belong to. |
+| `429` | Rate limited. `Retry-After` says how long to wait; the body's `scope` says whether the limit was per-address or per-token. |
+
+#### How it differs from `login`
+
+|  | `login` | API token |
+|---|---|---|
+| Needs a browser | Yes | No |
+| Credential rotates | Yes, on every refresh | No |
+| Survives a missed write | No | Yes |
+| Scope | Whatever the session can reach | One organization, fixed at creation |
+| Access | Full | Read-only or read-write, fixed at creation |
+
+An API token's organization and access mode cannot be changed after creation —
+create a new token instead. Expiry *can* be extended, from the same page, and
+doing so does not change the token value, so nothing needs reconfiguring.
+
+#### Rolling back to a refresh token
+
+If a token does not work and you need the deployment running again now:
+
+1. **Delete the `apiToken` field** from `~/.myspec/oauth_creds.json`. Emptying
+   it is not enough and neither is adding a refresh token alongside it: when an
+   `apiToken` is present it is used exclusively, and a rejected one fails the
+   run rather than falling back — silently downgrading to a different identity
+   would be worse than stopping.
+2. Restore the previous credential — restore a backup of the credentials file
+   if you took one, or run `login` again.
+
+Do **not** use `logout` to roll back. It deletes the whole credentials file,
+API token included.
+
+Migrating an existing install off `MYSPEC_REFRESH_TOKEN`? See the
+[migration runbook](../../docs/runbooks/mcp-api-token-migration.md).
+
 ### Active organization
 
 Every MySpec access token carries the slug of one **active organization**, and
@@ -104,7 +222,6 @@ Local state is stored under `~/.myspec/` (alongside the on-disk cache root), spl
 | Variable | Purpose |
 |---|---|
 | `MYSPEC_USER_AUTH_URL` | user-auth base URL (default `https://auth.myspec.dev`). The webapp URL is derived from it; the platform / ai-agent URLs are discovered via the webapp. |
-| `MYSPEC_REFRESH_TOKEN` | Skip file-based credentials; the server mints a fresh access token on first use via this refresh token. The supported way to wire the MCP server up without running `npx @myspec/mcp-server login`. |
 | `MYSPEC_DOWNLOAD_ROOT` | Absolute path used by `read_spec_file` as its on-disk cache root (default: `~/.myspec`). Tools never write outside this root. |
 | `MYSPEC_AI_AGENT_WS_URL` | ai-agent WebSocket URL for `reverse`; skips the webapp discovery call |
 

package/dist/index.js

@@ -29,11 +29,13 @@ var HttpStatusError = class extends Error {
 };
 var BEARER_PATTERN = /Bearer\s+[A-Za-z0-9._\-+/=]+/g;
 var REFRESH_TOKEN_PATTERN = /"refreshToken"\s*:\s*"[^"]+"/g;
+var API_TOKEN_PATTERN = /"apiToken"\s*:\s*"[^"]+"/g;
+var API_TOKEN_VALUE_PATTERN = /\bmsp_pat_[A-Za-z0-9]+/g;
 var ACCESS_TOKEN_PATTERN = /"accessToken"\s*:\s*"[^"]+"/g;
 var SNAKE_TOKEN_PATTERN = /"(access_token|refresh_token|id_token)"\s*:\s*"[^"]+"/g;
 var JWT_PATTERN = /\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g;
 function redactSensitive(value) {
-  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]");
+  return value.replace(BEARER_PATTERN, "Bearer [REDACTED]").replace(REFRESH_TOKEN_PATTERN, '"refreshToken":"[REDACTED]"').replace(API_TOKEN_PATTERN, '"apiToken":"[REDACTED]"').replace(API_TOKEN_VALUE_PATTERN, "[REDACTED_API_TOKEN]").replace(ACCESS_TOKEN_PATTERN, '"accessToken":"[REDACTED]"').replace(SNAKE_TOKEN_PATTERN, (_match, key) => `"${key}":"[REDACTED]"`).replace(JWT_PATTERN, "[REDACTED_JWT]");
 }
 var ConfigError = class extends Error {
   constructor(message) {
@@ -44,6 +46,13 @@ var ConfigError = class extends Error {
 
 // src/auth/oauth-loopback.ts
 var DEFAULT_TIMEOUT_MS = 5 * 6e4;
+function callbackWarning(callbackBase) {
+  return `Note: the sign-in page will try to call back to ${callbackBase}
+on whichever machine opens that URL. Do not open it on a machine where you
+do not trust everything else running on it \u2014 anything listening on that port
+can take the one-time code and exchange it for an access *and* refresh token,
+keeping access until you run \`myspec-mcp logout\`.`;
+}
 var SUCCESS_HTML = "<!doctype html><html><body><h1>Sign-in complete</h1><p>You may close this tab and return to your terminal.</p></body></html>";
 var ERROR_HTML = "<!doctype html><html><body><h1>Sign-in failed</h1><p>Return to your terminal for details.</p></body></html>";
 async function loopbackLogin(opts) {
@@ -67,17 +76,29 @@ async function loopbackLogin(opts) {
       const webappLogin = new URL(`${opts.webappUrl.replace(/\/$/, "")}/auth/cli`);
       webappLogin.searchParams.set("target", loopbackTarget);
       const signInUrl = webappLogin.toString();
+      const remoteBrowser = opts.remoteBrowser ?? !opts.openBrowser;
+      if (remoteBrowser) {
+        logger(callbackWarning(callbackBase));
+      }
       logger(`Open this URL in your browser to sign in:
   ${signInUrl}`);
       if (!opts.disablePasteFallback) {
+        const lead = remoteBrowser ? "Sign in there. If the page shows a token box, copy the whole value" : "If the browser cannot reach this CLI directly, copy the whole token";
         logger(
-          "If the browser cannot reach this CLI directly, paste the code shown on the\n/auth/cli page here and press Enter."
+          `${lead}
+shown in the box \u2014 it looks like \`<code>.<state>\` \u2014 and paste it here,
+then press Enter. (Not the \`code=\` value from the URL.) The code expires
+60 seconds after you finish signing in, and the page spends part of that
+trying to reach this CLI, so paste it the moment it appears.`
         );
       }
       if (opts.openBrowser) {
         opts.openBrowser(signInUrl).catch((err) => {
           const message = err instanceof Error ? err.message : String(err);
           logger(`Failed to open browser automatically: ${message}`);
+          if (!remoteBrowser) {
+            logger(callbackWarning(callbackBase));
+          }
         });
       }
     }
@@ -233,51 +254,6 @@ async function exchangeCode(userAuthUrl, code, fetchImpl) {
   return await response.json();
 }
 
-// src/auth/oauth-paste.ts
-import readline2 from "readline/promises";
-async function pasteLogin(opts) {
-  const fetchImpl = opts.fetchImpl ?? fetch;
-  const now = opts.now ?? Date.now;
-  const logger = opts.logger ?? ((m) => {
-    process.stderr.write(m + "\n");
-  });
-  const signInUrl = `${opts.webappUrl.replace(/\/$/, "")}/auth/cli`;
-  logger("Open this URL in your browser, sign in, and copy the one-time code shown:");
-  logger(`  ${signInUrl}`);
-  const ask = opts.prompt ?? defaultPrompt;
-  const raw = await ask("Paste the one-time code: ");
-  const code = raw.trim();
-  if (!code) {
-    throw new Error("No code provided.");
-  }
-  const response = await fetchImpl(`${opts.userAuthUrl}/api/auth/oauth/exchange`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ code })
-  });
-  if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    throw new HttpStatusError(response.status, body, `OAuth code exchange failed: HTTP ${String(response.status)}`);
-  }
-  const exchanged = await response.json();
-  return {
-    accessToken: exchanged.accessToken,
-    refreshToken: exchanged.refreshToken,
-    expiresAt: now() + exchanged.expiresIn * 1e3,
-    userAuthUrl: opts.userAuthUrl,
-    webappUrl: opts.webappUrl,
-    user: exchanged.user
-  };
-}
-async function defaultPrompt(question) {
-  const rl = readline2.createInterface({ input: process.stdin, output: process.stderr });
-  try {
-    return await rl.question(question);
-  } finally {
-    rl.close();
-  }
-}
-
 // src/auth/credentials-store.ts
 import { promises as fs } from "fs";
 import os from "os";
@@ -310,6 +286,7 @@ function createFileCredentialsStore(paths = {}) {
       return {
         accessToken: oauth.accessToken,
         refreshToken: oauth.refreshToken,
+        apiToken: oauth.apiToken,
         expiresAt: oauth.expiresAt,
         userAuthUrl: settings.userAuthUrl,
         platformUrl: settings.platformUrl,
@@ -334,6 +311,10 @@ function createFileCredentialsStore(paths = {}) {
         {
           accessToken: creds.accessToken,
           refreshToken: creds.refreshToken,
+          // Carried through every save. Omitting it would delete a configured
+          // API token on the first successful exchange, since save rewrites
+          // the whole file.
+          apiToken: creds.apiToken,
           expiresAt: creds.expiresAt,
           user: creds.user
         },
@@ -395,64 +376,39 @@ async function unlinkIfExists(target) {
     }
   }
 }
-var DEFAULT_USER_AUTH_URL = "https://auth.myspec.dev";
-function readEnvRefreshConfig(env = process.env) {
-  if (env.MYSPEC_ACCESS_TOKEN || env.MYSPEC_ACCESS_TOKEN_EXPIRES_AT) {
-    throw new ConfigError(
-      "MYSPEC_ACCESS_TOKEN / MYSPEC_ACCESS_TOKEN_EXPIRES_AT are not supported. The MCP server mints a fresh access token via MYSPEC_REFRESH_TOKEN; unset MYSPEC_ACCESS_TOKEN (and MYSPEC_ACCESS_TOKEN_EXPIRES_AT if set) and provide only MYSPEC_REFRESH_TOKEN."
+function assertNoEnvAccessToken(env = process.env) {
+  if (env.MYSPEC_REFRESH_TOKEN) {
+    process.stderr.write(
+      "myspec-mcp: MYSPEC_REFRESH_TOKEN is set but no longer supported and is being ignored. Set an `apiToken` in ~/.myspec/oauth_creds.json, or run `npx @myspec/mcp-server login`. See docs/runbooks/mcp-api-token-migration.md\n"
     );
   }
-  if (!env.MYSPEC_REFRESH_TOKEN) {
-    return null;
+  if (!env.MYSPEC_ACCESS_TOKEN && !env.MYSPEC_ACCESS_TOKEN_EXPIRES_AT) {
+    return;
   }
-  return {
-    refreshToken: env.MYSPEC_REFRESH_TOKEN,
-    userAuthUrl: env.MYSPEC_USER_AUTH_URL ?? DEFAULT_USER_AUTH_URL
-  };
-}
-function createCompositeCredentialsStore(opts) {
-  const { fileStore, envConfig } = opts;
-  const envRefreshToken = envConfig?.refreshToken;
-  const envUserAuthUrl = envConfig?.userAuthUrl ?? DEFAULT_USER_AUTH_URL;
-  return {
-    path: () => fileStore.path(),
-    async load() {
-      const fromFile = await fileStore.load();
-      if (fromFile) {
-        return fromFile;
-      }
-      if (!envRefreshToken) {
-        return null;
-      }
-      return {
-        accessToken: "",
-        refreshToken: envRefreshToken,
-        expiresAt: 0,
-        userAuthUrl: envUserAuthUrl,
-        user: { id: "env", email: "env@mcp" }
-      };
-    },
-    save(creds) {
-      return fileStore.save(creds);
-    },
-    clear() {
-      return fileStore.clear();
-    },
-    envRefreshToken: () => envRefreshToken,
-    envUserAuthUrl: () => envUserAuthUrl
-  };
+  throw new ConfigError(
+    "MYSPEC_ACCESS_TOKEN / MYSPEC_ACCESS_TOKEN_EXPIRES_AT are not supported. Run `npx @myspec/mcp-server login`, or put a long-lived API token in the `apiToken` field of your credentials file, and unset these variables."
+  );
 }
 function parseOauthCreds(value) {
   if (typeof value !== "object" || value === null) {
     throw new Error("oauth_creds.json is malformed (not an object)");
   }
   const v = value;
-  const accessToken = requireString(v, "accessToken");
-  const refreshToken = requireString(v, "refreshToken");
-  const expiresAt = requireNumber(v, "expiresAt");
+  const refreshToken = optionalString(v, "refreshToken");
+  const apiToken = optionalString(v, "apiToken");
+  if (!refreshToken && !apiToken) {
+    throw new NeedsLoginError(
+      "oauth_creds.json has no apiToken or refreshToken. Run `npx @myspec/mcp-server login` to sign in, or provision an API token."
+    );
+  }
+  const accessToken = optionalString(v, "accessToken") ?? "";
+  const expiresAt = v.expiresAt === void 0 ? 0 : requireNumber(v, "expiresAt");
   const userRaw = v.user;
   if (typeof userRaw !== "object" || userRaw === null) {
-    throw new Error("oauth_creds.json is malformed (missing user)");
+    if (!apiToken) {
+      throw new Error("oauth_creds.json is malformed (missing user)");
+    }
+    return { accessToken, refreshToken, apiToken, expiresAt };
   }
   const userObj = userRaw;
   const user = {
@@ -460,7 +416,17 @@ function parseOauthCreds(value) {
     email: requireString(userObj, "email"),
     name: typeof userObj.name === "string" ? userObj.name : void 0
   };
-  return { accessToken, refreshToken, expiresAt, user };
+  return { accessToken, refreshToken, apiToken, expiresAt, user };
+}
+function optionalString(v, key) {
+  const raw = v[key];
+  if (raw === void 0 || raw === null) {
+    return void 0;
+  }
+  if (typeof raw !== "string") {
+    throw new Error(`Credentials file is malformed (invalid ${key})`);
+  }
+  return raw.length === 0 ? void 0 : raw;
 }
 function parseSettings(value) {
   if (typeof value !== "object" || value === null) {
@@ -497,14 +463,21 @@ var TokenManager = class {
   store;
   fetchImpl;
   now;
-  envFallback;
   cached = null;
   refreshInFlight = null;
+  /**
+   * Set once the exchange endpoint rejects the API token outright.
+   *
+   * The rejection deliberately does not wipe the credential, so without this
+   * every subsequent tool call would re-POST a known-bad token to the endpoint
+   * the server rate-limits as its brute-force control. Latching turns a loop
+   * into one failed request.
+   */
+  apiTokenRejection = 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();
@@ -547,27 +520,20 @@ var TokenManager = class {
     return this.refreshInFlight;
   }
   async doRefresh(creds) {
+    if (creds.apiToken) {
+      if (this.apiTokenRejection) {
+        throw this.apiTokenRejection;
+      }
+      return this.performExchange(creds, creds.apiToken);
+    }
+    if (!creds.refreshToken) {
+      throw new NeedsLoginError(
+        "No credential is configured. Either run `npx @myspec/mcp-server login` to sign in interactively, or add a long-lived API token to the `apiToken` field of your credentials file \u2014 create one in the MySpec webapp under the avatar menu, API tokens."
+      );
+    }
     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;
     }
@@ -578,6 +544,52 @@ var TokenManager = class {
       await this.store.clear();
     }
   }
+  /**
+   * Trades the long-lived API token for a short-lived access token.
+   *
+   * Unlike refresh, nothing here is persisted except the new access token and
+   * its expiry — the API token is unchanged by the exchange, so re-saving it
+   * would be a no-op and expecting a rotated value back would be wrong.
+   */
+  async performExchange(creds, apiToken) {
+    const url = `${creds.userAuthUrl}/api/auth/token/exchange`;
+    const response = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { "x-api-key": apiToken }
+    });
+    if (response.status === 401 || response.status === 403) {
+      const reason = response.status === 403 ? "the token owner no longer has access to its organization" : "the token is invalid, disabled, or expired";
+      const rejection = new ApiTokenRejectedError(
+        `API token exchange failed: ${reason}. Create a new API token in MySpec and write it to the apiToken field of your credentials file.`
+      );
+      this.apiTokenRejection = rejection;
+      throw rejection;
+    }
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      throw new HttpStatusError(
+        response.status,
+        body,
+        `Token exchange failed: HTTP ${String(response.status)}`
+      );
+    }
+    const payload = await response.json().catch(() => null);
+    if (!payload || typeof payload.accessToken !== "string" || typeof payload.expiresIn !== "number") {
+      throw new HttpStatusError(
+        response.status,
+        "",
+        "Token exchange response was malformed."
+      );
+    }
+    const next = {
+      ...creds,
+      accessToken: payload.accessToken,
+      expiresAt: this.now() + payload.expiresIn * 1e3
+    };
+    this.cached = next;
+    await this.store.save(next);
+    return next;
+  }
   async performRefresh(creds) {
     const url = `${creds.userAuthUrl}/api/auth/token/refresh`;
     const response = await this.fetchImpl(url, {
@@ -613,9 +625,11 @@ var TokenManager = class {
 };
 var RefreshRejectedError = class extends NeedsLoginError {
 };
+var ApiTokenRejectedError = class extends ConfigError {
+};
 
 // src/auth/organization.ts
-import readline3 from "readline";
+import readline2 from "readline";
 function readOrgClaim(accessToken) {
   const payload = accessToken.split(".")[1];
   if (payload === void 0) {
@@ -716,7 +730,7 @@ async function promptForOrganization(organizations, deps = {}) {
     output.write(`  ${String(index + 1)}) ${org.name} (${org.slug})
 `);
   });
-  const rl = readline3.createInterface({ input, output });
+  const rl = readline2.createInterface({ input, output });
   try {
     for (; ; ) {
       const answer = await new Promise((resolve3) => {
@@ -823,11 +837,11 @@ async function discoverConfig(opts) {
   } catch {
     throw discoveryError(endpoint, "response is not valid JSON", hint);
   }
-  const platformUrl = optionalString(body.platformUrl);
+  const platformUrl = optionalString2(body.platformUrl);
   if (platformUrl !== void 0) {
     assertHttpUrl(platformUrl, endpoint, hint);
   }
-  const aiAgentMcpReverseUrl = optionalString(body.aiAgentMcpReverseUrl);
+  const aiAgentMcpReverseUrl = optionalString2(body.aiAgentMcpReverseUrl);
   if (aiAgentMcpReverseUrl !== void 0) {
     assertWebSocketUrl(aiAgentMcpReverseUrl, endpoint, hint);
   }
@@ -853,7 +867,7 @@ function fetchConfig(endpoint, token, fetchImpl) {
     headers: { Authorization: `Bearer ${token}` }
   });
 }
-function optionalString(value) {
+function optionalString2(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 function assertHttpUrl(value, endpoint, hint) {
@@ -891,29 +905,35 @@ function discoveryError(endpoint, reason, hint) {
 }
 
 // src/cli/login.ts
+var PASTE_TIMEOUT_MS = 15 * 6e4;
 async function runLogin(options, deps = {}) {
   const config = resolveConfig({ cliUserAuthUrl: options.userAuthUrl });
   const store = deps.store ?? createFileCredentialsStore();
   const log = deps.log ?? ((message) => {
     process.stderr.write(message + "\n");
   });
-  const doLogin = deps.doLogin ?? ((cfg) => options.paste ? pasteLogin(cfg) : loopbackLogin({
-    ...cfg,
-    openBrowser: async (url) => {
-      const mod = await import("open");
-      await mod.default(url);
-    }
-  }));
+  const openBrowser = async (url) => {
+    const mod = await import("open");
+    await mod.default(url);
+  };
+  const loopback = deps.loopback ?? loopbackLogin;
+  const doLogin = deps.doLogin ?? ((cfg) => {
+    return loopback(
+      options.paste ? { ...cfg, remoteBrowser: true, timeoutMs: PASTE_TIMEOUT_MS } : { ...cfg, openBrowser }
+    );
+  });
   const credentials = await doLogin({
     userAuthUrl: config.userAuthUrl,
     webappUrl: config.webappUrl
   });
   const enriched = await discoverAfterLogin(credentials, config.webappUrl, deps.discover, log);
-  await store.save(enriched);
-  log(`Signed in as ${enriched.user.email}.`);
+  const prior = await store.load().catch(() => null);
+  const preserved = prior?.apiToken === void 0 ? enriched : { ...enriched, apiToken: prior.apiToken };
+  await store.save(preserved);
+  log(`Signed in as ${enriched.user?.email ?? "unknown"}.`);
   log(`Credentials saved to ${store.path()}`);
   await ensureActiveOrganization({
-    credentials: enriched,
+    credentials: preserved,
     webappUrl: config.webappUrl,
     requestedSlug: options.org,
     store,
@@ -1046,11 +1066,31 @@ async function runLogout() {
         "Content-Type": "application/json",
         Authorization: `Bearer ${existing.accessToken}`
       },
-      body: JSON.stringify({ refreshToken: existing.refreshToken }),
+      // Only session-derived credentials have a server-side session to end.
+      // An API-token credential has none, so there is nothing to revoke here —
+      // revoking the token itself is done from the MySpec web UI.
+      body: JSON.stringify(
+        existing.refreshToken ? { refreshToken: existing.refreshToken } : {}
+      ),
       signal: AbortSignal.timeout(5e3)
     });
   } catch {
   }
+  if (existing.apiToken) {
+    await store.save({
+      apiToken: existing.apiToken,
+      accessToken: "",
+      expiresAt: 0,
+      userAuthUrl: existing.userAuthUrl,
+      ...existing.platformUrl ? { platformUrl: existing.platformUrl } : {},
+      ...existing.webappUrl ? { webappUrl: existing.webappUrl } : {},
+      ...existing.aiAgentMcpReverseUrl ? { aiAgentMcpReverseUrl: existing.aiAgentMcpReverseUrl } : {}
+    });
+    process.stderr.write(
+      "Signed out. The configured API token was kept \u2014 delete the `apiToken` field in ~/.myspec/oauth_creds.json to remove it.\n"
+    );
+    return;
+  }
   await store.clear();
   process.stderr.write("Signed out and cleared local credentials.\n");
 }
@@ -4735,7 +4775,7 @@ Press Ctrl-C to stop. Auto-reconnect enabled.
       const message = err instanceof Error ? err.message : String(err);
       process.stderr.write(
         `myspec-mcp reverse: cannot obtain access token: ${message}
-Run \`npx @myspec/mcp-server login\` (or set MYSPEC_REFRESH_TOKEN) and try again.
+Run \`npx @myspec/mcp-server login\`, or configure an API token, and try again.
 `
       );
       return;
@@ -5011,7 +5051,9 @@ function printHelp() {
     "  (default)               Start MCP server over stdio",
     "  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 --paste           Same as login, but never auto-opens a browser. Open",
+    "                          the printed URL yourself; if the page cannot reach this",
+    "                          CLI it shows a `<code>.<state>` token to paste back.",
     "  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.",
@@ -5035,10 +5077,7 @@ function printHelp() {
     "",
     "Environment:",
     "  MYSPEC_USER_AUTH_URL    user-auth base URL (default https://auth.myspec.dev)",
-    "  MYSPEC_AI_AGENT_WS_URL  ai-agent WebSocket URL for `reverse` (skips discovery)",
-    "  MYSPEC_REFRESH_TOKEN    Skip file-based credentials; the server mints a",
-    "                          fresh access token on first use via this refresh",
-    "                          token."
+    "  MYSPEC_AI_AGENT_WS_URL  ai-agent WebSocket URL for `reverse` (skips discovery)"
   ];
   process.stderr.write(lines.join("\n") + "\n");
 }
@@ -5146,12 +5185,9 @@ async function runReverseCommand(flags) {
     loadStored = () => Promise.resolve(null);
     persist = void 0;
   } else {
-    const envConfig = readEnvRefreshConfig();
-    const store = createCompositeCredentialsStore({
-      fileStore: createFileCredentialsStore(),
-      envConfig
-    });
-    const tokenManager = new TokenManager({ store, envFallback: envConfig });
+    assertNoEnvAccessToken();
+    const store = createFileCredentialsStore();
+    const tokenManager = new TokenManager({ store });
     getAccessToken = () => tokenManager.getValidAccessToken();
     onAuthFailed = async () => {
       await tokenManager.forceRefresh();
@@ -5218,25 +5254,19 @@ function createPlatformUrlResolver(deps) {
   };
 }
 async function runServe(flags) {
-  const envConfig = readEnvRefreshConfig();
-  const store = createCompositeCredentialsStore({
-    fileStore: createFileCredentialsStore(),
-    envConfig
-  });
+  assertNoEnvAccessToken();
+  const store = createFileCredentialsStore();
   const initial = await store.load();
   if (!initial) {
     process.stderr.write(
-      "myspec-mcp: starting unauthenticated. Run `npx @myspec/mcp-server login` (or set MYSPEC_REFRESH_TOKEN) to enable tools.\n"
+      "myspec-mcp: starting unauthenticated. Run `npx @myspec/mcp-server login`, or configure an API token, to enable tools.\n"
     );
   }
   const config = resolveConfig({
     cliUserAuthUrl: flagString(flags, "user-auth-url"),
     storedUserAuthUrl: initial?.userAuthUrl
   });
-  const tokenManager = new TokenManager({
-    store,
-    envFallback: envConfig
-  });
+  const tokenManager = new TokenManager({ store });
   const client = new PlatformClient({
     resolveBaseUrl: createPlatformUrlResolver({
       store,

package/package.json

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