@nooticr/mcp 1.26.40 → 1.26.41

package/README.md

@@ -337,6 +337,76 @@ npx @nooticr/mcp --http     # remote HTTP with OAuth (for OpenAI Agents SDK)
 (mode `0600`). If your browser cannot be opened automatically, copy the URL it
 prints into a browser manually.
 
+## Running on a server (no browser)
+
+`login` and the OAuth flow both need a browser once, and both leave behind a
+15-minute access token kept alive by a refresh token. That is the wrong shape
+for an integration running server-side: nothing there can complete a consent
+screen, and a refresh chain that breaks has to be repaired by hand.
+
+An **API key** is the other way in. Mint one from a browser at
+[mcp.nooticr.com/dashboard](https://mcp.nooticr.com/dashboard) — sign in, name
+the key, copy it — or from a machine you *can* sign in on, once:
+
+```bash
+npx @nooticr/mcp login                                  # the one interactive step
+npx @nooticr/mcp api-key create --name "aybee-prod"     # prints the key, once
+```
+
+Then give it to the deployment. There is nothing else to configure and nothing
+to refresh — the key stays valid until you revoke it.
+
+```bash
+# stdio, as a subprocess of your own service
+NOOTICR_API_KEY=nk_... npx @nooticr/mcp
+```
+
+On a server, prefer the environment variable: it is what every container
+runtime and secret manager already injects, and it leaves nothing on a disk
+that a redeploy is going to throw away. Where setting one is the awkward part
+— a laptop, or a client like Claude Desktop that does not inherit your shell —
+store the key in the credentials file instead:
+
+```bash
+npx @nooticr/mcp login --api-key nk_...
+```
+
+That checks the key against the server before writing it, so a typo fails
+while you are still there to fix it, and then behaves exactly like the
+environment variable: no browser, no refresh, valid until revoked. The file
+holds one credential, so this replaces any session an earlier `login` left
+behind (and `NOOTICR_API_KEY` still overrides it).
+
+```http
+# or against the remote endpoint, as an ordinary bearer token —
+# no /authorize, no PKCE, no redirect URI
+POST https://mcp.nooticr.com/mcp
+Authorization: Bearer nk_...
+```
+
+Managing them, from the dashboard's **API keys** card or the CLI:
+
+```bash
+npx @nooticr/mcp api-key create --name "staging" --expires-in-days 90
+npx @nooticr/mcp api-key list
+npx @nooticr/mcp api-key revoke <id>
+```
+
+Every command takes `--json` for scripting. A few things worth knowing:
+
+- The key is shown **once**, by `api-key create`. nooticr stores only a hash of
+  it and cannot show it again; `list` shows the head (`nk_1a2b3c4d…`) so you
+  can tell keys apart.
+- A key carries the scope of whoever created it — their account, and the
+  workspace they were in (`--workspace-id` picks another one you belong to).
+- A key **cannot create or revoke keys**. That is deliberate: it means a leaked
+  key cannot mint a replacement that outlives revoking the original.
+- `--expires-in-days` is optional. Without it a key does not expire on its own.
+- Revoking takes effect immediately at the API. The hosted remote endpoint
+  caches the "this key is real" answer for up to five minutes, which only ever
+  lets a revoked key see the tool list — every call that touches your account
+  is checked against nooticr-server on the spot.
+
 ## Usage in Claude Desktop
 
 After `npx @nooticr/mcp login`, add to `claude_desktop_config.json`:
@@ -455,6 +525,11 @@ nooticr-mcp --stdio            Same as above
 nooticr-mcp --http [--port N]  Start the remote HTTP transport with OAuth (default port 3457)
 nooticr-mcp login              Sign in to nooticr via Google in your browser
 nooticr-mcp login --email ... --password ...   Password login
+nooticr-mcp login --api-key nk_...             Sign in with an API key, no browser
+nooticr-mcp api-key create [--name N] [--expires-in-days D] [--workspace-id W] [--json]
+                               Mint a key for a server with no browser
+nooticr-mcp api-key list [--json]         List this account's keys
+nooticr-mcp api-key revoke <id> [--json]  Revoke one
 nooticr-mcp --help             Show help
 ```
 
@@ -463,7 +538,8 @@ nooticr-mcp --help             Show help
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `NOOTICR_BASE_URL` | `https://api.nooticr.com` | nooticr server base URL (trailing slash stripped) |
-| `NOOTICR_ACCESS_TOKEN` | — | nooticr JWT access token; takes priority over the credentials file |
+| `NOOTICR_ACCESS_TOKEN` | — | nooticr JWT access token; takes priority over everything below |
+| `NOOTICR_API_KEY` | — | nooticr API key from `api-key create` — no browser, no refresh, valid until revoked; takes priority over the credentials file (including a key `login --api-key` put there) |
 | `NOOTICR_CREDENTIALS_FILE` | `~/.config/nooticr-mcp/credentials.json` | token store path |
 | `NOOTICR_PUBLIC_URL` | `http://localhost:3457` | public base URL advertised in OAuth metadata (HTTP mode) |
 | `NOOTICR_PORT` | `3457` | port for `--http` and `login` |
@@ -471,10 +547,20 @@ nooticr-mcp --help             Show help
 
 ## How authentication works
 
-**stdio mode** (Claude Desktop, Cursor): the server uses the token from
-`NOOTICR_ACCESS_TOKEN` or the credentials file written by `login`. If the token
-is expired it is automatically refreshed with the stored refresh token, and if
-the nooticr API returns `401` the request is retried once after a refresh.
+**stdio mode** (Claude Desktop, Cursor): the server uses the first credential
+it finds — `NOOTICR_ACCESS_TOKEN`, then `NOOTICR_API_KEY`, then the credentials
+file written by `login`. That file holds one credential, whichever `login` last
+wrote: an API key (`login --api-key`) or a session. A session token that has
+expired is refreshed with the stored refresh token, and a `401` from the
+nooticr API is retried once after a refresh. An API key is never refreshed
+wherever it came from: it does not expire, so a `401` on one means revoked or
+mistyped, and retrying would only hide that.
+
+**API key** (any transport, no browser): send it as the bearer token, or set
+`NOOTICR_API_KEY`. nooticr-server resolves the key to its owner and the
+workspace it was scoped to, and every authorization check downstream sees
+exactly what it would have seen for a signed-in session. See
+[Running on a server](#running-on-a-server-no-browser).
 
 **HTTP mode** (OpenAI Agents SDK, remote clients): the server runs its own
 OAuth 2.0 authorization server (Authorization Code + PKCE S256, public client,
@@ -488,7 +574,9 @@ per the MCP 2025-03-26 spec):
   one-time code
 - `POST /token` — verifies PKCE and issues an opaque Bearer token bound to the
   nooticr session (valid 1 hour)
-- every MCP RPC validates the Bearer token against the session map
+- every MCP RPC validates the Bearer token against the session map — or, when
+  the bearer is an API key, forwards it to nooticr-server as the caller's own
+  credential, which is what makes this endpoint usable with no browser at all
 
 ## Supported URLs
 
@@ -508,8 +596,14 @@ and text** posts.
 
 ## Troubleshooting
 
-- **`Not authenticated with nooticr` / 401**: run `npx @nooticr/mcp login` or set
-  `NOOTICR_ACCESS_TOKEN`.
+- **`Not authenticated with nooticr` / 401**: run `npx @nooticr/mcp login`, or
+  set `NOOTICR_API_KEY` (see [Running on a server](#running-on-a-server-no-browser)).
+- **`unknown, revoked or expired nooticr API key`**: the key is not one this
+  account has live. `npx @nooticr/mcp api-key list` shows every key and its
+  state, revoked ones included.
+- **`API keys cannot manage API keys`**: `api-key create`/`list`/`revoke` need a
+  signed-in session, which is why they ignore a key in `NOOTICR_API_KEY` *and*
+  one stored by `login --api-key`. Run `npx @nooticr/mcp login` first.
 - **402 paywall / `insufficient MCP credits`**: your nooticr account is out of
   credits. Prices are listed per tool in [Tools](#tools) — 1 credit for a post
   lookup or transcript, 2 for discovery and for a tool that makes one fetch, 3
@@ -541,7 +635,12 @@ package for **Claude Desktop**, **Cursor**, and **OpenAI Agents SDK**.
   (in-memory).
 - Access tokens are opaque, random, and bound to the in-memory session map;
   they expire after 1 hour. Restarting the server invalidates all sessions.
-- Never share your credentials file or `NOOTICR_ACCESS_TOKEN`.
+- API keys are stored as a sha256 hash, never in the clear, so a database dump
+  cannot be replayed against the API. They are scoped to one account and one
+  workspace, carry their owner's role as it is *now* rather than as it was when
+  the key was minted, and cannot be used to create or revoke keys.
+- Never share your credentials file, `NOOTICR_ACCESS_TOKEN` or
+  `NOOTICR_API_KEY`.
 
 ## Development
 

package/dist/auth.js

@@ -1,11 +1,23 @@
 /**
  * Token storage + resolution.
  *
- * Priority: env NOOTICR_ACCESS_TOKEN > credentials file (auto-refresh when
- * expired) > per-session tokens (HTTP OAuth mode only).
+ * Priority: env NOOTICR_ACCESS_TOKEN > env NOOTICR_API_KEY > credentials file
+ * (an API key stored by `login --api-key`, else a session token, refreshed
+ * when expired) > per-session tokens (HTTP OAuth mode only).
+ *
+ * `NOOTICR_ACCESS_TOKEN` stays first because it has always been the explicit
+ * "use exactly this token" override, and someone who exports one for a single
+ * debugging run should get it. An API key sits directly behind it: it is the
+ * credential a server holds permanently, so it outranks anything in a file.
+ *
+ * The file holds *one* credential, whichever `login` last wrote. A store
+ * carrying both a key and a session would make "which am I signed in as"
+ * unanswerable — and, worse, let a rejected key quietly fall back to a stale
+ * session belonging to someone else.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { getApiKey } from "./config.js";
 import { NooticrClient, NooticrError } from "./nooticr.js";
 const REFRESH_BEFORE_EXPIRY_MS = 30_000;
 export class NooticrAuthError extends Error {
@@ -40,7 +52,7 @@ export class AuthManager {
         try {
             const raw = await fs.promises.readFile(this.credentialsFile, "utf8");
             const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed.accessToken === "string") {
+            if (parsed && (typeof parsed.accessToken === "string" || typeof parsed.apiKey === "string")) {
                 return parsed;
             }
             return null;
@@ -63,15 +75,34 @@ export class AuthManager {
     /**
      * Resolves the current access token for a request. `session` provides the
      * per-session tokens issued via our own OAuth /token endpoint (HTTP mode).
+     *
+     * `allowApiKey` exists for the one caller that must not use one: the
+     * `api-key` CLI commands. The backend refuses key management to a
+     * key-authenticated caller, so resolving a key there would turn "create me
+     * a second key" into a 403 that reads like a permissions bug rather than
+     * the deliberate bound it is. It skips both places a key can live — the
+     * environment and the credentials file — since the bound is about the
+     * credential, not about where it was found.
      */
-    async getAccessToken(session) {
+    async getAccessToken(session, { allowApiKey = true } = {}) {
         const envToken = process.env.NOOTICR_ACCESS_TOKEN;
         if (envToken) {
             this.lastSource = "env";
             this.lastRefreshToken = undefined;
             return envToken;
         }
+        const apiKey = allowApiKey ? getApiKey() : undefined;
+        if (apiKey) {
+            this.lastSource = "apiKey";
+            this.lastRefreshToken = undefined;
+            return apiKey;
+        }
         const store = await this.loadStore();
+        if (allowApiKey && store?.apiKey) {
+            this.lastSource = "apiKey";
+            this.lastRefreshToken = undefined;
+            return store.apiKey;
+        }
         if (store?.accessToken && !isTokenExpired(store)) {
             this.lastSource = "file";
             this.lastRefreshToken = store.refreshToken;
@@ -101,6 +132,10 @@ export class AuthManager {
      * the current token. Returns true when a new token is available.
      */
     async onUnauthorized(session) {
+        // A key has nothing to redeem: a 401 on one means revoked, expired or
+        // mistyped, and retrying with the same string forever would hide that.
+        if (this.lastSource === "apiKey")
+            return false;
         let refreshToken = this.lastRefreshToken;
         if (this.lastSource === "session" && session?.refreshToken) {
             refreshToken = session.refreshToken;
@@ -131,7 +166,22 @@ export class AuthManager {
         await this.saveStore(store);
         this.lastSource = "file";
         this.lastRefreshToken = store.refreshToken;
-        return store.accessToken;
+        // `session.accessToken` rather than `store.accessToken`: the guard above
+        // has already narrowed it, and the store's field is optional now that a
+        // credentials file may hold an API key instead of a session.
+        return session.accessToken;
+    }
+    /**
+     * Persists an API key as this machine's credential, replacing whatever
+     * `login` last wrote. For clients that do not inherit a shell environment
+     * (Claude Desktop, Cursor) and for a laptop where editing JSON to set an
+     * env var is the annoying part; a server should still be given
+     * `NOOTICR_API_KEY` and left with nothing on disk.
+     */
+    async persistApiKey(apiKey, user) {
+        await this.saveStore({ apiKey, user });
+        this.lastSource = "apiKey";
+        this.lastRefreshToken = undefined;
     }
     /**
      * Persists a session obtained from login/OAuth completion.
@@ -150,7 +200,8 @@ export class AuthManager {
     }
     ensureUnauthenticatedError() {
         throw new NooticrAuthError("Not authenticated with nooticr. Run `npx nooticr-mcp login` to sign in " +
-            "with Google, or set the NOOTICR_ACCESS_TOKEN environment variable " +
+            "with Google, or — on a server with no browser — set NOOTICR_API_KEY " +
+            "to a key from `npx nooticr-mcp api-key create` " +
             "(see `npx nooticr-mcp --help`).");
     }
 }
@@ -161,7 +212,27 @@ export function createStdioTokenProvider(auth) {
         onUnauthorized: async () => auth.onUnauthorized(),
     };
 }
-/** Builds a TokenProvider for HTTP mode: env > file > per-session tokens. */
+/**
+ * Builds a TokenProvider for the `api-key` CLI commands: env access token or
+ * the credentials file, never `NOOTICR_API_KEY`. See `getAccessToken`.
+ */
+export function createManagementTokenProvider(auth) {
+    return {
+        getAccessToken: async () => auth.getAccessToken(undefined, { allowApiKey: false }),
+        onUnauthorized: async () => auth.onUnauthorized(),
+    };
+}
+/**
+ * Builds a TokenProvider for one caller's own API key — the headless path
+ * through HTTP mode, where the bearer the client presented *is* the nooticr
+ * credential. Deliberately not `createHttpTokenProvider`: that one falls back
+ * to the operator's environment and credentials file, which would answer one
+ * tenant's call with another's account.
+ */
+export function createApiKeyTokenProvider(apiKey) {
+    return { getAccessToken: async () => apiKey };
+}
+/** Builds a TokenProvider for HTTP mode: env > api key > file > per-session tokens. */
 export function createHttpTokenProvider(auth, session) {
     return {
         getAccessToken: async () => auth.getAccessToken(session),

package/dist/config.js

@@ -40,6 +40,17 @@ export function getPort() {
     }
     return port;
 }
+/**
+ * A nooticr API key from the environment, if one is set.
+ *
+ * This is the headless path: no browser, no credentials file, nothing to
+ * refresh. A server-side integration sets `NOOTICR_API_KEY` once and the key
+ * stays valid until someone revokes it.
+ */
+export function getApiKey() {
+    const raw = process.env.NOOTICR_API_KEY?.trim();
+    return raw ? raw : undefined;
+}
 export function getCredentialsFile() {
     if (process.env.NOOTICR_CREDENTIALS_FILE) {
         return process.env.NOOTICR_CREDENTIALS_FILE;

package/dist/index.js

@@ -5,7 +5,8 @@
  *
  * Modes:
  *   nooticr-mcp            stdio transport (default; Claude Desktop, Cursor)
- *   nooticr-mcp login      browser-based Google sign-in to nooticr
+ *   nooticr-mcp login      browser-based Google sign-in (or --api-key, no browser)
+ *   nooticr-mcp api-key    mint/list/revoke a key for a server with no browser
  *   nooticr-mcp --http     remote HTTP transport with OAuth (OpenAI Agents SDK)
  */
 import http from "node:http";
@@ -13,7 +14,8 @@ import { randomUUID } from "node:crypto";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { getBaseUrl, getPublicUrl, getPort, getCredentialsFile, getTransportMode, DEFAULT_PORT, } from "./config.js";
-import { AuthManager, NooticrAuthError, createHttpTokenProvider, createStdioTokenProvider } from "./auth.js";
+import { AuthManager, NooticrAuthError, createApiKeyTokenProvider, createHttpTokenProvider, createManagementTokenProvider, createStdioTokenProvider, } from "./auth.js";
+import { looksLikeApiKey } from "./shared/api-key.js";
 import { NooticrClient, NooticrError } from "./nooticr.js";
 import { OAuthManager, SCOPES } from "./oauth.js";
 import { createMcpServer } from "./shared/tools.js";
@@ -78,12 +80,21 @@ function bearerToken(req) {
 }
 /**
  * A request bearer token is valid when it was issued by our OAuth `/token`
- * endpoint, or when it matches `NOOTICR_ACCESS_TOKEN` (pre-provisioned
- * deployments and local testing — no browser OAuth round-trip needed).
+ * endpoint, when it is a nooticr API key, or when it matches
+ * `NOOTICR_ACCESS_TOKEN` (pre-provisioned deployments and local testing — no
+ * browser OAuth round-trip needed).
+ *
+ * A key is accepted on its shape alone because this process does not hold the
+ * secret to check it against — only nooticr-server does, and it checks every
+ * call. What that admits without a round trip is `initialize` and
+ * `tools/list`, both of which answer the same for everyone; the first call
+ * that touches an account gets the backend's own 401.
  */
 function validMcpToken(token, oauth) {
     if (oauth.verifyToken(token))
         return true;
+    if (looksLikeApiKey(token))
+        return true;
     const envToken = process.env.NOOTICR_ACCESS_TOKEN;
     return typeof envToken === "string" && envToken.length > 0 && token === envToken;
 }
@@ -93,8 +104,10 @@ async function handleMcpRequest(state, req, res) {
     if (!token || !validMcpToken(token, state.oauth)) {
         return sendJson(res, 401, {
             error: "Unauthorized",
-            error_description: "This MCP server requires OAuth authentication. Fetch an access token from " +
-                `${state.oauth.authorizationServerMetadata().authorization_endpoint} first.`,
+            error_description: "This MCP server requires authentication. Fetch an access token from " +
+                `${state.oauth.authorizationServerMetadata().authorization_endpoint}, or — on a ` +
+                "server with no browser — send a nooticr API key as the bearer token " +
+                "(npx @nooticr/mcp api-key create).",
         });
     }
     // Hand the validated token to the SDK transport, which forwards it to tool
@@ -221,8 +234,16 @@ export async function runHttp(port, publicUrl) {
         transports: new Map(),
         connections: new Map(),
         serverFactory: () => createMcpServer((extra) => {
-            const session = extra.authInfo?.token
-                ? oauth.verifyToken(extra.authInfo.token)
+            const bearer = extra.authInfo?.token;
+            // A caller who presented their own API key is answered as themselves.
+            // Falling through to `createHttpTokenProvider` here would resolve the
+            // *operator's* environment or credentials file instead — one tenant's
+            // request served from another's account.
+            if (looksLikeApiKey(bearer)) {
+                return new NooticrClient(baseUrl, createApiKeyTokenProvider(bearer));
+            }
+            const session = bearer
+                ? oauth.verifyToken(bearer)
                 : undefined;
             return new NooticrClient(baseUrl, createHttpTokenProvider(auth, session
                 ? {
@@ -253,6 +274,27 @@ export async function runLogin(opts) {
     const client = new NooticrClient(baseUrl, {
         getAccessToken: async () => undefined,
     });
+    if (opts.apiKey) {
+        // Check the key before writing it. This is the one moment a person is
+        // present to fix a typo — an unchecked key would instead surface as a
+        // failed tool call later, from a client that cannot explain itself.
+        const keyed = new NooticrClient(baseUrl, createApiKeyTokenProvider(opts.apiKey));
+        let user;
+        try {
+            user = await keyed.me();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new NooticrAuthError(`That API key was rejected by ${baseUrl}: ${msg}\n` +
+                "`npx nooticr-mcp api-key list` (signed in) shows which keys are still active.");
+        }
+        await auth.persistApiKey(opts.apiKey, user);
+        process.stdout.write(`Signed in as ${user?.email ?? "unknown user"} with an API key. ` +
+            `Saved to ${auth.getCredentialsFile()}\n` +
+            "The key does not expire, so there is nothing to refresh and no browser to open again.\n" +
+            "On a server, prefer NOOTICR_API_KEY over this file — see the README.\n");
+        return;
+    }
     if (opts.email && opts.password) {
         const session = await client.login(opts.email, opts.password);
         await auth.persistSession(session);
@@ -315,6 +357,98 @@ export async function runLogin(opts) {
         process.exit(1);
     }, 300_000).unref();
 }
+function formatDate(value) {
+    if (!value)
+        return "never";
+    const at = new Date(value);
+    return Number.isNaN(at.getTime()) ? value : at.toISOString().slice(0, 10);
+}
+function describeKey(key) {
+    const state = key.revokedAt
+        ? "revoked"
+        : key.expiresAt && new Date(key.expiresAt).getTime() <= Date.now()
+            ? "expired"
+            : "active";
+    return [
+        `${key.prefix}\u2026  ${key.name}`,
+        `  id         ${key.id}`,
+        `  state      ${state}`,
+        `  created    ${formatDate(key.createdAt)}`,
+        `  last used  ${formatDate(key.lastUsedAt)}`,
+        `  expires    ${formatDate(key.expiresAt)}`,
+    ].join("\n");
+}
+/**
+ * Mints, lists and revokes the keys a headless deployment authenticates with.
+ *
+ * Creating one needs an interactive session exactly once — that is the step it
+ * removes from every run afterwards — so these commands deliberately refuse to
+ * authenticate with `NOOTICR_API_KEY` even when one is set. The backend
+ * refuses key management to a key-authenticated caller anyway; resolving one
+ * here would only turn that bound into a 403 that reads like a bug.
+ */
+export async function runApiKey(opts) {
+    const baseUrl = getBaseUrl();
+    const auth = new AuthManager(baseUrl, getCredentialsFile());
+    const token = await auth.getAccessToken(undefined, { allowApiKey: false });
+    if (!token) {
+        // Telling these two apart matters: "sign in first" is wrong advice for
+        // someone who *is* signed in, with a key, and is being refused for a
+        // reason the message otherwise never mentions.
+        const hasKey = Boolean(await auth.getAccessToken());
+        throw new NooticrAuthError(hasKey
+            ? "You are signed in with an API key, and a key cannot manage keys — that bound is " +
+                "what stops a leaked key minting a replacement that outlives revoking the original. " +
+                "Sign in as yourself for this one: `npx nooticr-mcp login` " +
+                "(or `login --email ... --password ...`)."
+            : "Sign in first: `npx nooticr-mcp login` (or `login --email ... --password ...`). " +
+                "Minting a key is the one step that needs a browser, and it is the last one: " +
+                "the key it returns is what every run afterwards uses.");
+    }
+    const client = new NooticrClient(baseUrl, createManagementTokenProvider(auth));
+    if (opts.action === "create") {
+        const created = await client.createApiKey({
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
+            ...(opts.workspaceId !== undefined ? { workspaceId: opts.workspaceId } : {}),
+            ...(opts.expiresInDays !== undefined ? { expiresInDays: opts.expiresInDays } : {}),
+        });
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(created, null, 2)}\n`);
+            return;
+        }
+        process.stdout.write(`Created API key "${created.name}" (${created.id}).\n\n` +
+            `  ${created.key}\n\n` +
+            "This is the only time the key is shown — nooticr stores a hash of it and\n" +
+            "cannot show it again. Store it wherever this deployment keeps its secrets,\n" +
+            "then give it to the server:\n\n" +
+            "  NOOTICR_API_KEY=<key> npx nooticr-mcp\n\n" +
+            "or, against the remote HTTP endpoint, as the bearer token:\n\n" +
+            "  Authorization: Bearer <key>\n");
+        return;
+    }
+    if (opts.action === "list") {
+        const keys = await client.listApiKeys();
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(keys, null, 2)}\n`);
+            return;
+        }
+        if (keys.length === 0) {
+            process.stdout.write("No API keys. Create one with `npx nooticr-mcp api-key create --name <name>`.\n");
+            return;
+        }
+        process.stdout.write(`${keys.map(describeKey).join("\n\n")}\n`);
+        return;
+    }
+    if (!opts.id) {
+        throw new NooticrError(400, "Usage: nooticr-mcp api-key revoke <id>");
+    }
+    await client.revokeApiKey(opts.id);
+    if (opts.json) {
+        process.stdout.write(`${JSON.stringify({ id: opts.id, revoked: true }, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`Revoked ${opts.id}. Any server still presenting it now gets a 401.\n`);
+}
 // ---------------------------------------------------------------------------
 // CLI
 // ---------------------------------------------------------------------------
@@ -328,11 +462,18 @@ Usage:
                                 (default port ${DEFAULT_PORT}; also NOOTICR_PORT)
   nooticr-mcp login              Sign in to nooticr via Google in your browser
   nooticr-mcp login --email me@example.com --password '...'   Password login
+  nooticr-mcp login --api-key nk_...  Sign in with an API key (no browser)
+  nooticr-mcp api-key create [--name N] [--expires-in-days D] [--workspace-id W] [--json]
+                                Mint a key for a server with no browser
+  nooticr-mcp api-key list [--json]        List this account's keys
+  nooticr-mcp api-key revoke <id> [--json] Revoke one
   nooticr-mcp --help             Show this help
 
 Environment variables:
   NOOTICR_BASE_URL          nooticr server base URL (default http://localhost:8080)
   NOOTICR_ACCESS_TOKEN      nooticr JWT access token (bypasses login)
+  NOOTICR_API_KEY           nooticr API key from "api-key create" — no browser,
+                            no refresh, valid until revoked
   NOOTICR_CREDENTIALS_FILE  token store path (default ~/.config/nooticr-mcp/credentials.json)
   NOOTICR_PUBLIC_URL        public base URL for the HTTP mode (default http://localhost:3457)
   NOOTICR_PORT              port for --http and login (default ${DEFAULT_PORT})
@@ -343,6 +484,11 @@ Client setup:
     "command": "npx", "args": ["nooticr-mcp"]  (plus NOOTICR_ACCESS_TOKEN if needed)
   OpenAI Agents SDK (remote HTTP): use the RemoteMCPClient with URL
     <NOOTICR_PUBLIC_URL>/mcp — the OAuth flow will open your browser.
+  Server-side, no browser: mint a key once with "api-key create", then either
+    set NOOTICR_API_KEY for the stdio server, or send it to the remote endpoint
+    as "Authorization: Bearer <key>" and skip the OAuth flow entirely.
+  A client that does not inherit your shell environment: "login --api-key nk_..."
+    stores the same key in the credentials file instead.
 
 See README.md for full instructions.
 `);
@@ -361,6 +507,17 @@ async function main() {
         };
         const email = valueOf("--email");
         const password = valueOf("--password");
+        // Every other flag here is kebab-case; `--api_key` is the near-miss worth
+        // naming rather than ignoring, since ignoring it opens a browser instead.
+        if (rest.includes("--api_key")) {
+            process.stderr.write("Unknown flag --api_key. Did you mean --api-key?\n");
+            process.exit(1);
+        }
+        const apiKey = valueOf("--api-key");
+        if (rest.includes("--api-key") && !apiKey) {
+            process.stderr.write("--api-key needs a value (the nk_… key from `api-key create`).\n");
+            process.exit(1);
+        }
         let port = getPort();
         const portRaw = valueOf("--port");
         if (portRaw !== undefined)
@@ -373,8 +530,12 @@ async function main() {
             process.stderr.write("Both --email and --password must be provided together.\n");
             process.exit(1);
         }
+        if (apiKey && (email || password)) {
+            process.stderr.write("Use --api-key or --email/--password, not both.\n");
+            process.exit(1);
+        }
         try {
-            await runLogin({ email, password, port });
+            await runLogin({ email, password, apiKey, port });
         }
         catch (err) {
             process.stderr.write(`Login failed: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -382,6 +543,55 @@ async function main() {
         }
         return;
     }
+    if (args[0] === "api-key" || args[0] === "api-keys") {
+        const rest = args.slice(1);
+        const action = rest[0];
+        if (action !== "create" && action !== "list" && action !== "revoke") {
+            process.stderr.write("Usage: nooticr-mcp api-key <create|list|revoke> [options]\n" +
+                "       nooticr-mcp api-key create [--name N] [--expires-in-days D] [--workspace-id W]\n" +
+                "       nooticr-mcp api-key revoke <id>\n");
+            process.exit(1);
+        }
+        const flags = rest.slice(1);
+        const valueOf = (flag) => {
+            const idx = flags.indexOf(flag);
+            return idx >= 0 && flags[idx + 1] ? flags[idx + 1] : undefined;
+        };
+        const opts = { action, json: flags.includes("--json") };
+        const name = valueOf("--name");
+        if (name !== undefined)
+            opts.name = name;
+        const workspaceId = valueOf("--workspace-id");
+        if (workspaceId !== undefined)
+            opts.workspaceId = workspaceId;
+        const expiresRaw = valueOf("--expires-in-days");
+        if (expiresRaw !== undefined) {
+            const days = Number.parseInt(expiresRaw, 10);
+            if (!Number.isInteger(days) || days < 1) {
+                process.stderr.write("--expires-in-days must be a positive whole number of days.\n");
+                process.exit(1);
+            }
+            opts.expiresInDays = days;
+        }
+        if (action === "revoke") {
+            // The id is positional, so anything that starts with "-" is a flag the
+            // user meant for something else, not the key they want gone.
+            const id = flags.find((arg) => !arg.startsWith("-"));
+            if (!id) {
+                process.stderr.write("Usage: nooticr-mcp api-key revoke <id>\n");
+                process.exit(1);
+            }
+            opts.id = id;
+        }
+        try {
+            await runApiKey(opts);
+        }
+        catch (err) {
+            process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+        return;
+    }
     const isHttp = args.includes("--http") || getTransportMode() === "http";
     let port = getPort();
     if (args.includes("--port")) {

package/dist/shared/api-key.js

@@ -0,0 +1,20 @@
+/**
+ * nooticr API keys — the credential for a caller with no browser.
+ *
+ * Everything else this package can authenticate with ends at a 15-minute JWT:
+ * `login` writes one (plus a refresh token) to a credentials file, and the
+ * OAuth flows mint one behind a consent screen. Both assume a machine someone
+ * can sit at once. A partner's backend cannot run either, so it gets a key
+ * instead: one string, set once, valid until it is revoked.
+ *
+ * The prefix is load-bearing in two places that must agree — this file and
+ * nooticr-server's `routes::api_keys::API_KEY_PREFIX`. The server uses it to
+ * decide whether a bearer token is a key at all (and therefore whether to look
+ * in its database); this package uses it to decide whether a token can be
+ * refreshed. A JWT is three base64url segments, so it can never collide.
+ */
+export const API_KEY_PREFIX = "nk_";
+/** Whether a bearer token is a nooticr API key rather than a JWT. */
+export function looksLikeApiKey(token) {
+    return typeof token === "string" && token.startsWith(API_KEY_PREFIX);
+}

package/dist/shared/nooticr.js

@@ -98,11 +98,16 @@ export class NooticrClient {
             body = undefined;
         }
         const json = (body ?? {});
+        // Name the endpoint: a bare status code says nothing about which call
+        // failed, and these surface to the user as tool errors. Then add the
+        // body when it is plainly a sentence — dropping it leaves a headless
+        // caller with a number and no cause.
+        const detail = plainTextDetail(text);
         const errorMessage = typeof json.error === "string"
             ? json.error
-            : // Name the endpoint: a bare status code says nothing about which
-                // call failed, and these surface to the user as tool errors.
-                `nooticr API error (${res.status}) from ${path}`;
+            : detail
+                ? `nooticr API error (${res.status}) from ${path}: ${detail}`
+                : `nooticr API error (${res.status}) from ${path}`;
         if (res.status >= 200 && res.status < 300) {
             return body;
         }
@@ -172,6 +177,28 @@ export class NooticrClient {
             auth: true,
         });
     }
+    /**
+     * Mints a key for the signed-in user. Deliberately not callable *with* a
+     * key: the backend refuses key-management to key-authenticated callers so a
+     * leaked key cannot mint a sibling that survives its own revocation.
+     */
+    async createApiKey(input = {}) {
+        return this.request("POST", "/auth/api-keys", {
+            auth: true,
+            body: input,
+        });
+    }
+    async listApiKeys() {
+        const res = await this.request("GET", "/auth/api-keys", {
+            auth: true,
+        });
+        return res?.keys ?? [];
+    }
+    async revokeApiKey(id) {
+        await this.request("DELETE", `/auth/api-keys/${encodeURIComponent(id)}`, {
+            auth: true,
+        });
+    }
     async me() {
         return this.request("GET", "/auth/me", { auth: true });
     }
@@ -238,6 +265,21 @@ export class NooticrClient {
         throw new NooticrError(res.status, typeof json.error === "string" ? json.error : `Refresh failed (${res.status})`, { body });
     }
 }
+/**
+ * The backend answers a good many routes with a bare string rather than JSON
+ * (axum's `(StatusCode, String)`), and "nooticr API error (403)" tells whoever
+ * reads it nothing — least of all a headless integration, where the message is
+ * the only thing anyone will see. Use the body when it is plainly a sentence:
+ * short, one line, and not the start of a document.
+ */
+function plainTextDetail(text) {
+    const trimmed = text.trim();
+    if (!trimmed || trimmed.length > 300 || trimmed.includes("\n"))
+        return undefined;
+    if (/^[<{[]/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
 async function parseJsonBody(res) {
     const text = await res.text();
     try {

package/dist/shared/tools-def.js

@@ -435,8 +435,8 @@ export const TOOL_DEFINITIONS = [
     {
         name: "scan_marketplace_category",
         title: "Scan Marketplace Category",
-        description: "Collect a category from any of eleven marketplaces and read it: products with prices, star histograms, the review text itself, and the arithmetic over them (price spread, rating spread, which aspects recur across how many brands, and the share of each product's ratings sitting at 1-2 stars). marketplace picks the site — one of amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, temu. Pass query to search the category, items to pin named competitors by id or URL, or both. You write the read: purchase drivers, barriers, what the incumbents do well, the gaps, and how a new entrant could position. Collection runs in the background, so this returns everything ready within waitSeconds plus a scanId to continue with marketplace_scan_status — that is free, and repeating it is how a scan gets more time. For Amazon specifically, scan_amazon_category returns the same shape plus Amazon's own review-aspect counts. Consumes 3 nooticr credits per product collected — a product with reviews is a real browser render behind the site's bot defences.",
-        inputSchema: z.object({ marketplace: z.string().describe("Which site to read. One of: amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, temu."), query: z.string().optional().describe("Category or keyword to search, e.g. 'cast iron skillet'."), items: z.array(z.string()).optional().describe("Named competitors, by product id or URL."), limit: z.number().int().optional().describe("Products to collect (default 10, max 50)."), reviews: z.boolean().optional().describe("Collect review text too (default true)."), market: z.string().optional().describe("The storefront to read, for the sites that have more than one. Amazon: a country code or host — com (US), co.uk, de, fr and the rest, default www.amazon.com · Mercado Libre: one of eighteen markets, named however it comes to hand — MLB, br, Brazil · Lazada: sg, my, th, vn, ph or id · Otto: de or at · Rakuten: jp (Ichiba) or tw · Trendyol: one of 47 storefronts — tr, de, ae, sa and the rest · Jumia: ng, eg, ke, ma, ci, gh, sn, tn, ug or dz · AliExpress, Cdiscount, Flipkart and Temu have one storefront each and take no market argument. An id is scoped to one storefront: the same id on another is a different product or nothing at all."), domain: z.string().optional().describe("Amazon only: the marketplace host. Other sites use market."), waitSeconds: z.number().int().optional().describe("How long to wait before returning partial results (default 45, max 55). Poll marketplace_scan_status for the rest instead; it is free and repeatable."), focus: z.string().optional().describe("An extra question to answer from the reviews.") }).strict(),
+        description: "Collect a category from any of twelve marketplaces and read it: products with prices, star histograms, the review text itself, and the arithmetic over them (price spread, rating spread, which aspects recur across how many brands, and the share of each product's ratings sitting at 1-2 stars). marketplace picks the site — one of amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, vinted, temu. Pass query to search the category, items to pin named competitors by id or URL, or both. You write the read: purchase drivers, barriers, what the incumbents do well, the gaps, and how a new entrant could position. Collection runs in the background, so this returns everything ready within waitSeconds plus a scanId to continue with marketplace_scan_status — that is free, and repeating it is how a scan gets more time. For Amazon specifically, scan_amazon_category returns the same shape plus Amazon's own review-aspect counts. Consumes 3 nooticr credits per product collected — a product with reviews is a real browser render behind the site's bot defences.",
+        inputSchema: z.object({ marketplace: z.string().describe("Which site to read. One of: amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, vinted, temu."), query: z.string().optional().describe("Category or keyword to search, e.g. 'cast iron skillet'."), items: z.array(z.string()).optional().describe("Named competitors, by product id or URL."), limit: z.number().int().optional().describe("Products to collect (default 10, max 50)."), reviews: z.boolean().optional().describe("Collect review text too (default true)."), market: z.string().optional().describe("The storefront to read, for the sites that have more than one. Amazon: a country code or host — com (US), co.uk, de, fr and the rest, default www.amazon.com · Mercado Libre: one of eighteen markets, named however it comes to hand — MLB, br, Brazil · Lazada: sg, my, th, vn, ph or id · Otto: de or at · Rakuten: jp (Ichiba) or tw · Trendyol: one of 47 storefronts — tr, de, ae, sa and the rest · Jumia: ng, eg, ke, ma, ci, gh, sn, tn, ug or dz · AliExpress, Cdiscount, Flipkart and Temu have one storefront each and take no market argument. An id is scoped to one storefront: the same id on another is a different product or nothing at all."), domain: z.string().optional().describe("Amazon only: the marketplace host. Other sites use market."), waitSeconds: z.number().int().optional().describe("How long to wait before returning partial results (default 45, max 55). Poll marketplace_scan_status for the rest instead; it is free and repeatable."), focus: z.string().optional().describe("An extra question to answer from the reviews.") }).strict(),
     },
     {
         name: "marketplace_scan_status",
@@ -447,8 +447,8 @@ export const TOOL_DEFINITIONS = [
     {
         name: "get_marketplace_product",
         title: "Get Marketplace Product",
-        description: "Fetch one product from any of eleven marketplaces by id or URL: price, rating, the full star histogram, specs, and the review text. marketplace picks the site — one of amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, temu. Use for a single product; for a category or a competitive set, scan_marketplace_category collects many in one job and rolls them up. Consumes 3 nooticr credits.",
-        inputSchema: z.object({ marketplace: z.string().describe("Which site the product is on. One of: amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, temu."), id: z.string().optional().describe("The product id, in whatever form the site addresses products by."), url: z.string().optional().describe("The full product URL, if you have that instead."), reviews: z.boolean().optional().describe("Collect review text too (default true)."), market: z.string().optional().describe("The storefront the product is on, for sites that have more than one. Amazon: a country code or host — com (US), co.uk, de, fr and the rest, default www.amazon.com · Mercado Libre: one of eighteen markets, named however it comes to hand — MLB, br, Brazil · Lazada: sg, my, th, vn, ph or id · Otto: de or at · Rakuten: jp (Ichiba) or tw · Trendyol: one of 47 storefronts — tr, de, ae, sa and the rest · Jumia: ng, eg, ke, ma, ci, gh, sn, tn, ug or dz · AliExpress, Cdiscount, Flipkart and Temu have one storefront each and take no market argument. An id is scoped to one storefront: the same id on another is a different product or nothing at all."), domain: z.string().optional().describe("Amazon only: the marketplace host. Other sites use market.") }).strict(),
+        description: "Fetch one product from any of twelve marketplaces by id or URL: price, rating, the full star histogram, specs, and the review text. marketplace picks the site — one of amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, vinted, temu. Use for a single product; for a category or a competitive set, scan_marketplace_category collects many in one job and rolls them up. Consumes 3 nooticr credits.",
+        inputSchema: z.object({ marketplace: z.string().describe("Which site the product is on. One of: amazon, aliexpress, cdiscount, flipkart, mercadolibre, lazada, otto, rakuten, trendyol, jumia, vinted, temu."), id: z.string().optional().describe("The product id, in whatever form the site addresses products by."), url: z.string().optional().describe("The full product URL, if you have that instead."), reviews: z.boolean().optional().describe("Collect review text too (default true)."), market: z.string().optional().describe("The storefront the product is on, for sites that have more than one. Amazon: a country code or host — com (US), co.uk, de, fr and the rest, default www.amazon.com · Mercado Libre: one of eighteen markets, named however it comes to hand — MLB, br, Brazil · Lazada: sg, my, th, vn, ph or id · Otto: de or at · Rakuten: jp (Ichiba) or tw · Trendyol: one of 47 storefronts — tr, de, ae, sa and the rest · Jumia: ng, eg, ke, ma, ci, gh, sn, tn, ug or dz · AliExpress, Cdiscount, Flipkart and Temu have one storefront each and take no market argument. An id is scoped to one storefront: the same id on another is a different product or nothing at all."), domain: z.string().optional().describe("Amazon only: the marketplace host. Other sites use market.") }).strict(),
     },
     {
         name: "show_amazon_category_insights",

package/dist/shared/tools.js

@@ -28,7 +28,7 @@ import { registerCollabTools } from "./collab.js";
 import { registerAmazonTools } from "./amazon.js";
 import { registerMarketplaceTools } from "./marketplace.js";
 /** Current MCP server version — bumped on every deploy for traceability. */
-export const MCP_SERVER_VERSION = "1.26.40";
+export const MCP_SERVER_VERSION = "1.26.41";
 /** MCP Apps extension identifier */
 const UI_EXTENSION = "io.modelcontextprotocol/ui";
 /** MIME type for MCP Apps HTML resources */
@@ -346,6 +346,24 @@ function toolError(prefix, err) {
     // and what fixes it — including that they will not have to ask twice, which
     // is only true now that nooticr_login resumes the interrupted call.
     if (isAuthFailure(err)) {
+        // A deployment running on an API key has nobody to open a sign-in link:
+        // its 401 means the key was revoked, expired or mistyped, and "sign in
+        // again" sends whoever reads that log looking for a browser that does not
+        // exist. The backend names this case in its own message and the client
+        // carries plain-text errors through, so the two can be told apart here.
+        if (/api key/i.test(msg)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `${prefix}: this nooticr API key is not valid — revoked, expired, or mistyped. ` +
+                            `No sign-in link will help: nothing here can be re-authorised interactively. ` +
+                            `Replace the key (NOOTICR_API_KEY, or the bearer token sent to the remote ` +
+                            `endpoint) with a live one — \`npx @nooticr/mcp api-key list\` shows which are ` +
+                            `still active. (${msg})`,
+                    }],
+                isError: true,
+            };
+        }
         return {
             content: [{
                     type: "text",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nooticr/mcp",
   "mcpName": "com.nooticr/mcp",
-  "version": "1.26.40",
+  "version": "1.26.41",
   "description": "MCP server for nooticr - fetch, discover and understand TikTok/Instagram/YouTube/X/Reddit/LinkedIn/Weibo posts with AI (media metadata, niche discovery, brand monitoring, hook & viral analysis)",
   "homepage": "https://mcp.nooticr.com",
   "repository": {