@fennecstudio/x-tkn-mcp 1.0.0 → 1.3.0

package/README.md

@@ -6,9 +6,10 @@ Lets an AI agent hand a secret to a person as a one-time link, with no way to re
 npx -y @fennecstudio/x-tkn-mcp
 ```
 
-- **No read tool.** The server has `create_secret`, `check_status` and
-  `revoke_secret`. Once a secret is handed over, the agent can see whether it
-  was opened and can cancel it. It cannot see the secret again.
+- **No read tool.** The server has `create_secret`, `check_status`,
+  `revoke_secret` and `claim_sandbox`. Once a secret is handed over, the agent
+  can see whether it was opened and can cancel it. It cannot see the secret
+  again.
 - **Encrypted on your machine.** `create_secret` encrypts with AES-256-GCM
   before anything is sent. X-TKN stores only ciphertext. The key travels in the
   link's `#fragment`, which browsers never send to a server.
@@ -22,18 +23,43 @@ recipient can read it.
 
 ## Setup
 
-You need Node 20 or later and an X-TKN API key. Developer keys are free: sign up
-at [x-tkn.com](https://x-tkn.com) and create one in the account console.
-Sandbox keys (from `POST /accounts/sandbox`) cannot create secrets.
+You need Node 20 or later. An X-TKN API key is optional.
+
+**With no key**, the server starts a sandbox on its first tool call, with no
+signup. Nothing is minted at startup. The key is saved in
+`$XDG_CONFIG_HOME/x-tkn/sandbox.json` (`~/.config/x-tkn/sandbox.json` by
+default), the directory 0700 and the file 0600, and later starts reuse it until
+it expires. The key never appears in a tool result or in the server's log.
+Servers that start together share one sandbox: while one mints, it holds a
+`sandbox.json.lock` beside the file, and the others wait for it and use its key.
+
+- A sandbox lasts 24 hours, and so does every secret it creates:
+  `create_secret` refuses an `expiresIn` that runs past the sandbox's end.
+  Every result on a sandbox key ends with a line giving that end.
+- When it ends, the next call starts a new sandbox and says so. Codes from the
+  old one no longer work with `check_status` or `revoke_secret`.
+- To keep a sandbox, call `claim_sandbox`. It returns a one-time link for the
+  person who should keep it, and the key never leaves this machine. A sandbox
+  has to be claimed before it can be upgraded. The sandbox key still ends on
+  schedule after a claim, so a claimed account goes on with a Developer key
+  created for it and set here.
+- Once a sandbox has spent its operations, the server does not start another,
+  because that would lose the old one's codes. Call `claim_sandbox`, or set a
+  key.
+
+**For a key that stays**, Developer keys are free: sign up at
+[x-tkn.com](https://x-tkn.com) and create one in the account console. A key in
+`X_TKN_API_KEY` always wins: then nothing is minted and nothing is written.
 
 **Claude Code**
 
 ```bash
-claude mcp add x-tkn -e X_TKN_API_KEY=your-key -- npx -y @fennecstudio/x-tkn-mcp
+claude mcp add x-tkn -- npx -y @fennecstudio/x-tkn-mcp                            # a sandbox
+claude mcp add x-tkn -e X_TKN_API_KEY=your-key -- npx -y @fennecstudio/x-tkn-mcp  # your key
 ```
 
 **Claude Desktop, Cursor, Windsurf and other clients** take the same block in
-their MCP config file:
+their MCP config file. Leave `env` out for a sandbox:
 
 ```json
 {
@@ -47,9 +73,6 @@ their MCP config file:
 }
 ```
 
-Without a key the server still starts, and every tool call answers with how to
-get one.
-
 ## Tools
 
 ### `create_secret`
@@ -59,12 +82,13 @@ Encrypts a secret and returns a link that opens it once.
 | Argument         | Required | What it does                                                                                                   |
 | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
 | `secret`         | yes      | The text to hand over.                                                                                         |
-| `expiresIn`      | no       | `{ days, hours, minutes }`. Defaults to the plan's: 7 days on Developer, 30 on Team.                          |
+| `expiresIn`      | no       | `{ days, hours, minutes }`. Defaults to the plan's: 7 days on Developer, 30 on Team. On a sandbox key, defaults to the sandbox's end and cannot be later. |
 | `passphrase`     | no       | The recipient has to type this before the secret opens. 8 to 256 characters. Team and above.                  |
 | `recipientEmail` | no       | The recipient has to enter a 6-digit code sent to this address. Team and above. Not with `passphrase`.       |
 | `note`           | no       | For your own records in the X-TKN console. Stored unencrypted and never shown to the recipient.               |
 
-Returns the `link`, a `code` for the other two tools, and `expiresAt`.
+Returns the `link`, a `code` for `check_status` and `revoke_secret`, and
+`expiresAt`.
 
 Send a passphrase by a different channel than the link. Anyone holding both can
 open the secret.
@@ -74,11 +98,31 @@ open the secret.
 Takes the `code`. Returns `waiting`, `opened`, `expired` or `revoked`, with
 `openedAt` once it has been opened. It never returns the secret.
 
+Each call is one metered operation, and a sandbox has 100 in all. Call it no
+more often than every 30 seconds: at one call every 5 seconds, a link nobody
+opens spends a whole sandbox in under nine minutes.
+
 ### `revoke_secret`
 
 Takes the `code`. Stops the link working, immediately and for good. A secret
 that was already opened stays opened.
 
+### `claim_sandbox`
+
+Takes no arguments. Returns a `claimUrl` and its `expiresAt`: a one-time link a
+person opens to claim the sandbox this server's key belongs to, so the account
+outlives its 24 hours. Claiming keeps the sandbox's secrets.
+
+Give the link only to the person who should keep the sandbox. It works once,
+until `expiresAt`: 30 minutes, or the sandbox's end if that is sooner. Calling
+`claim_sandbox` again voids the earlier link. It is not metered.
+
+The sandbox key still ends when the sandbox would have, claimed or not. For a
+key that lasts, create a Developer key for the account in the account console
+and set `X_TKN_API_KEY`. On a key that is not an unclaimed sandbox (one already
+claimed, merged into another account or ended, or a Developer key), it says so
+and claims nothing.
+
 ## What X-TKN sees
 
 The ciphertext, the expiry, your `note`, and, if you set them, a hash of the

package/dist/index.js

@@ -3,6 +3,10 @@
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/env.ts
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
 // ../js/src/errors.ts
 var XTknError = class extends Error {
   /** HTTP status. `0` when the request never got a response. */
@@ -211,12 +215,15 @@ var XTkn = class _XTkn {
    * agent gets from `npm install` to a working request without a human
    * clicking a link in an email.
    *
-   * The account is capped and temporary: 100 operations, 24 hours, and no
-   * `secret` tokens. {@link XTkn.claim} turns it into an ordinary Developer
-   * account with 10,000 operations a month and no expiry.
+   * The account is capped and temporary: 100 operations and 24 hours. It may
+   * create `secret` tokens, none of which outlives it. {@link XTkn.claim}, or
+   * the link {@link XTkn.createClaimLink} returns, turns it into an ordinary
+   * Developer account with 10,000 operations a month and no expiry.
    *
    * `account.apiKey` is returned once and cannot be read back. Persist it if
-   * the process may restart before the account is claimed.
+   * the process may restart before the account is claimed. It stops working at
+   * `account.expiresAt` whether or not the account was claimed: a claimed
+   * account needs a Developer key of its own, created in the console.
    *
    * @example
    * ```ts
@@ -243,9 +250,14 @@ var XTkn = class _XTkn {
    * client authenticates as is the one claimed — there is no account id to
    * pass and no way to name somebody else's.
    *
-   * Existing tokens and keys survive. Throws {@link XTknRequestError} with a
-   * 409 when that email already owns an account; sign in with that one
-   * instead, since merging is not supported.
+   * Existing tokens survive. The sandbox key still ends when the sandbox would
+   * have, so create a Developer key for the account. When that email already
+   * owns an account under the same sign-in, the sandbox is merged into it
+   * instead: the result has `merged: true` and that account's `customerId`,
+   * with no `class` or `monthlyOperations`, and this client's key now acts as
+   * that account until it lapses. Throws {@link XTknRequestError} with a 409
+   * when the email's account is under a different sign-in; sign in with that
+   * one, then claim again.
    *
    * @example
    * ```ts
@@ -262,6 +274,32 @@ var XTkn = class _XTkn {
       headers: { "X-Firebase-Token": firebaseIdToken }
     });
   }
+  /**
+   * Get a one-time link a person opens to claim this sandbox account.
+   *
+   * {@link XTkn.claim} needs the person's sign-in in your own code. This needs
+   * only the sandbox key, so an agent holding the key can hand its person the
+   * link instead. The claim is the same either way: existing tokens survive,
+   * and the sandbox key still ends when the sandbox would have.
+   *
+   * The link works once, until `expiresAt`: 30 minutes, or the sandbox's end
+   * if that is sooner. Minting another voids it. Not counted against the
+   * sandbox's operations.
+   *
+   * Throws {@link XTknError} with a 409 when this key's account is not an
+   * unclaimed sandbox: already claimed, merged into another account, ended, or
+   * never a sandbox.
+   *
+   * @example
+   * ```ts
+   * const { client } = await XTkn.createSandbox()
+   * const { claimUrl, expiresAt } = await client.createClaimLink()
+   * console.log(`Open this before ${expiresAt} to keep the sandbox: ${claimUrl}`)
+   * ```
+   */
+  async createClaimLink() {
+    return this.request("POST", "/accounts/claim");
+  }
   /**
    * Create a token.
    *
@@ -587,24 +625,23 @@ function unwrap(parsed) {
   return parsed;
 }
 
-// src/version.ts
-var VERSION = "1.0.0";
-
-// src/env.ts
-var USER_AGENT = `x-tkn-mcp/${VERSION}`;
-function apiKeyFrom(env) {
-  for (const name of API_KEY_ENV_VARS) {
-    if (env[name]) return env[name];
-  }
-  return void 0;
-}
-function clientFrom(env) {
-  return new XTkn({ apiKey: apiKeyFrom(env), headers: { "User-Agent": USER_AGENT } });
+// src/connection.ts
+function keyConnection(client) {
+  return {
+    async call(work) {
+      try {
+        return { ok: true, value: await work(client), notes: [] };
+      } catch (error) {
+        return { ok: false, error, origin: "key", notes: [] };
+      }
+    }
+  };
 }
 
-// src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
+// src/sandbox.ts
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 
 // ../js/src/vendor/token-envelope.ts
 var PREFIX_V1 = "xtkn.v1.";
@@ -723,8 +760,21 @@ function buildSecretLink(code2, key, options = {}) {
 // src/tools.ts
 var SECRET_TYPE = "secret";
 var SIGNUP_URL = "https://x-tkn.com";
-var NO_KEY_MESSAGE = `No X-TKN API key. Set ${API_KEY_ENV_VARS[0]} in this MCP server's environment. Developer keys are free: sign up at ${SIGNUP_URL} and create one in the account console. Sandbox keys cannot create secrets.`;
-var SANDBOX_KEY_MESSAGE = `This is a sandbox key, and sandbox accounts cannot create secrets. Set ${API_KEY_ENV_VARS[0]} to a free Developer key instead: sign up at ${SIGNUP_URL} and create one in the account console.`;
+var SANDBOX_EXPIRY_REFUSAL = "Sandbox accounts cannot mint tokens that outlive them.";
+var NO_KEY_MESSAGE = `No X-TKN API key. Set ${API_KEY_ENV_VARS[0]} in this MCP server's environment. To start now with no signup, POST to ${DEFAULT_BASE_URL}/accounts/sandbox for a sandbox key. It lasts 24 hours, and so does every secret it creates. For a key that stays, Developer keys are free: sign up at ${SIGNUP_URL} and create one in the account console.`;
+var SANDBOX_KEY_MESSAGE = `This is a sandbox key. A sandbox account is deleted with its secrets 24 hours after it was created, so no secret it creates can expire later than that. Leave expiresIn out to get the latest expiry it allows. For longer, call claim_sandbox and give the link it returns to the person who should keep the account, or set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
+function sandboxStartupMessage(path) {
+  return `No ${API_KEY_ENV_VARS[0]} set, so this server uses a sandbox: the first tool call reuses the one saved in ${path}, or starts a new one that lasts 24 hours. For a key that stays, set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
+}
+function sandboxLine(sandbox, path) {
+  const ends = `Sandbox key: it and its secrets end at ${sandbox.expiresAt}.`;
+  if (sandbox.unsaved) {
+    return `${ends} It could not be saved to ${path} (${sandbox.unsaved}), so this server loses it when it stops. To keep the sandbox, call claim_sandbox before then.`;
+  }
+  return `${ends} Its key is saved in ${path}. To keep the sandbox, call claim_sandbox for a link to give the person who should have it. A sandbox has to be claimed before it can be upgraded.`;
+}
+var SANDBOX_RENEWED_MESSAGE = `A new sandbox started: the last sandbox key expired or X-TKN refused it. Codes create_secret returned before this belong to the old sandbox, and check_status and revoke_secret cannot reach them. If that sandbox was claimed, the account lives on: create a Developer key for it in the account console at ${SIGNUP_URL} and set ${API_KEY_ENV_VARS[0]}.`;
+var SANDBOX_MINT_REFUSED_MESSAGE = `X-TKN is not starting another sandbox from this address for now. Set ${API_KEY_ENV_VARS[0]} in this MCP server's environment to a free Developer key from ${SIGNUP_URL}, or try again in a few minutes.`;
 async function createSecret(client, args) {
   if (args.passphrase !== void 0 && args.recipientEmail !== void 0) {
     throw new XTknConfigError("Set passphrase or recipientEmail, not both. A secret takes one recipient check.");
@@ -759,6 +809,16 @@ async function checkStatus(client, code2) {
 async function revokeSecret(client, code2) {
   return statusOf(await client.revokeToken(code2));
 }
+var CLAIMED_KEY_STILL_ENDS = `A claimed sandbox key still ends when the sandbox would have. For a key that lasts, create a Developer key for the account in the account console at ${SIGNUP_URL} and set ${API_KEY_ENV_VARS[0]}.`;
+var NOT_AN_UNCLAIMED_SANDBOX_MESSAGE = "This key is not an unclaimed sandbox, so there is nothing to claim: it is a sandbox key that was already claimed, merged into another account or has ended, or not a sandbox key at all. " + CLAIMED_KEY_STILL_ENDS;
+async function claimSandbox(client) {
+  try {
+    return await client.createClaimLink();
+  } catch (err) {
+    if (err instanceof XTknError && err.status === 409) throw new XTknError(NOT_AN_UNCLAIMED_SANDBOX_MESSAGE, 0);
+    throw err;
+  }
+}
 function statusOf(token) {
   const uses = token.uses ?? 0;
   const opened = token.isUsed ?? (token.maxUses != null && uses >= token.maxUses);
@@ -771,16 +831,23 @@ function statusOf(token) {
     createdAt: token.createdAt ?? null
   };
 }
-function describeError(err) {
+function describeError(err, origin = "key") {
+  if (origin === "mint" && err instanceof XTknRateLimitError) return SANDBOX_MINT_REFUSED_MESSAGE;
+  if (origin === "sandbox" && err instanceof XTknRateLimitError) {
+    return `X-TKN is refusing more requests on this sandbox key (${err.message}). To go on, call claim_sandbox and give the link it returns to a person: claiming the sandbox lifts its cap. Or set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
+  }
+  if (origin === "sandbox" && err instanceof XTknAuthError && err.status === 401) {
+    return `X-TKN refused this server's sandbox key (${err.message}). Set ${API_KEY_ENV_VARS[0]} to a free Developer key from ${SIGNUP_URL}.`;
+  }
   if (err instanceof XTknPaymentRequiredError) {
-    if (err.upgradeMethod === "claim") return SANDBOX_KEY_MESSAGE;
     const plan = err.requiredPlan ? `the ${err.requiredPlan} plan` : "a paid plan";
+    if (err.upgradeMethod === "claim") {
+      return `${err.message} This needs ${plan}, and this is a sandbox key: a person has to claim the account before it can be upgraded. Call claim_sandbox for the link that does it.`;
+    }
     const where = err.upgradeUrl ? ` A person can upgrade here: ${err.upgradeUrl}` : "";
     return `${err.message} This needs ${plan}.${where}`;
   }
-  if (err instanceof XTknRequestError && err.message.startsWith("Sandbox accounts cannot create secrets")) {
-    return SANDBOX_KEY_MESSAGE;
-  }
+  if (err instanceof XTknRequestError && err.message.startsWith(SANDBOX_EXPIRY_REFUSAL)) return SANDBOX_KEY_MESSAGE;
   if (err instanceof XTknConfigError && err.message.startsWith("No API key")) return NO_KEY_MESSAGE;
   if (err instanceof XTknAuthError && err.status === 401) {
     return `X-TKN refused the API key in ${API_KEY_ENV_VARS[0]} (${err.message}). It may be mistyped or revoked.`;
@@ -794,12 +861,247 @@ function describeError(err) {
   return "The tool failed unexpectedly.";
 }
 
+// src/sandbox.ts
+async function readSandboxCache(path, baseUrl) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+  if (!parsed || typeof parsed !== "object") return void 0;
+  const { apiKey, expiresAt, baseUrl: cachedBaseUrl } = parsed;
+  if (typeof apiKey !== "string" || apiKey === "") return void 0;
+  if (typeof expiresAt !== "string" || Number.isNaN(Date.parse(expiresAt))) return void 0;
+  if (cachedBaseUrl !== baseUrl) return void 0;
+  return { apiKey, expiresAt, baseUrl };
+}
+async function writeSandboxCache(path, sandbox) {
+  await prepareDir(dirname(path));
+  const temp = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await writeFile(temp, `${JSON.stringify(sandbox, null, 2)}
+`, { mode: 384, flag: "wx" });
+    await rename(temp, path);
+  } catch (err) {
+    await rm(temp, { force: true });
+    throw err;
+  }
+}
+async function prepareDir(dir) {
+  await mkdir(dir, { recursive: true, mode: 448 });
+  await chmod(dir, 448);
+}
+var LOCK_STALE_MS = DEFAULT_TIMEOUT_MS + 1e4;
+var LOCK_POLL_MS = 25;
+async function withCacheLock(path, work) {
+  const lock = `${path}.lock`;
+  const token = randomBytes(8).toString("hex");
+  if (!await acquireLock(path, lock, token)) return work();
+  try {
+    return await work();
+  } finally {
+    await releaseLock(lock, token);
+  }
+}
+async function acquireLock(path, lock, token) {
+  try {
+    await prepareDir(dirname(path));
+    for (; ; ) {
+      try {
+        await writeFile(lock, token, { mode: 384, flag: "wx" });
+        return true;
+      } catch (err) {
+        if (err.code !== "EEXIST") return false;
+      }
+      let age;
+      try {
+        age = Date.now() - (await stat(lock)).mtimeMs;
+      } catch (err) {
+        if (err.code === "ENOENT") continue;
+        return false;
+      }
+      if (age > LOCK_STALE_MS) await rm(lock, { force: true });
+      else await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+    }
+  } catch {
+    return false;
+  }
+}
+async function releaseLock(lock, token) {
+  try {
+    if (await readFile(lock, "utf8") === token) await rm(lock, { force: true });
+  } catch {
+  }
+}
+var SandboxConnection = class {
+  path;
+  baseUrl;
+  clientOptions;
+  now;
+  held;
+  pending;
+  constructor(options) {
+    this.path = options.path;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.clientOptions = { baseUrl: this.baseUrl, fetch: options.fetch, headers: options.headers };
+    this.now = options.now ?? Date.now;
+  }
+  async call(work) {
+    let acquired;
+    try {
+      acquired = await this.acquire();
+    } catch (error) {
+      return { ok: false, error, origin: "mint", notes: [] };
+    }
+    const { sandbox, fresh, renewed } = acquired;
+    try {
+      return { ok: true, value: await work(this.clientFor(sandbox)), notes: this.notes(sandbox, renewed) };
+    } catch (error) {
+      if (fresh || !isUnauthorized(error)) {
+        return { ok: false, error, origin: "sandbox", notes: this.notes(sandbox, renewed) };
+      }
+    }
+    let replacement;
+    try {
+      replacement = await this.replace(sandbox);
+    } catch (error) {
+      return { ok: false, error, origin: "mint", notes: [] };
+    }
+    try {
+      return { ok: true, value: await work(this.clientFor(replacement)), notes: this.notes(replacement, true) };
+    } catch (error) {
+      return { ok: false, error, origin: "sandbox", notes: this.notes(replacement, true) };
+    }
+  }
+  /**
+   * The sandbox for this call: the one held while it lasts, then the file's,
+   * then a new one.
+   *
+   * `fresh` is whether it was minted for this call. `renewed` is whether it
+   * replaced a sandbox this server or the file had, so the codes from that one
+   * are gone.
+   */
+  async acquire() {
+    const held = this.held;
+    if (held && !this.expired(held)) return { sandbox: held, fresh: false, renewed: false };
+    const sandbox = await this.single(() => this.load());
+    return {
+      sandbox,
+      fresh: sandbox.minted,
+      renewed: held ? sandbox.apiKey !== held.apiKey : sandbox.replaced
+    };
+  }
+  async load() {
+    const cached = await readSandboxCache(this.path, this.baseUrl);
+    if (cached && !this.expired(cached)) return this.adopt(cached, false);
+    return withCacheLock(this.path, async () => {
+      const again = await readSandboxCache(this.path, this.baseUrl);
+      if (again && !this.expired(again)) return this.adopt(again, cached !== void 0);
+      return this.mint(cached !== void 0 || again !== void 0);
+    });
+  }
+  /**
+   * A sandbox in place of `refused`, unless a concurrent call, or another
+   * server, already made one.
+   */
+  replace(refused) {
+    return this.single(async () => {
+      const held = this.held;
+      if (held && held.apiKey !== refused.apiKey && !this.expired(held)) return held;
+      return withCacheLock(this.path, async () => {
+        const cached = await readSandboxCache(this.path, this.baseUrl);
+        if (cached && cached.apiKey !== refused.apiKey && !this.expired(cached)) return this.adopt(cached, true);
+        return this.mint(true);
+      });
+    });
+  }
+  /** Hold a sandbox another server minted, which this one found in the file. */
+  adopt(cached, replaced) {
+    this.held = { ...cached, minted: false, replaced };
+    return this.held;
+  }
+  async mint(replaced) {
+    const { account } = await XTkn.createSandbox(this.clientOptions);
+    if (typeof account?.apiKey !== "string" || !account.apiKey || Number.isNaN(Date.parse(account.expiresAt))) {
+      throw new XTknError("X-TKN started a sandbox but returned no key or expiry for it", 0);
+    }
+    const sandbox = { apiKey: account.apiKey, expiresAt: account.expiresAt, baseUrl: this.baseUrl };
+    let unsaved;
+    try {
+      await writeSandboxCache(this.path, sandbox);
+    } catch (err) {
+      unsaved = err?.code ?? "write failed";
+    }
+    this.held = { ...sandbox, minted: true, replaced, unsaved };
+    return this.held;
+  }
+  /** One mint or file read at a time. Concurrent first calls share the one sandbox. */
+  single(start) {
+    this.pending ??= start().finally(() => {
+      this.pending = void 0;
+    });
+    return this.pending;
+  }
+  expired(sandbox) {
+    return Date.parse(sandbox.expiresAt) <= this.now();
+  }
+  clientFor(sandbox) {
+    return new XTkn({ ...this.clientOptions, apiKey: sandbox.apiKey });
+  }
+  notes(sandbox, renewed) {
+    const line = sandboxLine(sandbox, this.path);
+    return renewed ? [SANDBOX_RENEWED_MESSAGE, line] : [line];
+  }
+};
+function isUnauthorized(err) {
+  return err instanceof XTknAuthError && err.status === 401;
+}
+
+// src/version.ts
+var VERSION = "1.3.0";
+
+// src/env.ts
+var USER_AGENT = `x-tkn-mcp/${VERSION}`;
+function apiKeyFrom(env) {
+  for (const name of API_KEY_ENV_VARS) {
+    if (env[name]) return env[name];
+  }
+  return void 0;
+}
+function clientFrom(env, options = {}) {
+  return new XTkn({ ...options, apiKey: apiKeyFrom(env), headers: { "User-Agent": USER_AGENT } });
+}
+function sandboxCachePath(env, home = homedir()) {
+  const xdg = env.XDG_CONFIG_HOME;
+  const configHome = xdg && isAbsolute(xdg) ? xdg : join(home, ".config");
+  return join(configHome, "x-tkn", "sandbox.json");
+}
+function connectionFrom(env, options = {}) {
+  const { home, now, ...client } = options;
+  if (apiKeyFrom(env)) return keyConnection(clientFrom(env, client));
+  return new SandboxConnection({
+    ...client,
+    path: sandboxCachePath(env, home),
+    headers: { "User-Agent": USER_AGENT },
+    now
+  });
+}
+
 // src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
 var INSTRUCTIONS = [
   "X-TKN hands a secret to a person as a one-time link.",
   "create_secret encrypts the secret on this machine. X-TKN stores only ciphertext, and the key travels in the link after the #.",
   "There is no tool to read a secret back. After handing one over you can check whether it was opened (check_status) or cancel it (revoke_secret).",
-  "Give the link only to the person it is for: opening it uses it up. If you set a passphrase, send it by a different channel than the link."
+  "Give the link only to the person it is for: opening it uses it up. If you set a passphrase, send it by a different channel than the link.",
+  // Read at connect time, before any tool call can say it. An agent with no
+  // key should start building, not stop to ask a person to sign up, and since
+  // 1.2.0 it need not even fetch a key: `connectionFrom` mints one.
+  "With no X_TKN_API_KEY set, this server gets a sandbox key itself on the first tool call: no signup, and it creates real secrets for 24 hours, long enough to build and test the integration.",
+  "To keep a sandbox past its 24 hours, call claim_sandbox and give the link it returns to the person who should keep it.",
+  `Its key still ends on schedule after a claim. For a key that stays, a person signs up at ${SIGNUP_URL} for a free Developer key.`
 ].join(" ");
 var durationField = z.number().int().min(0);
 var expiresIn = z.object({
@@ -817,7 +1119,8 @@ var statusShape = {
   expiresAt: z.string().nullable(),
   createdAt: z.string().nullable()
 };
-function createXtknMcpServer({ client }) {
+function createXtknMcpServer(options) {
+  const connection = "connection" in options ? options.connection : keyConnection(options.client);
   const server = new McpServer({ name: "x-tkn", title: "X-TKN", version: VERSION }, { instructions: INSTRUCTIONS });
   server.registerTool(
     "create_secret",
@@ -826,7 +1129,9 @@ function createXtknMcpServer({ client }) {
       description: "Turn a secret (a password, API key, recovery code or private note) into a link a person opens once. The secret is encrypted on this machine before anything is sent, and X-TKN never holds the key. The link stops working once opened, or at its expiry. You cannot read the secret back afterwards: this server has no read tool. Returns the link and a code for check_status and revoke_secret. Up to 64 KB on the free Developer plan, 256 KB on Team and Enterprise.",
       inputSchema: {
         secret: z.string().min(1).describe("The secret to hand over. It is encrypted before it leaves this machine."),
-        expiresIn: expiresIn.optional().describe("How long the link works if nobody opens it. Defaults to the plan's: 7 days on Developer, 30 on Team."),
+        expiresIn: expiresIn.optional().describe(
+          "How long the link works if nobody opens it. Defaults to the plan's: 7 days on Developer, 30 on Team. On a sandbox key it cannot run past the sandbox, which ends 24 hours after it was created, and defaults to that end."
+        ),
         passphrase: z.string().min(8).max(256).optional().describe(
           "Make the recipient type this before the secret opens. Send it by a different channel than the link. X-TKN stores a hash of it, which gates the link and plays no part in the encryption. Team plan and above."
         ),
@@ -845,18 +1150,18 @@ function createXtknMcpServer({ client }) {
       },
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
     },
-    (args) => run(async () => created(await createSecret(client, args)))
+    (args) => run(connection, async (client) => created(await createSecret(client, args)))
   );
   server.registerTool(
     "check_status",
     {
       title: "Check a secret link",
-      description: "Whether a secret link is still waiting, has been opened, expired, or was revoked. Never returns the secret.",
+      description: "Whether a secret link is still waiting, has been opened, expired, or was revoked. Never returns the secret. Each call is one metered operation, and a sandbox has 100 in all, so call this no more often than every 30 seconds.",
       inputSchema: { code },
       outputSchema: statusShape,
       annotations: { readOnlyHint: true, openWorldHint: true }
     },
-    ({ code: code2 }) => run(async () => status(await checkStatus(client, code2)))
+    ({ code: code2 }) => run(connection, async (client) => status(await checkStatus(client, code2)))
   );
   server.registerTool(
     "revoke_secret",
@@ -867,16 +1172,28 @@ function createXtknMcpServer({ client }) {
       outputSchema: statusShape,
       annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true }
     },
-    ({ code: code2 }) => run(async () => status(await revokeSecret(client, code2)))
+    ({ code: code2 }) => run(connection, async (client) => status(await revokeSecret(client, code2)))
+  );
+  server.registerTool(
+    "claim_sandbox",
+    {
+      title: "Get a link that keeps this sandbox",
+      description: "Get a one-time link a person opens to claim the sandbox this server's key belongs to, so the account outlives its 24 hours and keeps its secrets. Give the link only to the person who should keep it. It works once, for 30 minutes or until the sandbox ends if that is sooner, and calling this again voids the earlier link. The sandbox key itself still ends on schedule: a claimed account goes on with a Developer key created for it. Not metered. On a key that is not an unclaimed sandbox it says so and claims nothing.",
+      outputSchema: {
+        claimUrl: z.string().describe("The one-time link for the person who should keep the sandbox."),
+        expiresAt: z.string().describe("When the link stops working if nobody has used it.")
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
+    },
+    () => run(connection, async (client) => claimLink(await claimSandbox(client)))
   );
   return server;
 }
-async function run(work) {
-  try {
-    return await work();
-  } catch (err) {
-    return { content: [{ type: "text", text: describeError(err) }], isError: true };
-  }
+async function run(connection, work) {
+  const called = await connection.call(work);
+  const result = called.ok ? called.value : { content: [{ type: "text", text: describeError(called.error, called.origin) }], isError: true };
+  if (called.notes.length === 0) return result;
+  return { ...result, content: [...result.content, { type: "text", text: called.notes.join("\n") }] };
 }
 function created(secret) {
   const lines = [
@@ -891,6 +1208,19 @@ function created(secret) {
   lines.push(`Code for check_status and revoke_secret: ${secret.code}`);
   return { content: [{ type: "text", text: lines.join("\n") }], structuredContent: { ...secret } };
 }
+function claimLink(link) {
+  const lines = [
+    `Claim link: ${link.claimUrl}`,
+    "Give it to the person who should keep this sandbox, and to nobody else: anyone holding it can claim the sandbox.",
+    `It works once, until ${link.expiresAt}: 30 minutes, or the sandbox's end if that is sooner. Calling claim_sandbox again voids it.`,
+    "Claiming keeps the sandbox's secrets.",
+    CLAIMED_KEY_STILL_ENDS
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: { claimUrl: link.claimUrl, expiresAt: link.expiresAt }
+  };
+}
 var STATUS_TEXT = {
   waiting: "Waiting: not opened yet.",
   opened: "Opened: the recipient has it, and the link no longer works.",
@@ -911,8 +1241,8 @@ async function main(argv) {
 `);
     return;
   }
-  if (!apiKeyFrom(process.env)) console.error(NO_KEY_MESSAGE);
-  const server = createXtknMcpServer({ client: clientFrom(process.env) });
+  if (!apiKeyFrom(process.env)) console.error(sandboxStartupMessage(sandboxCachePath(process.env)));
+  const server = createXtknMcpServer({ connection: connectionFrom(process.env) });
   await server.connect(new StdioServerTransport());
 }
 main(process.argv.slice(2)).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fennecstudio/x-tkn-mcp",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "mcpName": "io.github.fennecstudio/x-tkn-mcp",
   "description": "MCP server for X-TKN: hand a secret to a person as a one-time link, encrypted on your machine. No read tool.",
   "keywords": [