@fennecstudio/x-tkn-mcp 1.0.0 → 1.2.0

package/README.md

@@ -22,18 +22,41 @@ 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`.
+- A person can keep a sandbox by claiming it at `POST /accounts/claim` with the
+  key from that file. 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. Claim it, 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 +70,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,7 +79,7 @@ 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.               |
@@ -74,6 +94,10 @@ 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

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}
+   * 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
@@ -587,24 +594,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 +729,22 @@ 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_CLAIM_ENDPOINT = "POST /accounts/claim";
+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, a person can claim the account at ${SANDBOX_CLAIM_ENDPOINT}, 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 nobody can claim it, and this server loses it when it stops.`;
+  }
+  return `${ends} To keep it, a person claims it at ${SANDBOX_CLAIM_ENDPOINT} with the key saved in ${path}. 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.");
@@ -771,16 +791,24 @@ 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, a person can claim the sandbox at ${SANDBOX_CLAIM_ENDPOINT}, which 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") {
+      const claim = err.claimEndpoint ?? SANDBOX_CLAIM_ENDPOINT;
+      return `${err.message} This needs ${plan}, and this is a sandbox key: a person has to claim the account at ${claim} before it can be upgraded.`;
+    }
     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 +822,246 @@ 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.2.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.",
+  `For a key that stays, a person can claim the sandbox at ${SANDBOX_CLAIM_ENDPOINT}, or sign up at ${SIGNUP_URL} for a free Developer key.`
 ].join(" ");
 var durationField = z.number().int().min(0);
 var expiresIn = z.object({
@@ -817,7 +1079,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 +1089,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 +1110,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 +1132,15 @@ 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)))
   );
   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 = [
@@ -911,8 +1175,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.2.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": [