nansen-cli 1.41.1 → 1.43.0

package/src/cli.js

@@ -11,6 +11,7 @@ import { buildTradingCommands } from './trading.js';
 import { buildLimitOrderCommands } from './limit-order.js';
 import { formatAlertsTable, buildAlertsCommands } from './commands/alerts.js';
 import { buildAgentCommands } from './commands/agent.js';
+import { buildMcpCommands } from './commands/mcp.js';
 import { buildResearchCommands, RESEARCH_HISTORICAL_SUBCOMMANDS } from './commands/research.js';
 import { resolveAddress, isEnsName } from './ens.js';
 import fs from 'fs';
@@ -190,7 +191,7 @@ export function parseArgs(args) {
       const key = arg.slice(2);
       const next = args[i + 1];
       
-      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled' || key === 'expert' || key === 'json' || key === 'offline' || key === 'no-simulate' || key === 'no-verify-outcome' || key === 'no-revoke-excessive-allowance') {
+      if (key === 'pretty' || key === 'help' || key === 'version' || key === 'table' || key === 'no-retry' || key === 'cache' || key === 'no-cache' || key === 'stream' || key === 'enrich' || key === 'full' || key === 'human' || key === 'enabled' || key === 'disabled' || key === 'expert' || key === 'json' || key === 'offline' || key === 'no-simulate' || key === 'no-verify-outcome' || key === 'no-revoke-excessive-allowance' || key === 'dry-run') {
         result.flags[key] = true;
       } else if (next && (!next.startsWith('-') || /^-\d/.test(next))) {
         // Try to parse as JSON first (for objects/arrays/booleans),
@@ -734,9 +735,10 @@ COMMANDS:
   agent       Ask the Nansen AI research agent (fast/expert modes)
   alerts      list, create, update, toggle, delete
   web         search, fetch
+  mcp         install/uninstall/verify the Nansen MCP server
   account     Show API key status, plan, and remaining credits
   auth        status — offline auth status: key source, wallets (no network)
-  login       Save API key (--api-key <key>, --human, or NANSEN_API_KEY env var)
+  login       Save API key (--human, NANSEN_API_KEY, or --api-key <key>)
   logout      Remove saved API key
   doctor      Diagnostics: auth, wallets, caches, connectivity (--offline --json)
   schema      JSON schema for all commands (use "nansen schema <cmd>" for one)
@@ -827,43 +829,45 @@ CROSS-CHAIN NOTES (when using --to-chain):
   Bridge providers: Li.Fi or Relay (selected automatically based on best price)
   Typical bridge time: 1-5 minutes`;
 
-// Helper to prompt for input (exported for mocking)
-export async function prompt(question, hidden = false) {
+// Helper to prompt for input (exported for mocking). Output defaults to stderr
+// so the prompt and masked `*` characters stay on the terminal and never land
+// in a redirected stdout (matching wallet.js promptPassword).
+export async function prompt(question, hidden = false, { input = process.stdin, output = process.stderr } = {}) {
   return new Promise((resolve) => {
-    if (hidden && process.stdout.isTTY) {
-      process.stdout.write(question);
-      let input = '';
-      process.stdin.setRawMode(true);
-      process.stdin.resume();
-      process.stdin.setEncoding('utf8');
+    if (hidden && input.isTTY) {
+      output.write(question);
+      let value = '';
+      input.setRawMode(true);
+      input.resume();
+      input.setEncoding('utf8');
       
       const onData = (char) => {
         if (char === '\n' || char === '\r') {
-          process.stdin.setRawMode(false);
-          process.stdin.pause();
-          process.stdin.removeListener('data', onData);
-          process.stdout.write('\n');
-          resolve(input);
+          input.setRawMode(false);
+          input.pause();
+          input.removeListener('data', onData);
+          output.write('\n');
+          resolve(value);
         } else if (char === '\u0003') {
           // Ctrl+C
           process.exit();
         } else if (char === '\u007F' || char === '\b') {
           // Backspace
-          if (input.length > 0) {
-            input = input.slice(0, -1);
-            process.stdout.write('\b \b');
+          if (value.length > 0) {
+            value = value.slice(0, -1);
+            output.write('\b \b');
           }
         } else {
-          input += char;
-          process.stdout.write('*');
+          value += char;
+          output.write('*');
         }
       };
       
-      process.stdin.on('data', onData);
+      input.on('data', onData);
     } else {
       const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout
+        input,
+        output
       });
       rl.question(question, (answer) => {
         rl.close();
@@ -919,6 +923,7 @@ export function buildCommands(deps = {}) {
       log(formatDoctorReport(checks, { cliVersion: VERSION, offline: Boolean(flags.offline) }));
     },
 
+
     'web': async (args, apiInstance, flags, options) => {
       const subcommand = args[0] || 'help';
       const subArgs = args.slice(1);
@@ -993,13 +998,14 @@ export function buildCommands(deps = {}) {
       if (flags.help || flags.h) {
         log('nansen login - Save your Nansen API key\n');
         log('USAGE:');
-        log('  nansen login --api-key <key>');
-        log('  NANSEN_API_KEY=<key> nansen login');
-        log('  nansen login --human              (interactive prompt)\n');
+        log('  nansen login --human              (interactive prompt; key never enters shell history)');
+        log('  nansen login                      (uses NANSEN_API_KEY when already set)');
+        log('  nansen login --api-key <key>      (literal key IS recorded in shell history)\n');
         log('OPTIONS:');
-        log('  --api-key <key>   Your Nansen API key');
+        log('  --api-key <key>   Your Nansen API key (recorded in shell history — prefer --human)');
         log('  --human           Enable interactive prompt');
         log('  --help            Show this help\n');
+        log('Setting a literal key in a command may record it in shell history.');
         log('Get your API key at: https://app.nansen.ai/auth/agent-setup');
         return;
       }
@@ -1012,9 +1018,9 @@ export function buildCommands(deps = {}) {
 
       if (!apiKey && flags.human) {
         if (!isTTY) {
-          throw new CommandError('--human requires an interactive terminal. Use --api-key or NANSEN_API_KEY env var instead.', 'NOT_A_TTY', {
+          throw new CommandError('--human requires an interactive terminal. Set NANSEN_API_KEY in the environment (or pass --api-key <key>, which is recorded in shell history).', 'NOT_A_TTY', {
             error: 'NOT_A_TTY',
-            message: '--human requires an interactive terminal. Use --api-key or NANSEN_API_KEY env var instead.',
+            message: '--human requires an interactive terminal. Set NANSEN_API_KEY in the environment (or pass --api-key <key>, which is recorded in shell history).',
           });
         }
         log('Nansen CLI Login\n');
@@ -1027,8 +1033,8 @@ export function buildCommands(deps = {}) {
           error: 'API_KEY_REQUIRED',
           message: 'No API key provided.',
           resolution: [
-            'Run: nansen login --api-key <key>',
-            'Or set NANSEN_API_KEY environment variable',
+            'Run in an interactive terminal: nansen login --human',
+            'Or set NANSEN_API_KEY in the environment',
             'Get your API key at: https://app.nansen.ai/auth/agent-setup',
           ],
         });
@@ -1049,13 +1055,28 @@ export function buildCommands(deps = {}) {
           throw new CommandError('The API key is not valid.', 'INVALID_API_KEY', {
             error: 'INVALID_API_KEY',
             message: 'The API key is not valid.',
-            resolution: ['Check your key at https://app.nansen.ai/auth/agent-setup'],
+            resolution: ['Check or rotate your key at https://app.nansen.ai/api?tab=api'],
           });
         }
-        throw new CommandError(`Could not verify API key: ${error.message}`, 'VERIFICATION_FAILED', {
+        // Restore signal from the STRUCTURED error code only — never from
+        // error.message, which can echo the upstream response body (and the key
+        // with it). A transient failure shouldn't read as "check your key".
+        let message = 'Could not verify API key.';
+        let resolution = ['Check your internet connection', 'Try again'];
+        if (error.code === ErrorCode.RATE_LIMITED) {
+          message = 'Rate limited while verifying the API key.';
+          resolution = ['Wait a moment, then run nansen login again'];
+        } else if (error.code === ErrorCode.SERVER_ERROR || error.code === ErrorCode.SERVICE_UNAVAILABLE) {
+          message = 'The Nansen API is unavailable right now, so the key could not be verified.';
+          resolution = ['Try again shortly'];
+        } else if (error.code === ErrorCode.TIMEOUT) {
+          message = 'Timed out verifying the API key.';
+          resolution = ['Check your connection', 'Try again'];
+        }
+        throw new CommandError(message, 'VERIFICATION_FAILED', {
           error: 'VERIFICATION_FAILED',
-          message: `Could not verify API key: ${error.message}`,
-          resolution: ['Check your internet connection', 'Try again'],
+          message,
+          resolution,
         });
       }
 
@@ -1806,13 +1827,13 @@ export function generateSubcommandHelp(command, subcommand, prefix = null) {
   const exampleValues = { address: '0x...', token: '0x...', query: '"term"', symbol: 'BTC', date: '2024-01-01' };
   const chain = subSchema.options?.chain?.default || 'solana';
   const cmdPrefix = prefix || (DEPRECATED_TO_RESEARCH.has(command) ? `research ${command}` : command);
-  let example = `nansen ${cmdPrefix} ${subcommand}`;
-  if (subSchema.options) {
+  let example = subSchema.examples?.[0] || `nansen ${cmdPrefix} ${subcommand}`;
+  if (!subSchema.examples?.length && subSchema.options) {
     for (const [name, opt] of Object.entries(subSchema.options)) {
       if (opt.required) example += ` --${name} ${exampleValues[name] || '<val>'}`;
     }
   }
-  if (subSchema.options?.chain && !subSchema.options.chain.required) {
+  if (!subSchema.examples?.length && subSchema.options?.chain && !subSchema.options.chain.required) {
     example += ` --chain ${chain}`;
   }
   lines.push(`Example: ${example}`);
@@ -1851,7 +1872,8 @@ export async function runCLI(rawArgs, deps = {}) {
   // `auth` and `doctor --offline` promise zero network activity — that
   // contract covers the background update-check fetch and telemetry too,
   // not just the command's own requests.
-  const isOfflineCommand = command === 'auth' || (command === 'doctor' && flags.offline);
+  const isMcpUsage = command === 'mcp' && (subcommand !== 'verify' || flags.help || flags.h);
+  const isOfflineCommand = command === 'auth' || (command === 'doctor' && flags.offline) || isMcpUsage;
   const trackSucceeded = isOfflineCommand ? async () => {} : trackCommandSucceeded;
   const trackFailed = isOfflineCommand ? async () => {} : trackCommandFailed;
 
@@ -1871,7 +1893,9 @@ export async function runCLI(rawArgs, deps = {}) {
     return '';
   };
 
-  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...buildAlertsCommands(deps), ...buildAgentCommands(deps), ...commandOverrides };
+  // mcp prints its own output via `log`; runCLI callers inject their stdout
+  // sink as `output`, so map it across (an explicit `log` dep still wins).
+  const commands = { ...buildCommands(deps), ...buildWalletCommands(deps), ...buildTradingCommands(deps), ...buildAlertsCommands(deps), ...buildAgentCommands(deps), ...buildMcpCommands({ ...deps, log: deps.log ?? output }), ...commandOverrides };
 
   if (flags.version || flags.v) {
     output(VERSION);
@@ -2115,7 +2139,10 @@ export async function runCLI(rawArgs, deps = {}) {
     // data (e.g. PASSWORD_REQUIRED resolution steps) is preserved under `details`,
     // so agents get one consistent shape to branch on regardless of command.
     const errorData = formatError(error);
-    if (isUsageError(errorData, { pretty, table, csv, stream, isTTY })) {
+    if (error.reported) {
+      // The command already printed its full human-readable failure output;
+      // emitting the envelope too would produce two output shapes on stdout.
+    } else if (isUsageError(errorData, { pretty, table, csv, stream, isTTY })) {
       output(errorData.error);
     } else {
       const formatted = formatOutput(errorData, { pretty, table, csv });

package/src/commands/agent.js

@@ -254,6 +254,10 @@ EXAMPLES:
       try {
         response = await fetch(url, {
           method: 'POST',
+          // Never follow a redirect on a request carrying the API key — undici
+          // forwards custom credential headers (apikey) across a cross-origin
+          // redirect, handing the key to whatever host the response points at.
+          redirect: 'error',
           headers: buildHeaders(apiInstance),
           body: JSON.stringify(body),
           signal: controller.signal,

package/src/commands/mcp.js

@@ -0,0 +1,373 @@
+/**
+ * Nansen CLI - MCP install command
+ * One-step install of the hosted Nansen MCP server into local MCP clients.
+ *
+ * Writes a `nansen` entry into the client's own config file (merge-only,
+ * atomic, backed up). No network calls, no shelling out.
+ */
+
+import { CommandError } from '../api.js';
+import { DEFAULT_MCP_URL, formatMcpVerifyReport, runMcpVerifyChecks } from '../mcp-verify.js';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// Hosted Nansen MCP server (streamable HTTP, auth via NANSEN-API-KEY header).
+// Deliberately a constant: a user-supplied URL would let `install` write the
+// API key into a config that sends it to an arbitrary host. NANSEN_BASE_URL
+// (REST dev override) intentionally does not affect this.
+export const NANSEN_MCP_URL = 'https://mcp.nansen.ai/ra/mcp';
+
+// Claude Desktop's config only supports stdio servers, so it bridges through
+// mcp-remote. Pinned exact so `npx -y` never auto-pulls a compromised future
+// release; bump deliberately.
+export const MCP_REMOTE_PIN = 'mcp-remote@0.2.1';
+
+const SERVER_KEY = 'nansen';
+
+// House idiom (see src/api.js CONFIG_DIR): env first so tests can point HOME
+// at a temp dir; os.homedir() as last resort.
+const houseHomedir = () => process.env.HOME || process.env.USERPROFILE || os.homedir();
+
+export const SUPPORTED_CLIENTS = ['claude-code', 'claude-desktop', 'cursor'];
+
+const MCP_USAGE = `nansen mcp — Install the Nansen MCP server into a local MCP client
+
+USAGE:
+  nansen mcp install <client>     Add the Nansen MCP server to the client's config
+  nansen mcp uninstall <client>   Remove the Nansen MCP server from the client's config
+  nansen mcp verify [--api-key <key>] [--url <url>] [--json]
+                                  Verify the hosted MCP server and API key
+
+CLIENTS:
+  claude-code      ~/.claude.json (user scope)
+  claude-desktop   Claude Desktop config (macOS/Windows only)
+  cursor           ~/.cursor/mcp.json
+
+OPTIONS:
+  --dry-run        Preview the change (key redacted) without writing
+
+The API key is taken from \`nansen login\` / NANSEN_API_KEY. Re-run install after
+rotating your key to update the entry. Other clients: https://docs.nansen.ai/mcp/connecting`;
+
+/**
+ * Resolve the client's config file path for this platform.
+ * Throws CommandError for unsupported client/platform combos.
+ */
+export function resolveClientConfigPath(client, { platform = process.platform, homedir = houseHomedir(), env = process.env } = {}) {
+  switch (client) {
+    case 'claude-code':
+      return path.join(env.CLAUDE_CONFIG_DIR || homedir, '.claude.json');
+    case 'cursor':
+      return path.join(homedir, '.cursor', 'mcp.json');
+    case 'claude-desktop':
+      if (platform === 'darwin') {
+        return path.join(homedir, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+      }
+      if (platform === 'win32') {
+        return path.join(env.APPDATA || path.join(homedir, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+      }
+      throw new CommandError('Claude Desktop is not available on Linux. Use: nansen mcp install claude-code', 'UNSUPPORTED_PLATFORM');
+    default:
+      throw new CommandError(`Unknown client: ${client}. Supported: ${SUPPORTED_CLIENTS.join(', ')}`, 'INVALID_PARAMS');
+  }
+}
+
+/**
+ * Build the mcpServers entry for a client.
+ * claude-code/cursor use native remote HTTP; claude-desktop bridges via mcp-remote.
+ */
+export function buildServerEntry(client, apiKey) {
+  switch (client) {
+    case 'claude-code':
+      // "type" is required — a url without type is treated as broken stdio and skipped
+      return { type: 'http', url: NANSEN_MCP_URL, headers: { 'NANSEN-API-KEY': apiKey } };
+    case 'cursor':
+      return { url: NANSEN_MCP_URL, headers: { 'NANSEN-API-KEY': apiKey } };
+    case 'claude-desktop':
+      // Header name and value must be one arg. mcp-remote parses with
+      // /^([A-Za-z0-9_-]+):\s*(.*)$/, so whitespace after the colon is trimmed;
+      // what breaks it is an empty value.
+      // The ${NANSEN_API_KEY} placeholder is NOT shell syntax: mcp-remote itself
+      // substitutes ${VAR} in header values from its process env — see
+      // mcp-remote@0.2.1 dist/chunk-KIPEEEAF.js:29573-29576
+      // (`value.replace(/\$\{([^}]+)}/g, ...)`, logging "Replacing ${...} with
+      // environment value in header"). Claude Desktop injects the `env` block
+      // into the spawned npx process, mcp-remote expands the reference, and the
+      // key never appears in argv (visible in process listings). Verified live:
+      // the exact written config connects to prod with the substitution logged.
+      // Do NOT "fix" this by inlining the key into args.
+      // No --allow-http: the URL is HTTPS.
+      return {
+        command: 'npx',
+        args: ['-y', MCP_REMOTE_PIN, NANSEN_MCP_URL, '--header', 'NANSEN-API-KEY:${NANSEN_API_KEY}'],
+        env: { NANSEN_API_KEY: apiKey },
+      };
+    default:
+      throw new CommandError(`Unknown client: ${client}. Supported: ${SUPPORTED_CLIENTS.join(', ')}`, 'INVALID_PARAMS');
+  }
+}
+
+function assertMergeableServers(config, configPath) {
+  if (typeof config !== 'object' || config === null || Array.isArray(config)) {
+    throw new CommandError(`${configPath} must contain a JSON object. Fix or move the file, then re-run.`, 'INVALID_CONFIG');
+  }
+  if (config.mcpServers !== undefined && (typeof config.mcpServers !== 'object' || config.mcpServers === null || Array.isArray(config.mcpServers))) {
+    throw new CommandError(`"mcpServers" in ${configPath} is not an object. Fix or move the file, then re-run.`, 'INVALID_CONFIG');
+  }
+}
+
+/**
+ * Return a new config object with only mcpServers.nansen set/updated.
+ * Every other key and server entry is preserved.
+ */
+export function mergeNansenEntry(config, entry, configPath = 'config') {
+  assertMergeableServers(config, configPath);
+  return { ...config, mcpServers: { ...config.mcpServers, [SERVER_KEY]: entry } };
+}
+
+/**
+ * Return { config, removed } with mcpServers.nansen deleted.
+ */
+export function removeNansenEntry(config, configPath = 'config') {
+  assertMergeableServers(config, configPath);
+  if (!config.mcpServers || !(SERVER_KEY in config.mcpServers)) {
+    return { config, removed: false };
+  }
+  const { [SERVER_KEY]: _removed, ...rest } = config.mcpServers;
+  return { config: { ...config, mcpServers: rest }, removed: true };
+}
+
+export function buildMcpCommands(deps = {}) {
+  const {
+    log = console.log,
+    fsOverride: fsx = fs,
+    platform = process.platform,
+    homedirFn = houseHomedir,
+    env = process.env,
+    fetchFn = fetch,
+    devConfigPath,
+  } = deps;
+
+  // Follow symlinks so dotfile-managed configs are edited in place instead of
+  // having the link replaced by the atomic rename.
+  const resolveReal = (targetPath) => {
+    let ancestor = targetPath;
+    const missing = [];
+    while (!fsx.existsSync(ancestor)) {
+      const parent = path.dirname(ancestor);
+      if (parent === ancestor) return targetPath;
+      missing.unshift(path.basename(ancestor));
+      ancestor = parent;
+    }
+    try { return path.join(fsx.realpathSync(ancestor), ...missing); } catch { return targetPath; }
+  };
+
+  const readConfig = (configPath) => {
+    if (!fsx.existsSync(configPath)) return { config: {}, existed: false };
+    let raw;
+    try {
+      raw = fsx.readFileSync(configPath, 'utf8');
+    } catch (err) {
+      throw new CommandError(`Could not read ${configPath}: ${err.message}`, 'INVALID_CONFIG');
+    }
+    try {
+      return { config: JSON.parse(raw), existed: true };
+    } catch {
+      throw new CommandError(`Could not parse ${configPath} as JSON. Fix or move the file, then re-run.`, 'INVALID_CONFIG');
+    }
+  };
+
+  // Atomic: temp file in the same dir, then rename over the target.
+  // A crash mid-write can't leave a truncated config. chmod after rename is
+  // best-effort (no-op semantics on Windows) — the file now holds a secret.
+  const writeConfig = (configPath, config) => {
+    const dir = path.dirname(configPath);
+    if (!fsx.existsSync(dir)) fsx.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `.${path.basename(configPath)}.tmp-${process.pid}`);
+    try {
+      fsx.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+      fsx.renameSync(tmp, configPath);
+    } catch (err) {
+      try { fsx.unlinkSync(tmp); } catch { /* temp file may not exist */ }
+      throw err;
+    }
+    try { fsx.chmodSync(configPath, 0o600); } catch { /* Windows / exotic fs */ }
+  };
+
+  const backupConfig = (configPath) => {
+    const backupPath = `${configPath}.bak`;
+    const overwritten = fsx.existsSync(backupPath);
+    fsx.copyFileSync(configPath, backupPath);
+    try { fsx.chmodSync(backupPath, 0o600); } catch { /* best-effort */ }
+    log(overwritten
+      ? `Overwrote existing backup at ${backupPath}`
+      : `Backed up existing config to ${backupPath}`);
+    return backupPath;
+  };
+
+  const requireClient = (operation, client) => {
+    if (!client || !SUPPORTED_CLIENTS.includes(client)) {
+      throw new CommandError(`Usage: nansen mcp ${operation} <client>. Supported: ${SUPPORTED_CLIENTS.join(', ')}`, 'INVALID_PARAMS');
+    }
+  };
+
+  const verify = async (flags, options) => {
+    // A valueless --api-key parses as a flag and would silently fall back to
+    // the saved key - the exact false positive this command exists to catch.
+    if (flags['api-key']) {
+      throw new CommandError('--api-key requires a value. Usage: nansen mcp verify --api-key <key>', 'MISSING_PARAM');
+    }
+    // parseArgs JSON-parses option values, so `--api-key null` arrives as
+    // null and a repeated flag as an array - both must fail, not fall back.
+    if ('api-key' in options && typeof options['api-key'] !== 'string') {
+      throw new CommandError('--api-key must be a single key string. Usage: nansen mcp verify --api-key <key>', 'INVALID_PARAMS');
+    }
+    // Same guards for --url: a valueless flag or a repeated/JSON-parsed value
+    // must fail loudly, not flow an array into fetch or silently fall back.
+    if (flags.url) {
+      throw new CommandError('--url requires a value. Usage: nansen mcp verify --url <url>', 'MISSING_PARAM');
+    }
+    if ('url' in options && typeof options.url !== 'string') {
+      throw new CommandError('--url must be a single URL string. Usage: nansen mcp verify --url <url>', 'INVALID_PARAMS');
+    }
+
+    const url = options.url || DEFAULT_MCP_URL;
+    const checks = await runMcpVerifyChecks({
+      apiKey: options['api-key'],
+      url,
+      env,
+      fetchFn,
+      devConfigPath,
+    });
+    const verified = checks.some(checkItem => checkItem.id === 'mcp-auth' && checkItem.status === 'ok');
+    const result = {
+      verified,
+      url,
+      checks,
+      errors: checks.filter(checkItem => checkItem.status === 'error').length,
+      warnings: checks.filter(checkItem => checkItem.status === 'warn').length,
+    };
+
+    if (verified) {
+      if (flags.json) return result;
+      log(formatMcpVerifyReport(checks, url, true));
+      return undefined;
+    }
+
+    const reason = (checks.find(checkItem => checkItem.status === 'error')
+      || checks.find(checkItem => checkItem.id === 'mcp-auth' && checkItem.status !== 'ok'))?.message
+      || 'the paid data path did not complete';
+    const message = `MCP setup verification failed - ${reason}`;
+    if (flags.json) throw new CommandError(message, 'MCP_VERIFY_FAILED', result);
+    log(formatMcpVerifyReport(checks, url, false));
+    // The human report above is the complete failure output; mark the error
+    // so runCLI exits non-zero without also emitting the JSON envelope.
+    const reportedError = new CommandError(message, 'MCP_VERIFY_FAILED');
+    reportedError.reported = true;
+    throw reportedError;
+  };
+
+  return {
+    'mcp': async (args, apiInstance, flags, options) => {
+      const sub = args[0];
+      const client = args[1];
+
+      if (!sub || flags.help || flags.h) {
+        log(MCP_USAGE);
+        return undefined;
+      }
+
+      if (sub === 'verify') {
+        return verify(flags, options);
+      }
+
+      if (sub !== 'install' && sub !== 'uninstall') {
+        throw new CommandError(`Unknown subcommand: ${sub}\n\n${MCP_USAGE}`, 'INVALID_PARAMS');
+      }
+
+      requireClient(sub, client);
+      const configPath = resolveReal(resolveClientConfigPath(client, { platform, homedir: homedirFn(), env }));
+
+      if (sub === 'uninstall') {
+        // Single state object, assigned only when the read+remove pair
+        // succeeds. The !state guard below treats any escape from the try as
+        // "nothing to do", so a future early-return added to the catch cannot
+        // leak partial state into the backup/write path. Deliberately no
+        // initializer: no-useless-assignment proves every current path assigns
+        // or exits, and undefined already reads as "nothing to do".
+        let state;
+        try {
+          const { config, existed } = readConfig(configPath);
+          const { config: updated, removed } = removeNansenEntry(config, configPath);
+          state = { existed, updated, removed };
+        } catch (err) {
+          // --dry-run must not throw on an unparseable config: users reach for it
+          // precisely when unsure of the file's state. A real uninstall still
+          // fails before writing.
+          if (flags['dry-run']) {
+            log(`Cannot preview ${configPath}: ${err.message} No changes made.`);
+            return undefined;
+          }
+          throw err;
+        }
+        if (!state || !state.existed || !state.removed) {
+          log(`No Nansen MCP entry found in ${configPath}. Nothing to do.`);
+          return undefined;
+        }
+        const { updated } = state;
+        if (flags['dry-run']) {
+          log(`Would remove "${SERVER_KEY}" entry from ${configPath} (no changes made).`);
+          return undefined;
+        }
+        // Same backup contract as install: an accidental uninstall of the wrong
+        // client is recoverable. Backup failures surface before the config write.
+        const backupPath = backupConfig(configPath);
+        writeConfig(configPath, updated);
+        log(`Removed Nansen MCP server from ${configPath}`);
+        // The backup still holds the entry we just removed, key included.
+        log(`Note: ${backupPath} still contains your API key (mode 0600). Delete it once you've confirmed the change.`);
+        log(`Restart ${client} to pick up the change.`);
+        return undefined;
+      }
+
+      // install
+      const apiKey = apiInstance?.apiKey;
+      if (!apiKey) {
+        throw new CommandError('Not logged in. Run: nansen login', 'NOT_LOGGED_IN');
+      }
+
+      // Deliberate asymmetry with uninstall --dry-run (which previews even an
+      // unparseable config): for install, a corrupt existing config is a
+      // blocking error even under --dry-run, because the eventual write would
+      // refuse it too — previewing a merge into a file we cannot parse would
+      // promise something install cannot deliver.
+      const { config, existed } = readConfig(configPath);
+
+      if (flags['dry-run']) {
+        // The key is never printed — dry-run shows a redacted entry.
+        const redacted = buildServerEntry(client, '<redacted>');
+        mergeNansenEntry(config, redacted, configPath);
+        log(`Would write "${SERVER_KEY}" entry to ${configPath}:`);
+        log(JSON.stringify({ mcpServers: { [SERVER_KEY]: redacted } }, null, 2));
+        return undefined;
+      }
+
+      const hadEntry = !!config.mcpServers?.[SERVER_KEY];
+      const merged = mergeNansenEntry(config, buildServerEntry(client, apiKey), configPath);
+
+      if (existed) {
+        backupConfig(configPath);
+      }
+      writeConfig(configPath, merged);
+
+      log(hadEntry
+        ? `Updated existing Nansen MCP entry in ${configPath}`
+        : `Installed Nansen MCP server to ${configPath}`);
+      log(`Note: your Nansen API key is stored in plaintext in ${configPath}.`);
+      log('If this file is synced or backed up (settings sync, dotfiles), your key travels with it.');
+      log(`Restart ${client} to pick up the change.`);
+      return undefined;
+    },
+  };
+}

package/src/doctor.js

@@ -85,7 +85,7 @@ const DEV_CONFIG_PATH = path.join(__dirname, '..', 'config.json');
  * ~/.nansen/config.json, then the repo-local dev config.json, then env
  * overrides — but lazily and without secrets leaving this function unmasked.
  */
-function resolveAuthConfig(env, devConfigPath = DEV_CONFIG_PATH) {
+export function resolveAuthConfig(env, devConfigPath = DEV_CONFIG_PATH) {
   const userConfigPath = getConfigFilePath(env);
 
   let config = null;
@@ -249,7 +249,7 @@ export function getAuthStatus(deps = {}) {
 
 // ============= doctor =============
 
-function check(id, status, message, fix = null) {
+export function check(id, status, message, fix = null) {
   const result = { id, status, message };
   if (fix) result.fix = fix;
   return result;
@@ -313,7 +313,7 @@ export function runDoctorChecks(deps = {}) {
       }
     }
   } else {
-    checks.push(check('api-key', auth.configFileExists ? 'error' : 'warn', 'No API key configured', 'Run: nansen login --api-key <key>  (or fund an x402 wallet for pay-per-call access)'));
+    checks.push(check('api-key', auth.configFileExists ? 'error' : 'warn', 'No API key configured', 'Run: nansen login --human or set NANSEN_API_KEY  (or fund an x402 wallet for pay-per-call access)'));
   }
   // POSIX modes are meaningless on Windows — fs.stat reports 0o666 for every
   // file there, which would warn on all of them
@@ -454,6 +454,18 @@ export async function runConnectivityChecks(deps = {}) {
 
 const STATUS_ICONS = { ok: '✓', warn: '⚠️ ', error: '❌', info: 'ℹ' };
 
+/**
+ * Render check lines without a header or summary.
+ */
+export function formatChecks(checks) {
+  const lines = [];
+  for (const c of checks) {
+    lines.push(`${STATUS_ICONS[c.status] || ' '} ${c.message}`);
+    if (c.fix) lines.push(`    ${c.fix}`);
+  }
+  return lines.join('\n');
+}
+
 /**
  * Render doctor checks as human-readable lines with a summary tail.
  */
@@ -464,10 +476,7 @@ export function formatDoctorReport(checks, { cliVersion = null, offline = false
     : 'diagnostics (local checks + a credit-free connectivity probe; --offline to skip network)';
   lines.push(`Nansen CLI doctor${cliVersion ? ` v${cliVersion}` : ''} — ${mode}`);
   lines.push('');
-  for (const c of checks) {
-    lines.push(`${STATUS_ICONS[c.status] || ' '} ${c.message}`);
-    if (c.fix) lines.push(`    ${c.fix}`);
-  }
+  lines.push(formatChecks(checks));
   const warnings = checks.filter(c => c.status === 'warn').length;
   const errors = checks.filter(c => c.status === 'error').length;
   lines.push('');