@sutraspaces/mcp-server 1.1.2 → 1.2.0

package/README.md

@@ -11,16 +11,45 @@ npm install -g @sutraspaces/mcp-server
 Or run directly with npx:
 
 ```bash
+# OAuth — opens your browser to log in on first run (recommended)
+npx -y @sutraspaces/mcp-server
+
+# Or with an API token (no browser)
 SUTRA_API_TOKEN="sutra_live_sk_..." npx -y @sutraspaces/mcp-server
 ```
 
-You can get an API token from your Sutra account settings or by contacting support@sutra.co.
+There are two ways to authenticate:
+
+- **OAuth (recommended)** — run the server with no token. It opens your browser, you log in to Sutra and approve access, and the token is cached locally (`~/.sutra/credentials.json`) and refreshed automatically. No copy-pasting keys.
+- **API token** — set `SUTRA_API_TOKEN`. Best for headless/server environments. Get a token from your Sutra account settings (**Settings → Sutra API**) or by contacting support@sutra.co.
+
+If `SUTRA_API_TOKEN` is set, the server uses it and skips OAuth.
+
+### Managing OAuth login
+
+```bash
+npx -y @sutraspaces/mcp-server login    # log in / re-authorize without starting the server
+npx -y @sutraspaces/mcp-server logout   # clear cached credentials
+```
 
 ## Usage
 
 ### Claude Desktop
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`. With OAuth, no token is embedded — the server opens your browser the first time it runs:
+
+```json
+{
+  "mcpServers": {
+    "sutra": {
+      "command": "npx",
+      "args": ["-y", "@sutraspaces/mcp-server"]
+    }
+  }
+}
+```
+
+To use an API token instead, add it under `env`:
 
 ```json
 {
@@ -36,21 +65,30 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+If your client doesn't surface the login prompt on first start, run `npx -y @sutraspaces/mcp-server login` once in a terminal, then start the client.
+
 ### Claude Code
 
 ```bash
+# OAuth (opens browser on first run)
+claude mcp add sutra -- npx -y @sutraspaces/mcp-server
+
+# Or with an API token
 claude mcp add sutra -- env SUTRA_API_TOKEN=sutra_live_sk_... npx -y @sutraspaces/mcp-server
 ```
 
 ### Cursor / Windsurf / Other MCP Clients
 
-Point your MCP client at `npx -y @sutraspaces/mcp-server` with the `SUTRA_API_TOKEN` environment variable set. The server communicates over stdio.
+Point your MCP client at `npx -y @sutraspaces/mcp-server`. The server communicates over stdio. Leave the environment empty to authenticate with OAuth, or set `SUTRA_API_TOKEN` to use a token.
 
 ## Configuration
 
 | Variable | Required | Description |
 |---|---|---|
-| `SUTRA_API_TOKEN` | Yes | Your Sutra Admin API token (`sutra_live_sk_...`) |
+| `SUTRA_API_TOKEN` | No* | Your Sutra Admin API token (`sutra_live_sk_...`). *Required only if not using OAuth. When set, OAuth is skipped. |
+| `SUTRA_OAUTH_ISSUER` | No | OAuth issuer base URL (default: `https://sutra.co`). Must be `https://` (only loopback hosts may use `http://`). Separate from the Admin API URL. |
+| `SUTRA_SCOPES` | No | Space-separated scopes to request during OAuth login (default: all scopes your account can authorize) |
+| `SUTRA_CONFIG_DIR` | No | Directory for cached OAuth credentials (default: `~/.sutra`) |
 | `SUTRA_BASE_URL` | No | Override the API URL (default: `https://api.sutra.co/api/admin/v1`) |
 | `SUTRA_HELP_CENTER_TOKEN` | No | Internal scoped admin key (`sutra_admin_...`) for Lotus Help Center tools |
 | `SUTRA_HELP_CENTER_BASE_URL` | No | Override the Help Center API URL (default: `https://api.sutra.co/api/v4/lotus/help`) |
@@ -200,4 +238,4 @@ These tools are available only when `SUTRA_HELP_CENTER_TOKEN` is set.
 AI Agent → MCP Protocol (stdio) → sutra-mcp → Sutra Admin API → Sutra Platform
 ```
 
-The server is a thin, stateless wrapper. All data flows through the Sutra Admin API with Bearer token authentication. No data is cached or stored locally.
+The server is a thin, stateless wrapper. All data flows through the Sutra Admin API with Bearer token authentication. No Sutra customer data is cached or stored locally. The only thing written to disk is your OAuth credential cache at `~/.sutra/credentials.json` (file mode `600`), used to keep you logged in between runs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sutraspaces/mcp-server",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "MCP server for the Sutra Admin API — manage spaces, members, contacts, content, and more via AI agents",
   "type": "module",
   "main": "src/index.js",
@@ -12,7 +12,8 @@
     "README.md"
   ],
   "scripts": {
-    "start": "node src/index.js"
+    "start": "node src/index.js",
+    "test": "node --test"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
@@ -36,7 +37,7 @@
   "homepage": "https://github.com/lorenzsell/sutra-mcp",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lorenzsell/sutra-mcp.git"
+    "url": "https://github.com/lorenzsell/sutra-mcp.git"
   },
   "bugs": {
     "url": "https://github.com/lorenzsell/sutra-mcp/issues"

package/src/auth/oauth.js

@@ -0,0 +1,470 @@
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { generateCodeVerifier, generateCodeChallenge, generateState } from "./pkce.js";
+import { load, save, clear } from "./store.js";
+
+const LOGIN_TIMEOUT_MS = 300_000; // 5 minutes
+
+// ---------------------------------------------------------------------------
+// URL safety
+// ---------------------------------------------------------------------------
+
+const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+
+/**
+ * Require a URL to be HTTPS (or HTTP only for loopback dev hosts). This is the
+ * boundary that prevents the PKCE verifier, authorization code, and refresh
+ * token from ever being POSTed over plaintext to an attacker.
+ * @param {string} urlString
+ * @param {string} label
+ * @returns {URL}
+ */
+function assertHttpsOrLoopback(urlString, label) {
+  let u;
+  try {
+    u = new URL(urlString);
+  } catch {
+    throw new Error(`${label} is not a valid URL`);
+  }
+  const loopback = LOOPBACK_HOSTNAMES.has(u.hostname);
+  if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback)) {
+    throw new Error(
+      `${label} must use HTTPS (got ${u.protocol}//${u.host}). ` +
+      `Set SUTRA_OAUTH_ISSUER to an https:// URL.`
+    );
+  }
+  return u;
+}
+
+/**
+ * Require an OAuth endpoint to be HTTPS/loopback AND same-origin as the issuer.
+ * Same-origin blocks a tampered or hijacked metadata document from redirecting
+ * the token exchange (and thus the verifier/refresh token) to another host.
+ * @param {string} urlString
+ * @param {string} issuerOrigin
+ * @param {string} label
+ */
+function assertEndpointSafe(urlString, issuerOrigin, label) {
+  const u = assertHttpsOrLoopback(urlString, label);
+  if (u.origin !== issuerOrigin) {
+    throw new Error(
+      `${label} (${u.origin}) is not on the same origin as the issuer ` +
+      `(${issuerOrigin}); refusing to use it.`
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch OAuth server metadata from the well-known endpoint.
+ * Falls back to conventional paths if discovery fails.
+ * @param {string} issuer
+ * @returns {Promise<{ authorization_endpoint: string, token_endpoint: string }>}
+ */
+export async function discoverMetadata(issuer) {
+  const issuerOrigin = assertHttpsOrLoopback(issuer, "SUTRA_OAUTH_ISSUER").origin;
+
+  const validate = (md) => {
+    assertEndpointSafe(md.authorization_endpoint, issuerOrigin, "authorization_endpoint");
+    assertEndpointSafe(md.token_endpoint, issuerOrigin, "token_endpoint");
+    return md;
+  };
+
+  const wellKnown = `${issuer}/.well-known/oauth-authorization-server`;
+  try {
+    const res = await fetch(wellKnown, {
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (res.ok) {
+      const ct = res.headers.get("content-type") ?? "";
+      if (ct.includes("json")) {
+        const data = await res.json();
+        if (data.authorization_endpoint && data.token_endpoint) {
+          return validate(data);
+        }
+      }
+    }
+  } catch (err) {
+    // A validation failure (untrusted endpoint) must propagate, not silently
+    // fall back. Only swallow network/timeout/parse errors.
+    if (err instanceof TypeError === false && /must use HTTPS|same origin/.test(err.message)) {
+      throw err;
+    }
+    // network error or timeout — fall through to defaults
+  }
+  // Fallback to conventional paths (same origin as issuer by construction).
+  return validate({
+    authorization_endpoint: `${issuer}/oauth/authorize`,
+    token_endpoint: `${issuer}/oauth/token`,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Browser opener
+// ---------------------------------------------------------------------------
+
+/**
+ * Open a URL in the system browser. Never throws.
+ * @param {string} url
+ */
+function openBrowser(url) {
+  try {
+    const cmd =
+      process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+        ? "start"
+        : "xdg-open";
+    // On win32 'start' is a shell built-in; needs shell:true
+    spawn(cmd, [url], {
+      detached: true,
+      stdio: "ignore",
+      shell: process.platform === "win32",
+    }).unref();
+  } catch {
+    // Swallow — we still print the URL to stderr
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Loopback HTTP server helpers
+// ---------------------------------------------------------------------------
+
+const SUCCESS_HTML = `<!DOCTYPE html><html><head><meta charset="utf-8">
+<title>Sutra Login</title>
+<style>body{font-family:sans-serif;max-width:480px;margin:80px auto;text-align:center}
+h1{color:#1a7f5a}.check{font-size:64px}</style></head><body>
+<div class="check">&#10003;</div>
+<h1>You are logged in to Sutra</h1>
+<p>You can close this tab and return to your terminal.</p>
+</body></html>`;
+
+const ERROR_HTML = (msg) =>
+  `<!DOCTYPE html><html><head><meta charset="utf-8">
+<title>Sutra Login Error</title>
+<style>body{font-family:sans-serif;max-width:480px;margin:80px auto;text-align:center}
+h1{color:#c0392b}</style></head><body>
+<h1>Login failed</h1>
+<p>${escapeHtml(msg)}</p>
+<p>You can close this tab and check your terminal for details.</p>
+</body></html>`;
+
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Start an ephemeral loopback HTTP server on 127.0.0.1.
+ * Returns the server and its port.
+ * @returns {Promise<{ server: import("node:http").Server, port: number }>}
+ */
+function startCallbackServer() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        reject(new Error("Failed to bind loopback server"));
+        return;
+      }
+      resolve({ server, port: addr.port });
+    });
+    server.on("error", reject);
+  });
+}
+
+/**
+ * Wait for the OAuth callback on the given server.
+ * Resolves with { code, state } or rejects with an Error.
+ * Sends a friendly HTML response to the browser.
+ * @param {import("node:http").Server} server
+ * @param {string} expectedState
+ * @param {number} timeoutMs
+ * @returns {Promise<{ code: string, state: string }>}
+ */
+function waitForCallback(server, expectedState, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      server.close();
+      reject(new Error("Login timed out — no callback received within 5 minutes"));
+    }, timeoutMs);
+
+    server.on("request", (req, res) => {
+      if (settled) {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      // Only handle /callback
+      const url = new URL(req.url, "http://127.0.0.1");
+      if (url.pathname !== "/callback") {
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+
+      const error = url.searchParams.get("error");
+      const errorDesc =
+        url.searchParams.get("error_description") ?? error ?? "Unknown error";
+      const code = url.searchParams.get("code");
+      const returnedState = url.searchParams.get("state");
+
+      if (error) {
+        settled = true;
+        clearTimeout(timer);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(ERROR_HTML(errorDesc));
+        server.close();
+        reject(new Error(`OAuth error: ${errorDesc}`));
+        return;
+      }
+
+      if (returnedState !== expectedState) {
+        settled = true;
+        clearTimeout(timer);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(ERROR_HTML("State mismatch — possible CSRF attempt. Please try again."));
+        server.close();
+        reject(new Error("OAuth state mismatch (CSRF check failed)"));
+        return;
+      }
+
+      if (!code) {
+        settled = true;
+        clearTimeout(timer);
+        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(ERROR_HTML("No authorization code received"));
+        server.close();
+        reject(new Error("OAuth callback missing authorization code"));
+        return;
+      }
+
+      // Success
+      settled = true;
+      clearTimeout(timer);
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(SUCCESS_HTML);
+      server.close();
+      resolve({ code, state: returnedState });
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Token exchange helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * POST to the token endpoint with application/x-www-form-urlencoded body.
+ * Returns the parsed JSON response or throws.
+ * @param {string} tokenEndpoint
+ * @param {Record<string, string>} params
+ * @returns {Promise<{ access_token: string, token_type: string, expires_in: number, refresh_token?: string, scope?: string }>}
+ */
+async function postToken(tokenEndpoint, params) {
+  const body = new URLSearchParams(params).toString();
+  const res = await fetch(tokenEndpoint, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json",
+    },
+    body,
+    signal: AbortSignal.timeout(30_000),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Token endpoint error ${res.status}: ${safeErrorDetail(text)}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Token endpoint returned a non-JSON response (status ${res.status})`);
+  }
+}
+
+/**
+ * Extract only the OAuth `error`/`error_description` fields from a token-endpoint
+ * body. Never returns the raw body, which on a misbehaving or hostile endpoint
+ * could contain an access_token / refresh_token that would then land in logs.
+ * @param {string} text
+ * @returns {string}
+ */
+function safeErrorDetail(text) {
+  try {
+    const j = JSON.parse(text);
+    const detail = [j.error, j.error_description].filter(Boolean).join(": ");
+    return detail ? detail.slice(0, 200) : "unrecognized error response";
+  } catch {
+    return "unrecognized error response";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the full Authorization-Code + PKCE login flow.
+ * Opens a browser, waits for the callback, exchanges the code, saves creds.
+ *
+ * @param {{ issuer: string, interactive?: boolean }} options
+ * @returns {Promise<{ access_token: string, refresh_token?: string, expires_at: number, scope?: string, token_endpoint: string }>}
+ */
+export async function login({ issuer, interactive = true }) {
+  const metadata = await discoverMetadata(issuer);
+  const { authorization_endpoint, token_endpoint, scopes_supported } = metadata;
+
+  const verifier = generateCodeVerifier();
+  const challenge = generateCodeChallenge(verifier);
+  const state = generateState();
+
+  const { server, port } = await startCallbackServer();
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  const authorizeUrl = new URL(authorization_endpoint);
+  authorizeUrl.searchParams.set("response_type", "code");
+  authorizeUrl.searchParams.set("client_id", "sutra-mcp");
+  authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+  authorizeUrl.searchParams.set("state", state);
+  authorizeUrl.searchParams.set("code_challenge", challenge);
+  authorizeUrl.searchParams.set("code_challenge_method", "S256");
+  // Request scopes explicitly. SUTRA_SCOPES narrows the grant; otherwise default
+  // to the full set the server advertises (scopes_supported) so the MCP tools
+  // keep working. We always send an explicit scope when one is known rather than
+  // relying on the server's blank-scope default (which is read-only) — this
+  // keeps the grant visible on the consent screen and least-privilege-friendly.
+  const requestedScopes =
+    process.env.SUTRA_SCOPES?.trim() ||
+    (Array.isArray(scopes_supported) ? scopes_supported.join(" ") : "");
+  if (requestedScopes) {
+    authorizeUrl.searchParams.set("scope", requestedScopes);
+  } else {
+    // No SUTRA_SCOPES, and discovery didn't advertise scopes_supported (a
+    // degraded/fallback metadata fetch). Without a scope param the server grants
+    // its read-only default — and that token gets cached and silently reused. Make
+    // the downgrade visible so the user can re-run with SUTRA_SCOPES for writes.
+    process.stderr.write(
+      "\nWarning: the server did not advertise its available scopes (metadata " +
+      "discovery may have failed); requesting the server default, which is " +
+      "read-only. If you need write tools, set SUTRA_SCOPES and log in again.\n"
+    );
+  }
+
+  const urlString = authorizeUrl.toString();
+
+  process.stderr.write(
+    `\nOpen this URL to log in to Sutra:\n\n  ${urlString}\n\n` +
+    `Waiting for browser callback (5 min timeout)...\n`
+  );
+
+  if (interactive) {
+    openBrowser(urlString);
+  }
+
+  // Wait for callback — server is closed inside waitForCallback
+  const { code } = await waitForCallback(server, state, LOGIN_TIMEOUT_MS);
+
+  process.stderr.write("Authorization code received — exchanging for tokens...\n");
+
+  const tokenData = await postToken(token_endpoint, {
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: "sutra-mcp",
+    code_verifier: verifier,
+  });
+
+  const creds = {
+    access_token: tokenData.access_token,
+    refresh_token: tokenData.refresh_token ?? null,
+    expires_at: Date.now() + (tokenData.expires_in ?? 3600) * 1000,
+    scope: tokenData.scope ?? null,
+    token_endpoint,
+  };
+
+  save(issuer, creds);
+  process.stderr.write("Login successful. Credentials cached.\n");
+  return creds;
+}
+
+/**
+ * Refresh an access token using the stored refresh_token.
+ * Saves rotated credentials on success. Clears and throws on failure.
+ *
+ * @param {{ issuer: string, creds: object }} options
+ * @returns {Promise<object>} updated creds
+ */
+export async function refresh({ issuer, creds }) {
+  if (!creds.refresh_token) {
+    clear(issuer);
+    throw new Error("No refresh token available — please log in again");
+  }
+
+  try {
+    const tokenData = await postToken(creds.token_endpoint, {
+      grant_type: "refresh_token",
+      refresh_token: creds.refresh_token,
+      client_id: "sutra-mcp",
+    });
+
+    const updated = {
+      access_token: tokenData.access_token,
+      refresh_token: tokenData.refresh_token ?? creds.refresh_token,
+      expires_at: Date.now() + (tokenData.expires_in ?? 3600) * 1000,
+      scope: tokenData.scope ?? creds.scope,
+      token_endpoint: creds.token_endpoint,
+    };
+
+    save(issuer, updated);
+    return updated;
+  } catch (err) {
+    clear(issuer);
+    throw new Error(`Token refresh failed (${err.message}) — please log in again`);
+  }
+}
+
+/**
+ * Return a valid access token, refreshing or re-logging-in as needed.
+ * This is the main entry point called by the client bootstrap.
+ *
+ * @param {{ issuer: string }} options
+ * @returns {Promise<string>} a valid access token
+ */
+export async function getValidAccessToken({ issuer }) {
+  let creds = load(issuer);
+
+  if (creds) {
+    // Token still valid (with 60s buffer)
+    if (creds.expires_at - 60_000 > Date.now()) {
+      return creds.access_token;
+    }
+    // Expired but we have a refresh token
+    if (creds.refresh_token) {
+      try {
+        const updated = await refresh({ issuer, creds });
+        return updated.access_token;
+      } catch (err) {
+        process.stderr.write(`Refresh failed: ${err.message}\n`);
+        // Fall through to full login
+      }
+    }
+  }
+
+  // No valid creds — run full login
+  const freshCreds = await login({ issuer });
+  return freshCreds.access_token;
+}

package/src/auth/pkce.js

@@ -0,0 +1,38 @@
+import { randomBytes, createHash } from "node:crypto";
+
+/**
+ * Generate a PKCE code_verifier: 32 random bytes → base64url (43 chars, well
+ * within the 43-128 spec limit).
+ */
+export function generateCodeVerifier() {
+  return base64url(randomBytes(32));
+}
+
+/**
+ * Derive the code_challenge from the verifier: base64url(SHA-256(verifier))
+ * with no padding.
+ */
+export function generateCodeChallenge(verifier) {
+  const hash = createHash("sha256").update(verifier).digest();
+  return base64url(hash);
+}
+
+/**
+ * Generate a random opaque state value for CSRF protection.
+ */
+export function generateState() {
+  return base64url(randomBytes(16));
+}
+
+/**
+ * Base64url encode a Buffer — no padding, + → -, / → _.
+ * @param {Buffer} buf
+ * @returns {string}
+ */
+function base64url(buf) {
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=/g, "");
+}

package/src/auth/store.js

@@ -0,0 +1,84 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Return the path to the credentials file.
+ * Uses SUTRA_CONFIG_DIR env or ~/.sutra.
+ */
+function credentialsPath() {
+  const dir = process.env.SUTRA_CONFIG_DIR
+    ? process.env.SUTRA_CONFIG_DIR
+    : join(homedir(), ".sutra");
+  return { dir, file: join(dir, "credentials.json") };
+}
+
+/**
+ * Read the full credentials store from disk.
+ * Returns {} if missing or invalid.
+ * @returns {Record<string, object>}
+ */
+function readStore() {
+  const { file } = credentialsPath();
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write the full credentials store to disk.
+ * Creates the directory with mode 0700 if absent.
+ * Writes the file with mode 0600.
+ * @param {Record<string, object>} store
+ */
+function writeStore(store) {
+  const { dir, file } = credentialsPath();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+  }
+  writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+  // The `mode` option above is ignored when the file already exists, and is
+  // masked by the process umask even on creation. Enforce 0600/0700
+  // explicitly so the secrets are never left group/world-readable.
+  try {
+    chmodSync(file, 0o600);
+    chmodSync(dir, 0o700);
+  } catch {
+    // Best-effort on platforms without POSIX permissions (e.g. Windows).
+  }
+}
+
+/**
+ * Load cached credentials for the given issuer.
+ * @param {string} issuer
+ * @returns {{ access_token: string, refresh_token?: string, expires_at: number, scope?: string, token_endpoint: string } | null}
+ */
+export function load(issuer) {
+  const store = readStore();
+  return store[issuer] ?? null;
+}
+
+/**
+ * Persist credentials for the given issuer.
+ * @param {string} issuer
+ * @param {{ access_token: string, refresh_token?: string, expires_at: number, scope?: string, token_endpoint: string }} creds
+ */
+export function save(issuer, creds) {
+  const store = readStore();
+  store[issuer] = creds;
+  writeStore(store);
+}
+
+/**
+ * Remove cached credentials for the given issuer.
+ * @param {string} issuer
+ */
+export function clear(issuer) {
+  const store = readStore();
+  if (!Object.prototype.hasOwnProperty.call(store, issuer)) return;
+  delete store[issuer];
+  writeStore(store);
+}

package/src/client.js

@@ -1,12 +1,70 @@
 const BASE_URL = "https://api.sutra.co/api/admin/v1";
 
 export class SutraAdminClient {
-  constructor(apiToken, baseUrl) {
-    this.apiToken = apiToken;
+  /**
+   * @param {string | { getToken: () => Promise<string>, onUnauthorized?: () => Promise<void> }} tokenOrOptions
+   *   - string: static API token (original behavior, fully preserved)
+   *   - object: { getToken, onUnauthorized? } for OAuth token provider
+   * @param {string} [baseUrl]
+   */
+  constructor(tokenOrOptions, baseUrl) {
     this.baseUrl = (baseUrl || BASE_URL).replace(/\/+$/, "");
+
+    if (typeof tokenOrOptions === "string") {
+      // Original static-token path — unchanged behaviour
+      this.apiToken = tokenOrOptions;
+      this._getToken = null;
+      this._onUnauthorized = null;
+    } else {
+      // Token provider path (OAuth)
+      this.apiToken = null;
+      this._getToken = tokenOrOptions.getToken;
+      this._onUnauthorized = tokenOrOptions.onUnauthorized ?? null;
+    }
+  }
+
+  /**
+   * Resolve the current bearer token.
+   * @returns {Promise<string>}
+   */
+  async _resolveToken() {
+    if (this._getToken) {
+      return this._getToken();
+    }
+    return this.apiToken;
   }
 
   async request(method, path, { params, body, headers: extra } = {}) {
+    const token = await this._resolveToken();
+    const result = await this._doRequest(method, path, { params, body, extra, token });
+
+    // 401 retry — only once, only when a handler is registered
+    if (result.status === 401 && this._onUnauthorized) {
+      await this._onUnauthorized();
+      const retryToken = await this._resolveToken();
+      const retryResult = await this._doRequest(method, path, {
+        params,
+        body,
+        extra,
+        token: retryToken,
+      });
+      if (!retryResult.ok) {
+        throw new Error(`${method} ${path} → ${retryResult.status}: ${retryResult.text}`);
+      }
+      return retryResult.text ? JSON.parse(retryResult.text) : {};
+    }
+
+    if (!result.ok) {
+      throw new Error(`${method} ${path} → ${result.status}: ${result.text}`);
+    }
+    return result.text ? JSON.parse(result.text) : {};
+  }
+
+  /**
+   * Execute a single HTTP request and return raw status + text (no throw).
+   * @private
+   */
+  async _doRequest(method, path, { params, body, extra, token }) {
     const url = new URL(`${this.baseUrl}${path}`);
     if (params) {
       for (const [k, v] of Object.entries(params)) {
@@ -15,7 +73,7 @@ export class SutraAdminClient {
     }
 
     const headers = {
-      Authorization: `Bearer ${this.apiToken}`,
+      Authorization: `Bearer ${token}`,
       Accept: "application/json",
       ...(body ? { "Content-Type": "application/json" } : {}),
       ...extra,
@@ -28,11 +86,7 @@ export class SutraAdminClient {
     });
 
     const text = await res.text();
-    if (!res.ok) {
-      throw new Error(`${method} ${path} → ${res.status}: ${text}`);
-    }
-
-    return text ? JSON.parse(text) : {};
+    return { ok: res.ok, status: res.status, text };
   }
 
   get(path, params) {

package/src/index.js

@@ -22,28 +22,108 @@ import { registerBlogTools } from "./tools/blog.js";
 import { registerDesignTools } from "./tools/design.js";
 import { registerAdminApiResources } from "./resources/admin-api.js";
 import { registerDesignResources } from "./resources/design.js";
+import { getValidAccessToken, login, refresh } from "./auth/oauth.js";
+import { clear, load } from "./auth/store.js";
+
+// ---------------------------------------------------------------------------
+// CLI subcommands — must be handled before any MCP server setup so that
+// stdout is never written to (it is the MCP channel).
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+
+if (args.includes("login")) {
+  const issuer = process.env.SUTRA_OAUTH_ISSUER || "https://sutra.co";
+  try {
+    await login({ issuer });
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Login failed: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+if (args.includes("logout")) {
+  const issuer = process.env.SUTRA_OAUTH_ISSUER || "https://sutra.co";
+  clear(issuer);
+  process.stderr.write("Logged out — cached credentials removed.\n");
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Auth bootstrap
+// ---------------------------------------------------------------------------
 
 const SUTRA_API_TOKEN = process.env.SUTRA_API_TOKEN;
 const SUTRA_BASE_URL = process.env.SUTRA_BASE_URL;
+const SUTRA_OAUTH_ISSUER = process.env.SUTRA_OAUTH_ISSUER || "https://sutra.co";
 
-if (!SUTRA_API_TOKEN) {
-  console.error(
-    "SUTRA_API_TOKEN is required.\n\n" +
-    "Set it to your Sutra Admin API token (sutra_live_sk_...).\n" +
-    "Get one from your Sutra account settings or contact support@sutra.co.\n"
-  );
-  process.exit(1);
+let client;
+
+if (SUTRA_API_TOKEN) {
+  // Static token path — original behaviour, unchanged
+  client = new SutraAdminClient(SUTRA_API_TOKEN, SUTRA_BASE_URL);
+} else {
+  // OAuth path — obtain (or reuse/refresh) a token before connecting
+  process.stderr.write("No SUTRA_API_TOKEN set — using OAuth login.\n");
+
+  let cachedToken;
+  try {
+    cachedToken = await getValidAccessToken({ issuer: SUTRA_OAUTH_ISSUER });
+  } catch (err) {
+    process.stderr.write(
+      `Authentication failed: ${err.message}\n\n` +
+      "Run `npx -y @sutraspaces/mcp-server login` to authenticate, or set the\n" +
+      "SUTRA_API_TOKEN environment variable to a Sutra Admin API token.\n"
+    );
+    process.exit(1);
+  }
+
+  // Token provider: always return the in-memory cached token (fast path).
+  // The onUnauthorized handler refreshes it or triggers a new login.
+  const getToken = () => Promise.resolve(cachedToken);
+
+  // On a mid-session 401, only attempt a silent refresh. We deliberately do
+  // NOT trigger a full interactive browser login here: this runs inside a
+  // long-lived stdio server with no TTY, where spawning a browser and blocking
+  // a tool call for up to 5 minutes would be surprising and disruptive. If the
+  // refresh token is gone or rejected, surface a clear "re-run login" message.
+  const onUnauthorized = async () => {
+    process.stderr.write("Received 401 — attempting silent token refresh...\n");
+    try {
+      const stored = load(SUTRA_OAUTH_ISSUER);
+      if (!stored || !stored.refresh_token) {
+        process.stderr.write(
+          "No refresh token available. Run `npx -y @sutraspaces/mcp-server login` to re-authenticate.\n"
+        );
+        return;
+      }
+      const updated = await refresh({ issuer: SUTRA_OAUTH_ISSUER, creds: stored });
+      cachedToken = updated.access_token;
+      process.stderr.write("Token refreshed.\n");
+    } catch (err) {
+      process.stderr.write(
+        `Token refresh failed: ${err.message}\n` +
+        "Run `npx -y @sutraspaces/mcp-server login` to re-authenticate.\n"
+      );
+      // cachedToken unchanged; the retry will fail and surface a clear error.
+    }
+  };
+
+  client = new SutraAdminClient({ getToken, onUnauthorized }, SUTRA_BASE_URL);
 }
 
+// ---------------------------------------------------------------------------
+// MCP server setup
+// ---------------------------------------------------------------------------
+
 const server = new McpServer({
   name: "sutra",
-  version: "1.1.0",
+  version: "1.2.0",
   description:
     "Sutra Admin API — manage spaces, members, contacts, content, discussions, surveys, plans, broadcasts, and more.",
 });
 
-const client = new SutraAdminClient(SUTRA_API_TOKEN, SUTRA_BASE_URL);
-
 registerSpaceTools(server, client);
 registerMemberTools(server, client);
 registerContentTools(server, client);
@@ -66,10 +146,10 @@ registerDesignResources(server, client);
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("Sutra MCP server running on stdio");
+  process.stderr.write("Sutra MCP server running on stdio\n");
 }
 
 main().catch((err) => {
-  console.error("Fatal:", err);
+  process.stderr.write(`Fatal: ${err}\n`);
   process.exit(1);
 });