toolstile 0.2.1 → 0.4.0

package/README.md

@@ -27,34 +27,90 @@ scored: remote servers need an entry per client.
 ```text
 toolstile audit · local MCP config check · nothing leaves this machine
 
-Scanned 4 files from Claude Code, Cursor, Codex: 10 MCP servers.
+  Grade C  71/100   2 high · 1 medium
+  10 MCP servers in 4 files from Claude Code, Cursor, Codex
+
+HIGH  Plaintext secrets (2)
+  Anything that can read these files can use the credentials, including
+  backups, dotfile syncs and other tools.
+
+  • github (Cursor)  GitHub token
+    ~/.cursor/mcp.json  mcpServers.github.env.GITHUB_PERSONAL_ACCESS_TOKEN
+  • linear (Claude Code)  authorization header
+    ~/.claude.json  mcpServers.linear.headers.Authorization
+
+  Fix Move them into environment variables, or use the server's OAuth sign-in.
+      Rotate any secret in a file that was shared or synced.
+…
+Fix them: npx toolstile audit --fix (shows every change; you pick which to apply)
+```
+
+## Fix what it finds
+
+```sh
+npx toolstile audit --fix
+```
 
-  Grade B  77/100   1 high · 1 medium · 1 low
+lists every change it can make, as a diff with secret values hidden, then lets
+you pick which to apply (space toggles, enter applies):
 
-HIGH   Plaintext secret in github (Cursor)
-       A GitHub token is written directly into the config file. Anything that can
-       read the file, including backups, dotfile syncs and other tools, can use it.
-       ~/.cursor/mcp.json  mcpServers.github.env.GITHUB_PERSONAL_ACCESS_TOKEN
-       Fix: Reference an environment variable instead (for example ${API_TOKEN}) …
+```text
+  1.  HIGH   github (Cursor): move secret to $GITHUB_PERSONAL_ACCESS_TOKEN
+             ~/.cursor/mcp.json  mcpServers.github.env.GITHUB_PERSONAL_ACCESS_TOKEN
+             - "••••"
+             + "${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+  2.  MEDIUM linear (Claude Code): pin linear-mcp to 1.4.2
+             ~/.claude.json  mcpServers.linear.args[1]
+             - "linear-mcp"
+             + "linear-mcp@1.4.2"
 ```
 
+| Finding | What `--fix` does |
+| --- | --- |
+| Plaintext secret in `env` or a header | Replaces the value with a variable reference in the client's own syntax (`${NAME}` for Claude Code and Gemini CLI, `${env:NAME}` for Cursor, VS Code and Windsurf, `env_vars` / `bearer_token_env_var` / `env_http_headers` for Codex). The value goes into `~/.config/toolstile/secrets.env` (mode 600), and one line in your shell profile (`~/.zshrc`, `~/.bash_profile` or `~/.bashrc`, `~/.profile`, or fish's `conf.d`) loads it. A secret shared by several clients becomes one variable. |
+| Config file with secrets readable by other accounts | `chmod 600` |
+| Unpinned npm or PyPI package | Pins the version that is current now, looked up on npm or PyPI |
+| Rule that approves a whole server, or `enableAllProjectMcpServers` | Removes it. These start unselected, since the agent then asks before each tool. |
+
+Everything else (secrets in arguments or URLs, Claude Desktop and Cline, which
+cannot read variables, Windows, `http://` servers, Docker images, broad
+filesystem roots and auto-approve lists) is listed with what to change by hand.
+
+Each edited file is checked before it is written: it must parse to exactly the
+planned result, or it is left alone. JSON files keep their comments and layout;
+a Codex server's table is rewritten in place. The original files are copied to
+`~/.config/toolstile/backups/` first. They still hold the old secrets, so delete
+them once your agents work. After moving secrets, open a new terminal and restart
+your agents so they start with the variables, and rotate any secret that sat in a
+shared or synced file.
+
+`--dry-run` only shows the changes; `--yes` applies the ones that start selected
+without asking.
+
 ## The audit only reads
 
-- Reads config files on your machine. Writes nothing unless you ask for a card.
-- Makes no network requests and collects no telemetry. (Only the separate
-  `auth` and `mcp` commands below talk to Toolstile, and only when you run them.)
+- Reads config files on your machine. Writes nothing unless you ask for a card,
+  or run `--fix` and confirm the changes.
+- Makes no network requests and collects no telemetry. (`--fix` looks up the
+  current version of the unpinned packages it offers to pin on npm or PyPI. Only
+  the separate `auth` and `mcp` commands below talk to Toolstile, and only when
+  you run them.)
 - Never prints, stores or sends secret values. Findings name the file and key,
   for example `mcpServers.github.env.GITHUB_TOKEN`, and the kind of secret.
 - Never quotes a config file: one that cannot be read or parsed is listed with a
   reason and position only, for example `invalid TOML at line 3, column 12`.
-- About 2,500 lines of TypeScript with one runtime dependency
+- About 3,500 lines of TypeScript with two runtime dependencies
   ([smol-toml](https://github.com/squirrelchat/smol-toml), for Codex's TOML
-  config) and an optional one ([resvg-js](https://github.com/thx/resvg-js), only
+  config, and [jsonc-parser](https://github.com/microsoft/node-jsonc-parser), so
+  `--fix` keeps comments and layout in JSON files) and an optional one ([resvg-js](https://github.com/thx/resvg-js), only
   to render `--card` as PNG). Read it before you run it.
 
 ## Options
 
 ```text
+--fix               Suggest fixes and apply the ones you select
+--yes               With --fix: apply the fixes that start selected, without asking
+--dry-run           With --fix: only show the changes
 --json              Print results as JSON
 --card [file]       Write a shareable grade card (default toolstile-audit.png;
                     use a .svg name for SVG). Contains only the grade and counts.
@@ -109,7 +165,7 @@ values) and prints a ready-to-post link. To post the text report instead, add
 
 ## Connect your agents to Toolstile
 
-If you use [Toolstile](https://toolstile.com), the CLI can also sign in and set
+If you use [Toolstile](https://www.toolstile.com), the CLI can also sign in and set
 up the agents on a machine for you:
 
 ```sh
@@ -155,7 +211,7 @@ dashboard.
 
 | Option | Command | Meaning |
 | --- | --- | --- |
-| `--server <url>` | `auth login` | Toolstile address (default `https://toolstile.com`, or `TOOLSTILE_URL`) |
+| `--server <url>` | `auth login` | Toolstile address (default `https://app.toolstile.com`, or `TOOLSTILE_URL`) |
 | `--no-browser` | `auth login` | Do not try to open a browser on this machine |
 | `--enable <agents>` | `mcp setup` | Turn these on without prompting (comma-separated) |
 | `--disable <agents>` | `mcp setup` | Turn these off without prompting |
@@ -173,7 +229,7 @@ const { grade, findings } = audit();
 ## About
 
 Built by [Akshit Kr Nagpal](https://akshit.io) as part of
-[Toolstile](https://toolstile.com), an MCP gateway that keeps upstream
+[Toolstile](https://www.toolstile.com), an MCP gateway that keeps upstream
 credentials off your machines and lets you choose which tools each agent can use.
 The audit works on its own and does not require a Toolstile account.
 

package/dist/agents.d.ts

@@ -29,6 +29,13 @@ export declare class ManualEditError extends Error {
     readonly snippet: string;
     constructor(target: Target, reason: string, snippet: string);
 }
+/** Replaces the file in one step and keeps its permission bits; a symlink keeps pointing at it. */
+export declare function writeText(link: string, text: string): void;
+/**
+ * Drops `[mcp_servers.<name>]` and its sub-tables, keeping every other line and comment. With
+ * `replacement`, that text goes where the table was (or at the end when there was none).
+ */
+export declare function withoutTomlTable(text: string, server?: string, replacement?: string): string;
 /** The current entry, if the agent's config has one. */
 export declare function readEntry(target: Target): unknown;
 /**

package/dist/agents.js

@@ -65,7 +65,7 @@ function readText(path) {
     }
 }
 /** Replaces the file in one step and keeps its permission bits; a symlink keeps pointing at it. */
-function writeText(link, text) {
+export function writeText(link, text) {
     let path = link;
     let mode = 0o600;
     try {
@@ -92,20 +92,34 @@ function jsonEntry(target, command) {
 function tomlEntry(command) {
     return `[mcp_servers.${ENTRY}]\ncommand = ${JSON.stringify(command.command)}\nargs = [${command.args.map((a) => JSON.stringify(a)).join(", ")}]\n`;
 }
-/** Drops `[mcp_servers.toolstile]` and its sub-tables, keeping every other line and comment. */
-function withoutTomlEntry(text) {
+/**
+ * Drops `[mcp_servers.<name>]` and its sub-tables, keeping every other line and comment. With
+ * `replacement`, that text goes where the table was (or at the end when there was none).
+ */
+export function withoutTomlTable(text, server = ENTRY, replacement) {
     const lines = text.split("\n");
     const out = [];
     let skipping = false;
+    const plain = (header) => header.replace(/\s+/g, "").replace(/"/g, "");
+    const table = plain(`mcp_servers.${server}`);
     for (const line of lines) {
         const header = line.match(/^\s*\[\s*([^\]]+?)\s*\]\s*(#.*)?$/)?.[1];
         if (header !== undefined) {
-            const name = header.replace(/\s+/g, "").replace(/"/g, "");
-            skipping = name === `mcp_servers.${ENTRY}` || name.startsWith(`mcp_servers.${ENTRY}.`);
+            const name = plain(header);
+            skipping = name === table || name.startsWith(`${table}.`);
+        }
+        if (skipping && replacement !== undefined) {
+            out.push(replacement.replace(/\n+$/, ""), "");
+            replacement = undefined;
         }
         if (!skipping)
             out.push(line);
     }
+    if (replacement !== undefined) {
+        while (out.length && out[out.length - 1].trim() === "")
+            out.pop();
+        out.push(...(out.length ? [""] : []), replacement.replace(/\n+$/, ""), "");
+    }
     return out.join("\n").replace(/\n{3,}$/, "\n\n");
 }
 /** The current entry, if the agent's config has one. */
@@ -140,7 +154,7 @@ export function writeEntry(target, command) {
         const existing = current?.[ENTRY];
         if (!command && (existing === undefined || !isProxyEntry(existing)))
             return "unchanged";
-        let next = withoutTomlEntry(text);
+        let next = withoutTomlTable(text);
         if (command)
             next = `${next.replace(/\s*$/, "")}${next.trim() ? "\n\n" : ""}${tomlEntry(command)}`;
         let parsed;

package/dist/api.d.ts

@@ -20,6 +20,8 @@ export interface Account {
         id: string;
         label: string;
     } | null;
+    /** The gateway URL agents use; it can be on another host than this API. */
+    mcpUrl?: string;
 }
 export interface DeviceCode {
     device_code: string;

package/dist/checks.d.ts

@@ -1,5 +1,26 @@
 import { type Discovery } from "./sources.js";
-import type { Finding, ServerEntry } from "./types.js";
+import type { Finding, Location, ServerEntry } from "./types.js";
+export interface Secret {
+    server: ServerEntry;
+    location: Location;
+    /** Keys below the server object, for example `["env", "TOKEN"]`. */
+    keys: string[];
+    kind: string;
+    hash: string;
+    /** Kept in memory only, for `audit --fix` to move; never printed. */
+    value: string;
+}
+export declare function secretsOf(s: ServerEntry): Secret[];
+interface Words {
+    list: string[];
+    /** For each word, its index in `args`, or -1 when it comes from `command`. */
+    arg: number[];
+}
+/**
+ * Splits `command` and `args` into words, handling configs that put the whole command in one string,
+ * and skips Windows wrappers (`cmd /c npx …`, `wsl npx …`) so the real launcher comes first.
+ */
+export declare function words(s: ServerEntry): Words;
 interface Package {
     registry: "npm" | "pypi" | "docker";
     name: string;
@@ -11,6 +32,7 @@ interface Package {
 }
 /** Finds the package a launcher such as npx, uvx or docker runs. */
 export declare function packageOf(s: ServerEntry): Package | null;
+export declare const isPinned: (p: Package) => boolean;
 /** A stable identity for the same server configured in several places. */
 export declare function identityOf(s: ServerEntry): string | null;
 /** A path for a shell command: `~/...` under the home folder, single-quoted when needed. */

package/dist/checks.js

@@ -8,9 +8,9 @@ const at = (s, ...keys) => ({
     pointer: keys.reduce(pointerJoin, s.pointer),
 });
 const hash = (v) => createHash("sha256").update(v.trim()).digest("hex");
-function secretsOf(s) {
+export function secretsOf(s) {
     const out = [];
-    const add = (value, kind, ...keys) => out.push({ server: s, location: at(s, ...keys), kind, hash: hash(value) });
+    const add = (value, kind, ...keys) => out.push({ server: s, location: at(s, ...keys), keys, kind, hash: hash(value), value });
     for (const [k, v] of Object.entries(s.env)) {
         const kind = classify(k, v);
         if (kind)
@@ -19,7 +19,7 @@ function secretsOf(s) {
     for (const [k, v] of Object.entries(s.headers)) {
         const kind = classify(k, v);
         if (kind)
-            add(v, kind, "headers", k);
+            add(v, kind, s.headerKeys[k] ?? "headers", k);
     }
     for (const [k, v] of Object.entries(s.extraSecrets)) {
         const kind = classify(k, v);
@@ -75,7 +75,7 @@ function afterWrapper(list, start) {
  * Splits `command` and `args` into words, handling configs that put the whole command in one string,
  * and skips Windows wrappers (`cmd /c npx …`, `wsl npx …`) so the real launcher comes first.
  */
-function words(s) {
+export function words(s) {
     if (!s.command)
         return { list: [], arg: [] };
     const oneString = s.args.length === 0 && /\s/.test(s.command.trim());
@@ -168,7 +168,7 @@ function parsePackage(registry, spec, wordIndex, argIndex) {
         ? { registry, name: spec.slice(0, at), version: spec.slice(at + 1), ...where }
         : { registry, name: spec, version: null, ...where };
 }
-const isPinned = (p) => p.version !== null &&
+export const isPinned = (p) => p.version !== null &&
     p.version !== "latest" &&
     p.version !== "next" &&
     !/[\^~*xX><]/.test(p.version) &&
@@ -227,6 +227,8 @@ export function runChecks(d, home) {
             rule: "plaintext-secret",
             severity: "high",
             title: `Plaintext secret in ${label(server)}`,
+            subject: label(server),
+            note: kinds,
             detail: `${what} written directly into the config file. Anything that can read the file, including backups, dotfile syncs and other tools, can use ${one ? "it" : "them"}.`,
             fix: "Reference an environment variable instead (for example ${API_TOKEN}, or \"Bearer ${API_TOKEN}\" in a header), or use the server's OAuth sign-in. Rotate the secret if the file was ever shared or synced.",
             locations: list.map((s) => s.location),
@@ -246,6 +248,8 @@ export function runChecks(d, home) {
             rule: "copied-secret",
             severity: "medium",
             title: `Same ${list[0].kind} copied into ${files.size} files`,
+            subject: `${list[0].kind} in ${[...new Set(list.map((s) => s.server.name))].join(", ")}`,
+            note: [...new Set(list.map((s) => CLIENT_NAMES[s.server.client]))].join(", "),
             detail: `One credential is pasted into ${files.size} separate config files (${[...new Set(list.map((s) => CLIENT_NAMES[s.server.client]))].join(", ")}). Rotating or revoking it means finding every copy.`,
             fix: "Keep one copy in your environment or keychain and reference it from each client, or route the clients through one gateway.",
             locations: list.map((s) => s.location),
@@ -262,6 +266,8 @@ export function runChecks(d, home) {
             rule: "readable-config",
             severity: "medium",
             title: "Config file with secrets is readable by other accounts",
+            subject: f.path,
+            note: `permissions ${f.mode.toString(8).padStart(3, "0")}, open to ${open}`,
             detail: `This file holds plaintext secrets and has permissions ${f.mode.toString(8).padStart(3, "0")}, and every folder above it is open to ${open}, so ${who} can read it.`,
             fix: `Restrict it to your user: chmod 600 ${shellPath(f.path, home)}`,
             locations: [{ file: f.path, pointer: "(file permissions)" }],
@@ -277,6 +283,8 @@ export function runChecks(d, home) {
                         rule: "insecure-transport",
                         severity: "high",
                         title: `Unencrypted remote server: ${label(s)}`,
+                        subject: label(s),
+                        note: `http://${u.host}`,
                         detail: `${u.host} is reached over plain http://, so requests, tool results and any credentials travel unencrypted.`,
                         fix: "Use the server's https:// endpoint.",
                         locations: [at(s, "url")],
@@ -295,6 +303,8 @@ export function runChecks(d, home) {
                 rule: "unpinned-package",
                 severity: "medium",
                 title: `Unpinned ${where}: ${label(s)}`,
+                subject: label(s),
+                note: `${pkg.name}${pkg.version ? `@${pkg.version}` : ""}`,
                 detail: `${pkg.name}${pkg.version ? `@${pkg.version}` : ""} resolves to whatever version is newest each time the server starts, so a compromised or broken release runs with this server's access.`,
                 fix: pkg.registry === "docker"
                     ? `Pin an image digest or exact tag, for example ${pkg.name}:<version>.`
@@ -311,6 +321,8 @@ export function runChecks(d, home) {
                     rule: "privileged-container",
                     severity: "high",
                     title: `Container with host-level access: ${label(s)}`,
+                    subject: label(s),
+                    note: [...new Set(risky)].join(", "),
                     detail: `The server runs with ${[...new Set(risky)].join(", ")}, which gives it effective control of the host.`,
                     fix: "Remove --privileged and the Docker socket mount unless the server truly needs them.",
                     locations: [at(s, "args")],
@@ -324,6 +336,8 @@ export function runChecks(d, home) {
                 rule: "broad-filesystem",
                 severity: "medium",
                 title: `Filesystem server can read ${roots.includes("/") ? "the whole disk" : "your whole home folder"}: ${label(s)}`,
+                subject: label(s),
+                note: `allowed root ${roots.join(", ")}`,
                 detail: `Allowed root ${roots.join(", ")} includes SSH keys, cloud credentials and every other config file.`,
                 fix: "Allow only the project folders the agent needs.",
                 locations: [at(s, "args")],
@@ -335,6 +349,8 @@ export function runChecks(d, home) {
                 rule: "auto-approved-tools",
                 severity: "low",
                 title: `${s.autoApproved.length} tool${s.autoApproved.length === 1 ? "" : "s"} run without asking: ${label(s)}`,
+                subject: label(s),
+                note: `${s.autoApproved.slice(0, 4).join(", ")}${s.autoApproved.length > 4 ? `, +${s.autoApproved.length - 4} more` : ""}`,
                 detail: `Auto-approved: ${s.autoApproved.slice(0, 6).join(", ")}${s.autoApproved.length > 6 ? ", …" : ""}. A prompt injection in any content the agent reads can call these.`,
                 fix: "Keep auto-approval to read-only tools.",
                 locations: [at(s)],
@@ -350,6 +366,8 @@ export function runChecks(d, home) {
             title: all
                 ? `${CLIENT_NAMES[a.client]} approves ${a.subject === "mcp__*" ? "every MCP tool" : a.subject} without asking`
                 : `${CLIENT_NAMES[a.client]} runs every tool of ${a.subject.replace(/^mcp__/, "").replace(/__\*$/, "")} without asking`,
+            subject: `${a.subject} (${CLIENT_NAMES[a.client]})`,
+            note: all ? "every tool" : "every tool of the server",
             detail: `Permission rule ${a.subject} skips the confirmation prompt, including for write and delete tools. A prompt injection in a web page, issue or email the agent reads can call them.`,
             fix: "Allow specific read-only tools (mcp__server__tool) instead of whole servers.",
             locations: [a.location],
@@ -372,6 +390,8 @@ export function runChecks(d, home) {
             rule: "duplicated-server",
             severity: "info",
             title: `${list[0].name} is set up separately in ${clients.length} clients`,
+            subject: list[0].name,
+            note: clients.map((c) => CLIENT_NAMES[c]).join(", "),
             detail: `Configured in ${clients.map((c) => CLIENT_NAMES[c]).join(", ")}. Each copy has its own settings and sign-in to keep in sync and revoke.`,
             fix: "Nothing to fix; listed so you know where each copy lives.",
             locations: list.map((s) => at(s)),

package/dist/cli.js

@@ -5,12 +5,14 @@ import { resolve } from "node:path";
 import { createApi } from "./api.js";
 import { renderCard, shareText, shareUrl } from "./card.js";
 import { login, logout, proxy, setup, UserError } from "./commands.js";
+import { runFix } from "./fix.js";
 import { audit } from "./index.js";
 import { redact, renderJson, renderReport, style } from "./report.js";
 const HELP = `toolstile: audit your MCP configs and connect your agents to Toolstile
 
 Usage
   npx toolstile audit [options]     Check local MCP configs (offline, read-only)
+  npx toolstile audit --fix         Review suggested fixes and apply the ones you pick
   npx toolstile auth login          Sign in, from any machine, with a code
   npx toolstile auth logout         Sign out on this machine
   npx toolstile mcp setup           Choose which agents here use Toolstile
@@ -32,7 +34,21 @@ filesystem access and unencrypted remote servers.
 It only reads files. It sends nothing over the network and never
 prints secret values.
 
+With --fix it lists every change it can make, then applies the ones
+you select:
+  - moves plaintext secrets into environment variables, saved in an
+    owner-only file your shell loads, and references them from the config
+  - restricts config files that hold secrets to your user (chmod 600)
+  - pins unpinned npm and PyPI packages to their current version (the
+    only network use: it looks those versions up on npm and PyPI)
+  - removes rules that approve whole servers without asking (off at first)
+Original files are backed up before they change. Findings it cannot fix
+safely are listed with what to do by hand.
+
 Options
+  --fix               Suggest fixes and apply the ones you select
+  --yes               With --fix: apply the fixes that start selected, without asking
+  --dry-run           With --fix: only show the changes
   --json              Print results as JSON
   --card [file]       Write a shareable grade card (default toolstile-audit.png;
                       use a .svg name for SVG). Contains only the grade and counts.
@@ -52,7 +68,7 @@ login prints a link and a code. Open the link on any device with a browser
 reach this machine, so it works over SSH and on servers without a browser.
 
 Options
-  --server <url>      Toolstile address (default https://toolstile.com, or TOOLSTILE_URL)
+  --server <url>      Toolstile address (default https://app.toolstile.com, or TOOLSTILE_URL)
   --no-browser        Do not try to open a browser on this machine
 `;
 const MCP_HELP = `toolstile mcp: connect the agents on this machine to Toolstile
@@ -80,7 +96,7 @@ function version() {
     return pkg.version;
 }
 function parseArgs(argv) {
-    const args = { json: false, redact: false, card: null, project: process.cwd(), failOn: null };
+    const args = { fix: false, yes: false, dryRun: false, json: false, redact: false, card: null, project: process.cwd(), failOn: null };
     const rest = [...argv];
     if (rest[0] === "audit")
         rest.shift();
@@ -101,6 +117,16 @@ function parseArgs(argv) {
             case "-v":
             case "--version":
                 return "version";
+            case "--fix":
+                args.fix = true;
+                break;
+            case "--yes":
+            case "-y":
+                args.yes = true;
+                break;
+            case "--dry-run":
+                args.dryRun = true;
+                break;
             case "--json":
                 args.json = true;
                 break;
@@ -136,6 +162,10 @@ function parseArgs(argv) {
                 throw new Error(`Unknown option: ${a}`);
         }
     }
+    if ((args.yes || args.dryRun) && !args.fix)
+        throw new Error(`${args.yes ? "--yes" : "--dry-run"} only works with --fix`);
+    if (args.fix && (args.json || args.card || args.redact || args.failOn))
+        throw new Error("--fix cannot be combined with --json, --card, --redact or --fail-on");
     return args;
 }
 async function writeCard(path, svg) {
@@ -260,6 +290,19 @@ async function main() {
         return 0;
     }
     const home = homedir();
+    if (args.fix) {
+        return runFix({
+            home,
+            cwd: args.project,
+            platform: process.platform,
+            env: process.env,
+            stdin: process.stdin,
+            stdout: process.stdout,
+            style: style(process.stdout.isTTY === true && !process.env.NO_COLOR),
+            yes: args.yes,
+            dryRun: args.dryRun,
+        });
+    }
     const raw = audit({ home, cwd: args.project });
     const result = args.redact ? redact(raw, home, args.project) : raw;
     const color = !args.json && process.stdout.isTTY === true && !process.env.NO_COLOR;
@@ -267,7 +310,7 @@ async function main() {
     if (args.json)
         process.stdout.write(renderJson(result));
     else
-        process.stdout.write(renderReport(result, home, s, args.redact));
+        process.stdout.write(renderReport(result, home, s, args.redact, process.stdout.columns || 80));
     if (args.card) {
         if (result.grade === null) {
             process.stderr.write("No MCP servers found, so there is no grade to put on a card.\n");

package/dist/commands.d.ts

@@ -23,6 +23,8 @@ export declare class UserError extends Error {
 }
 /** HTTPS, except a loopback server for local development. */
 export declare function normalizeServer(value: string): string;
+/** A gateway URL the server reported: HTTPS (or loopback HTTP) with no credentials, else undefined. */
+export declare function gatewayUrl(value: unknown): string | undefined;
 export declare function login(ctx: Context, options: {
     server?: string;
     browser: boolean;

package/dist/commands.js

@@ -20,13 +20,31 @@ export function normalizeServer(value) {
         url = new URL(value);
     }
     catch {
-        throw new UserError(`--server must be a URL, for example https://toolstile.com`);
+        throw new UserError(`--server must be a URL, for example https://app.toolstile.com`);
     }
     const loopback = /^(localhost|127\.\d+\.\d+\.\d+|\[::1\])$/.test(url.hostname);
     if (url.protocol !== "https:" && !(loopback && url.protocol === "http:"))
         throw new UserError("--server must use https://");
     return url.origin;
 }
+/** A gateway URL the server reported: HTTPS (or loopback HTTP) with no credentials, else undefined. */
+export function gatewayUrl(value) {
+    if (typeof value !== "string")
+        return undefined;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+    const loopback = /^(localhost|127\.\d+\.\d+\.\d+|\[::1\])$/.test(url.hostname);
+    if (url.username || url.password || url.search || url.hash)
+        return undefined;
+    if (url.protocol !== "https:" && !(loopback && url.protocol === "http:"))
+        return undefined;
+    return url.href;
+}
 function defaultOpenBrowser(ctx) {
     return (url) => {
         // Over SSH or without a display the URL and code are enough; nothing to open.
@@ -180,6 +198,8 @@ export async function setup(ctx, options) {
     const both = enable.find((c) => disable.includes(c));
     if (both)
         throw new UserError(`${CLIENT_NAMES[both]} is in both --enable and --disable.`);
+    // The gateway can be on another host; only an HTTPS URL from this server is used.
+    const endpoint = gatewayUrl(account.mcpUrl) ?? `${state.server}/mcp`;
     const workspace = await chooseWorkspace(ctx, state, account.workspaces, options.workspace);
     state.workspace = { id: workspace.id, slug: workspace.slug, name: workspace.name };
     saveState(state, stateEnv(ctx));
@@ -254,6 +274,10 @@ export async function setup(ctx, options) {
         const want = wanted.has(target.client);
         const link = state.agents[target.client];
         if (want) {
+            if (live(target.client) && link && link.endpoint !== endpoint) {
+                link.endpoint = endpoint;
+                saveState(state, stateEnv(ctx));
+            }
             if (!live(target.client)) {
                 if (link)
                     await removeRemote(link).catch(() => undefined);
@@ -263,6 +287,7 @@ export async function setup(ctx, options) {
                     id: created.id,
                     workspaceId: workspace.id,
                     server: state.server,
+                    endpoint,
                     label: created.label,
                     token: created.token,
                 };
@@ -324,7 +349,7 @@ export async function setup(ctx, options) {
     }
     if ([...wanted].length) {
         print(ctx);
-        print(ctx, `Choose which MCP servers they can use: ${state.server}/app/${workspace.slug}/access`);
+        print(ctx, `Choose which MCP servers they can use: ${state.server}/${workspace.slug}/access`);
     }
     return manual.length ? 1 : 0;
 }
@@ -338,7 +363,7 @@ export async function proxy(ctx, agent) {
         throw new UserError(`${CLIENT_NAMES[client]} is not enabled on this machine. Run toolstile mcp setup.`);
     await runProxy({
         // The token goes only to the server that issued it, whatever the environment says.
-        endpoint: `${link.server}/mcp`,
+        endpoint: link.endpoint ?? `${link.server}/mcp`,
         token: link.token,
         input: ctx.stdin,
         output: ctx.stdout,