neon 4.0.0 → 4.2.0

package/README.md

@@ -62,7 +62,7 @@ Alternatively, you can authenticate a connection with a Neon API key using the `
 neon projects list --api-key <neon_api_key>
 ```
 
-For information about obtaining an Neon API key, see [Authentication](https://api-docs.neon.tech/reference/authentication), in the _Neon API Reference_.
+For information about obtaining an Neon API key, see [Authentication](https://neon.com/docs/reference/api/get-started), in the _Neon API Reference_.
 
 ## Project and branch creation
 
@@ -722,6 +722,43 @@ That message reports where parsing stopped and nothing more. `--data` carries wh
 | `--preview` | Enable preview features (scaffolding a project from a template) |
 | `--profile <name>` | Run as that stored account. See [Which credential an invocation uses](#which-credential-an-invocation-uses). |
 
+## Install the Neon MCP server (`mcp`)
+
+`neon mcp` writes the hosted Neon MCP server (`https://mcp.neon.tech/mcp`) into coding-agent config files.
+
+```bash
+# Interactive: global or project, then agents, then API key or OAuth, then confirm.
+$ neon mcp
+
+# Skip prompts. Global config, every globally detected agent, minted API key.
+$ neon mcp -y
+
+# OAuth: no API key minted. The agent prompts for Neon sign-in on first use.
+$ neon mcp --oauth
+
+# Project-level config. A minted key is still account-wide.
+$ neon mcp --project
+
+$ neon mcp --agent cursor --agent claude-code
+
+# Hide write tools. Does not change the minted key.
+$ neon mcp --read-only
+
+# Pin MCP tools to one project. Does not change the minted key.
+$ neon mcp --project-id <project-id>
+
+# Limit which tool categories are visible.
+$ neon mcp --category querying --category schema
+```
+
+On a TTY the command asks for config location (global is the default), then agents, then API key vs OAuth, then a summary to confirm before it writes. Detected agents start selected: globally installed agents or project-folder markers such as `.cursor` when the install is project.
+
+`-y` skips those questions. `--project`, `--oauth` and `--agent` skip the question they answer and still apply with `-y`. `--read-only` and `--category` are flags only and are never prompted. A linked project-folder install asks whether to pin MCP tools to that `.neon` project (`?projectId=`). An unlinked project folder does not ask. Global installs never add that param unless you pass `--project-id`. Without a TTY, pass `-y` to mint into every detected agent, `--agent` to name the agents or `--oauth` to write the URL only.
+
+`--agent` names: `antigravity`, `cline`, `cline-cli`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `mcporter`, `opencode`, `vscode`, `windsurf`, `zed`. Project installs drop `antigravity`, `cline`, `cline-cli`, `goose` and `windsurf`. `claude-desktop` is a known name that is then skipped.
+
+The default mints an account-wide API key (or reuses the Bearer already configured for Neon at `https://mcp.neon.tech/mcp`) and writes it into each selected agent's config. That key reaches everything the account can, in every organization. Revoke it with `neon api-keys revoke <id>`. `--oauth` writes the URL with no `Authorization` header; the agent signs in on first use. `--project` writes into the project config (`.cursor/mcp.json` and similar). `--read-only` adds `?readonly=true`. `--project-id` adds `?projectId=`. `--category` adds `?category=` (repeatable or comma-separated: `projects`, `branches`, `schema`, `querying`, `neon_auth`, `data_api`, `observability`, `docs`). Those query params restrict which MCP tools the server exposes; they do not change what the minted key can do.
+
 ## Snapshots (`snapshots`)
 
 `neon snapshots` (alias `neon snapshot`) manages **snapshots** — point-in-time backups of a branch that you can list, rename, expire, restore into a branch, or schedule automatically. Snapshots are a Beta Neon feature and were previously only available in the Console and REST API; this command group brings them to the CLI.
@@ -766,6 +803,15 @@ neon snapshots schedule set --branch main --schedule '[{"frequency":"weekly","da
 
 All sub-commands honor the [global options](#global-options), including `--output json|yaml|table`.
 
+## Database diagnostics (`inspect`)
+
+`neon inspect db stalled-queries` takes a read-only snapshot of active queries that have run for more than 30 seconds and groups parallel workers with their leader. Table output shows duration, wait event, blocking pids, role, query group, and query. `--output json` adds timestamps, query IDs, pids, database, and the rest of the row. A blocking pid can belong to an idle-in-transaction backend this command does not list; `neon inspect db locks` shows lock holders.
+
+```bash
+neon inspect db stalled-queries
+neon inspect db stalled-queries --output json
+```
+
 ## Logs (`logs`)
 
 `neon logs` reads the log records the services on a branch emit — Neon Functions, object storage, and Postgres computes. **Logs require Neon Platform Beta and are currently available only for projects in `aws-us-east-2`.**
@@ -1078,6 +1124,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                                   | Manage roles                       |
 | [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                                       | Manage operations                  |
 | logs                                                                       | `query`, `fields`, `field-values`                                                                            | Query branch logs (Beta)           |
+| inspect                                                                    | `db stalled-queries`                                                                                         | Inspect Postgres diagnostics       |
 | snapshots                                                                  | `list`, `get`, `create`, `update`, `delete`, `restore`, `finalize`, `schedule get`, `schedule set`           | Manage snapshots                   |
 | [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                                              | Get connection string              |
 | [psql](https://neon.com/docs/reference/cli-psql)                           |                                                                                                              | Connect to a database via psql     |
@@ -1091,6 +1138,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | deploy                                                                     |                                                                                                              | Alias for `config apply`           |
 | bootstrap                                                                  |                                                                                                              | Scaffold a project from a template |
 | init                                                                       |                                                                                                              | Set up a project for a coding agent |
+| mcp                                                                        |                                                                                                              | Install the Neon MCP server         |
 | bucket                                                                     | `create`, `list`, `delete`, `object list`, `object get`, `object put`, `object delete` (incl. `--recursive`) | Manage buckets and their objects   |
 | [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                                              | Generate a completion script       |
 
@@ -1141,7 +1189,7 @@ Global options are supported with any Neon CLI command.
 
 - <a id="api-key"></a>`--api-key`
 
-  Specifies your Neon API key. You can authenticate using a Neon API key when running a Neon CLI command instead of using `neon auth`. For information about obtaining an Neon API key, see [Authentication](https://api-docs.neon.tech/reference/authentication), in the _Neon API Reference_.
+  Specifies your Neon API key. You can authenticate using a Neon API key when running a Neon CLI command instead of using `neon auth`. For information about obtaining an Neon API key, see [Authentication](https://neon.com/docs/reference/api/get-started), in the _Neon API Reference_.
 
   ```bash
   neon <command> --api-key <neon_api_key>

package/dist/commands/auth.js

@@ -6,7 +6,7 @@ import { log } from "../log.js";
 import { getApiClient } from "../api.js";
 import { o as isOwnedCredentialPath } from "../_chunks/paths-g3DRqJiD.js";
 import { setAuthContext } from "../auth_context.js";
-import { isConfigInit, isCurrentBranchProbe, isProfileCommand } from "../context.js";
+import { isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isProfileCommand } from "../context.js";
 import { extendTokenSet } from "../utils/auth.js";
 import { auth, refreshToken } from "../auth.js";
 import { i as selectCredential, n as displacedProfileWarning, t as credentialInputs } from "../_chunks/auth_selection-Bx2NAgkk.js";
@@ -215,10 +215,12 @@ const ensureAuth = async (props) => {
 	if (isCurrentBranchProbe(props)) return;
 	if (isConfigInit(props)) return;
 	if (isProfileCommand(props)) return;
+	if (isMcpOauth(props)) return;
 	if (props._[0] === "open") return;
 	const isLocalDev = props._[0] === "dev";
 	const isBootstrap = props._[0] === "bootstrap";
 	const isInit = props._[0] === "init";
+	const isMcp = isMcpCommand(props);
 	if (props._[0] === "auth") {
 		props.apiClient = getApiClient({
 			apiKey: props.apiKey,
@@ -298,6 +300,10 @@ const ensureAuth = async (props) => {
 		log.debug("init: skipping global auth; init manages its own auth flow");
 		return;
 	}
+	if (isMcp) {
+		log.debug("mcp: no usable credentials; minting requires auth or --oauth");
+		return;
+	}
 	const apiKey = await authFlow({
 		...props,
 		profile: selection.profile

package/dist/commands/index.js

@@ -20,6 +20,7 @@ import { t as init_exports } from "./init.js";
 import { t as inspect_exports } from "./inspect.js";
 import { t as ip_allow_exports } from "./ip_allow.js";
 import { t as logs_exports } from "./logs.js";
+import { t as mcp_exports } from "./mcp.js";
 import { t as neon_auth_exports } from "./neon_auth.js";
 import { t as open_exports } from "./open.js";
 import { t as operations_exports } from "./operations.js";
@@ -58,6 +59,7 @@ var commands_default = [
 	link_exports,
 	open_exports,
 	init_exports,
+	mcp_exports,
 	data_api_exports,
 	functions_exports,
 	dev_exports,

package/dist/commands/mcp.js

@@ -0,0 +1,212 @@
+import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
+import { log } from "../log.js";
+import { readContextFile } from "../context.js";
+import { getCliName } from "../utils/cli_name.js";
+import { writer } from "../writer.js";
+import { noPassthrough, single } from "../utils/flags.js";
+import { existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
+import { mintMcpApiKey, withdrawMintedKey } from "../mcp/mint.js";
+import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { resolveInstallTargets } from "../mcp/targets.js";
+import { confirmMcpInstall } from "../mcp/wizard.js";
+import { resolveMcpPlan } from "../mcp/plan.js";
+//#region src/commands/mcp.ts
+var mcp_exports = /* @__PURE__ */ __exportAll({
+	builder: () => builder,
+	command: () => "mcp",
+	describe: () => describe,
+	handler: () => handler
+});
+const command = "mcp";
+const describe = "Install the Neon MCP server into coding agents";
+const builder = (argv) => argv.usage("$0 mcp [options]").options({
+	oauth: {
+		type: "boolean",
+		default: false,
+		describe: "Write the server URL only. The agent prompts for Neon sign-in on first use. No CLI login, no API key minted. Skips the auth question"
+	},
+	project: {
+		type: "boolean",
+		default: false,
+		describe: "Write project-level MCP config. Skips the config-location question. Does not change the minted key"
+	},
+	yes: {
+		alias: "y",
+		type: "boolean",
+		default: false,
+		describe: "Skip prompts. Defaults to global config, every detected agent and a minted account-wide API key. --project, --oauth, --agent, --read-only, --project-id and --category still apply"
+	},
+	agent: {
+		alias: "a",
+		type: "array",
+		string: true,
+		describe: "Coding agent to install into (repeatable). Skips the agent picker",
+		coerce: (value) => {
+			if (value === void 0) return [];
+			const list = Array.isArray(value) ? value : [value];
+			if (list.length === 0) throw new Error("--agent needs a value. Pass one, or omit the flag entirely.");
+			return list.map((item) => {
+				if (typeof item !== "string" || item.trim() === "") throw new Error("--agent needs a value. Pass one, or omit the flag entirely.");
+				return item;
+			});
+		}
+	},
+	"read-only": {
+		alias: "readonly",
+		type: "boolean",
+		default: false,
+		describe: "Restrict MCP tools to read-only (?readonly=true). Not prompted. Does not change the minted key"
+	},
+	"project-id": {
+		type: "string",
+		describe: "Pin MCP tools to one Neon project (?projectId=). Does not change the minted key. Interactive asks only for a linked project-folder install",
+		coerce: single("project-id")
+	},
+	category: {
+		type: "array",
+		string: true,
+		describe: "MCP tool category (repeatable or comma-separated). Default: all",
+		coerce: (value) => {
+			if (value === void 0) return [];
+			const list = Array.isArray(value) ? value : [value];
+			if (list.length === 0) throw new Error("--category needs a value. Pass one, or omit the flag entirely.");
+			const parts = [];
+			for (const item of list) {
+				if (typeof item !== "string" || item.trim() === "") throw new Error("--category needs a value. Pass one, or omit the flag entirely.");
+				for (const part of item.split(",")) {
+					const trimmed = part.trim();
+					if (trimmed === "") throw new Error("--category needs a value. Pass one, or omit the flag entirely.");
+					parts.push(trimmed);
+				}
+			}
+			return parseMcpCategories(parts);
+		}
+	}
+}).example("$0 mcp", "Interactive: config location, agents, auth, then confirm").example("$0 mcp -y", "Global config, detected agents, minted API key").example("$0 mcp --oauth", "Install with OAuth; the agent signs in on first use").example("$0 mcp --project", "Write project-level config").example("$0 mcp --agent cursor --agent claude-code", "Install into specific agents").example("$0 mcp --read-only", "Hide write tools via ?readonly=true").example("$0 mcp --project-id <id>", "Pin tools to one project via ?projectId=").example("$0 mcp --category querying --category schema", "Limit tools to those categories").strict().check(noPassthrough("mcp"));
+const handler = async (props) => {
+	const cwd = process.cwd();
+	const interactive = canPickAgentsInteractively() && props.yes !== true;
+	const linkedProjectId = readContextFile(props.contextFile).projectId;
+	const plan = await resolveMcpPlan({
+		project: props.project === true,
+		oauth: props.oauth === true,
+		agents: props.agent ?? [],
+		yes: props.yes === true,
+		cwd,
+		interactive,
+		readOnly: props.readOnly === true,
+		projectId: props.projectId,
+		categories: props.category ?? [],
+		linkedProjectId
+	});
+	const { install, skipped } = resolveInstallTargets({
+		agents: plan.agents,
+		scope: plan.scope
+	});
+	const url = neonMcpUrl({
+		readOnly: plan.readOnly,
+		projectId: plan.urlProjectId,
+		categories: plan.categories
+	});
+	if (plan.scope === "project" && plan.auth === "api-key") {
+		const tracked = trackedProjectMcpConfig({
+			agents: install,
+			cwd
+		});
+		if (tracked) throw new Error(`${tracked} is tracked by git. Untrack it before writing an API key, or pass --oauth.`);
+	}
+	const existing = plan.auth === "api-key" ? existingNeonApiKey({
+		agents: install,
+		scope: plan.scope,
+		cwd
+	}) : void 0;
+	if (plan.auth === "api-key" && !existing) {
+		if (!props.apiClient || !props.apiKey) throw new Error(`Authentication required. Run \`${getCliName()} auth\`, pass --api-key or use --oauth to install without a Neon credential.`);
+		if (!canPickAgentsInteractively() && props.yes !== true && (props.agent ?? []).length === 0) throw new Error("No interactive terminal. Pass -y to mint into every detected agent, --agent <name> to name them or --oauth to install without minting.");
+	}
+	if (interactive) {
+		if (!await confirmMcpInstall({
+			scope: plan.scope,
+			install,
+			skipped,
+			auth: plan.auth,
+			reuse: existing !== void 0,
+			url
+		})) {
+			log.info("Aborted. Nothing was written.");
+			return;
+		}
+	}
+	let auth;
+	let minted;
+	if (plan.auth === "oauth") auth = { kind: "oauth" };
+	else if (existing) {
+		auth = {
+			kind: "api-key",
+			apiKey: existing
+		};
+		log.info("Reusing the API key already configured for the Neon MCP server.");
+	} else {
+		minted = await mintMcpApiKey({ apiClient: props.apiClient });
+		auth = {
+			kind: "api-key",
+			apiKey: minted.key
+		};
+		log.warning("This key reaches everything your account can, in every organization.");
+	}
+	const rows = [];
+	let successes = 0;
+	const failedAgents = [];
+	for (const agent of install) {
+		const result = installNeonMcpServer({
+			agent,
+			scope: plan.scope,
+			cwd,
+			auth,
+			url
+		});
+		if (result.ok) {
+			successes += 1;
+			rows.push({
+				agent,
+				status: "installed"
+			});
+			log.info("Wrote %s", result.path);
+		} else {
+			rows.push({
+				agent,
+				status: result.unsupported ? "skipped" : "failed",
+				error: result.error
+			});
+			if (!result.unsupported) failedAgents.push(agent);
+		}
+	}
+	for (const row of skipped) rows.push({
+		agent: row.agent,
+		status: "skipped",
+		error: row.error
+	});
+	if (successes === 0) {
+		if (minted && props.apiClient) {
+			const withdrawn = await withdrawMintedKey(props.apiClient, minted);
+			throw new Error(withdrawn ? "Failed to write Neon MCP config to any agent. The minted API key has been revoked." : `Failed to write Neon MCP config to any agent. The minted API key could NOT be revoked. Remove it with \`${getCliName()} api-keys revoke ${minted.id}\`.`);
+		}
+		throw new Error("Failed to write Neon MCP config to any agent.");
+	}
+	log.info("URL: %s", url);
+	const out = writer(props);
+	out.write(rows, {
+		fields: [
+			"agent",
+			"status",
+			"error"
+		],
+		title: "MCP"
+	});
+	out.end();
+	if (minted) log.info("Minted API key %s (id %d, account). Revoke with: %s", minted.name, minted.id, `${getCliName()} api-keys revoke ${minted.id}`);
+	if (plan.auth === "oauth") log.info("The agent will prompt for Neon sign-in on first use.");
+	if (failedAgents.length > 0) throw new Error(`Failed to write Neon MCP config for: ${failedAgents.join(", ")}.`);
+};
+//#endregion
+export { builder, command, describe, handler, mcp_exports as t };

package/dist/context.js

@@ -50,6 +50,27 @@ const isProfileCommand = (args) => args._[0] === "profile" || args._[0] === "pro
 * far a credential reaches must come from an explicit flag, never from `.neon`.
 */
 const isApiKeysCommand = (args) => args._[0] === "api-keys" || args._[0] === "api-key";
+const isMcpCommand = (args) => args._[0] === "mcp";
+/** Raw argv is required because auth middleware runs before MCP flags are parsed. */
+const isMcpOauth = (args) => isMcpCommand(args) && argvEnablesMcpOauth(process.argv);
+const OAUTH_FALSE = /* @__PURE__ */ new Set([
+	"false",
+	"0",
+	"no"
+]);
+function argvEnablesMcpOauth(argv) {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--oauth=true" || arg === "--oauth=1") return true;
+		if (arg === "--oauth=false" || arg === "--oauth=0") continue;
+		if (arg === "--oauth") {
+			const next = argv[i + 1];
+			if (next !== void 0 && OAUTH_FALSE.has(next.toLowerCase())) continue;
+			return true;
+		}
+	}
+	return false;
+}
 const CONTEXT_FILE = ".neon";
 const GITIGNORE_FILE = ".gitignore";
 const canAccessFile = (file) => {
@@ -108,6 +129,7 @@ const enrichFromContext = (args) => {
 	if (args._[0] === "link" || args._[0] === "set-context") return;
 	if (isApiKeysCommand(args)) return;
 	if (isProfileCommand(args)) return;
+	if (isMcpCommand(args)) return;
 	const context = readContextFile(args.contextFile);
 	if (!args.orgId) args.orgId = context.orgId;
 	if (!args.projectId) args.projectId = context.projectId;
@@ -213,4 +235,4 @@ const globToRegExp = (pattern) => {
 	return new RegExp(`^${source}$`);
 };
 //#endregion
-export { applyContext, contextBranch, currentContextFile, enrichFromContext, ensureGitignored, isApiKeysCommand, isConfigInit, isCurrentBranchProbe, isProfileCommand, readContextFile, setContext, updateContextFile, walkContextFile };
+export { applyContext, contextBranch, currentContextFile, enrichFromContext, ensureGitignored, isApiKeysCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isProfileCommand, readContextFile, setContext, updateContextFile, walkContextFile };

package/dist/index.js

@@ -29,6 +29,7 @@ const NO_SUBCOMMANDS_VERBS = [
 	"link",
 	"open",
 	"init",
+	"mcp",
 	"dev",
 	"deploy",
 	"diff",

package/dist/init/agents.js

@@ -1,32 +1,6 @@
-import { agents, detectGlobalAgents, getAgentTypes } from "add-mcp";
+import { agentSupportsHttpMcp, agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, listMcpAgentIds, resolveAddMcpAgentId, tryResolveAddMcpAgentId } from "../mcp/agents.js";
+import { agents } from "add-mcp";
 //#region src/init/agents.ts
-const AGENT_ALIASES = {
-	cursor: "cursor",
-	copilot: "vscode",
-	"github-copilot": "vscode",
-	"vs-code": "vscode",
-	vscode: "vscode",
-	claude: "claude-code",
-	"claude-code": "claude-code",
-	"claude-desktop": "claude-desktop",
-	codex: "codex",
-	opencode: "opencode",
-	antigravity: "antigravity",
-	cline: "cline",
-	"cline-cli": "cline-cli",
-	"cline-vscode": "cline",
-	"gemini-cli": "gemini-cli",
-	gemini: "gemini-cli",
-	goose: "goose",
-	windsurf: "windsurf",
-	codeium: "windsurf",
-	cascade: "windsurf",
-	"github-copilot-cli": "github-copilot-cli",
-	mcporter: "mcporter",
-	zed: "zed",
-	grok: "grok-build",
-	"grok-build": "grok-build"
-};
 const SKILLS_AGENT_BY_TYPE = {
 	cursor: "cursor",
 	vscode: "github-copilot",
@@ -44,26 +18,6 @@ const SKILLS_AGENT_BY_TYPE = {
 	zed: "zed",
 	"grok-build": "grok"
 };
-function listMcpAgentIds() {
-	return getAgentTypes();
-}
-function getAgentDisplayName(id) {
-	return agents[id].displayName;
-}
-function agentSupportsProjectMcp(id) {
-	return Boolean(agents[id].localConfigPath);
-}
-function agentSupportsHttpMcp(id) {
-	return agents[id].supportedTransports.includes("http");
-}
-function tryResolveAddMcpAgentId(rawAgent) {
-	return AGENT_ALIASES[rawAgent.toLowerCase()];
-}
-function resolveAddMcpAgentId(rawAgent) {
-	const resolved = tryResolveAddMcpAgentId(rawAgent);
-	if (!resolved) throw new Error(`Unknown agent: "${rawAgent}". Supported agents: ${listMcpAgentIds().join(", ")}`);
-	return resolved;
-}
 function getSkillsAgentName(agent) {
 	if (Object.prototype.hasOwnProperty.call(SKILLS_AGENT_BY_TYPE, agent)) return SKILLS_AGENT_BY_TYPE[agent];
 	const id = tryResolveAddMcpAgentId(agent);
@@ -79,9 +33,6 @@ function agentPickerHint(id) {
 	if (supportsSkills(id)) return "MCP server, skills";
 	return "MCP server";
 }
-async function detectInstalledAgents() {
-	return detectGlobalAgents();
-}
 function mcpPickerOptions() {
 	return listMcpAgentIds().map((id) => ({
 		value: id,

package/dist/init/editors.js

@@ -1,4 +1,5 @@
-import { detectInstalledAgents } from "./agents.js";
+import { detectInstalledAgents } from "../mcp/agents.js";
+import "./agents.js";
 import { resolve } from "node:path";
 //#region src/init/editors.ts
 function getVSCodeGlobalConfigDir(homeDir) {

package/dist/init/interactive.js

@@ -1,11 +1,12 @@
 import { FALLBACK_TEMPLATES, fetchTemplates, scaffoldTemplate } from "./bootstrap.js";
 import { detectAgent, detectIde } from "./detect_agent.js";
 import { neonInitAgentCmd } from "./profile_cli.js";
-import { agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, getSkillsAgentName, mcpPickerOptions, tryResolveAddMcpAgentId } from "./agents.js";
+import { installNeonMcpServer } from "../mcp/install.js";
+import { agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, tryResolveAddMcpAgentId } from "../mcp/agents.js";
+import { getSkillsAgentName, mcpPickerOptions } from "./agents.js";
 import { ensureNeonctlAuth, isAuthenticated } from "./auth.js";
 import { installExtension, isExtensionInstalled } from "./extension.js";
 import { inspectProject } from "./inspect.js";
-import { installNeonMcpServer } from "./install_mcp.js";
 import { ensureNeonctl } from "./neonctl.js";
 import { ensureSkillsUpToDate, installAgentSkills, skillsInstalledForAgent } from "./skills.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";

package/dist/init/orchestrate.js

@@ -1,4 +1,5 @@
-import { supportsSkills, tryResolveAddMcpAgentId } from "./agents.js";
+import { tryResolveAddMcpAgentId } from "../mcp/agents.js";
+import { supportsSkills } from "./agents.js";
 import { isAuthenticated } from "./auth.js";
 import { inspectProject } from "./inspect.js";
 import { getSkillList, missingSkillsForAgent, skillsInstalledForAgent } from "./skills.js";

package/dist/init/phases/mcp.js

@@ -1,6 +1,7 @@
-import { agentSupportsHttpMcp, agentSupportsProjectMcp, getAgentDisplayName, getSkillsAgentName, resolveAddMcpAgentId, tryResolveAddMcpAgentId } from "../agents.js";
+import { installNeonMcpServer } from "../../mcp/install.js";
+import { agentSupportsHttpMcp, agentSupportsProjectMcp, getAgentDisplayName, resolveAddMcpAgentId, tryResolveAddMcpAgentId } from "../../mcp/agents.js";
+import { getSkillsAgentName } from "../agents.js";
 import { isAuthenticated } from "../auth.js";
-import { installNeonMcpServer } from "../install_mcp.js";
 //#region src/init/phases/mcp.ts
 function skillsFollowUp(agent) {
 	if (agent && !getSkillsAgentName(agent)) return agent ? [

package/dist/init/phases/setup.js

@@ -1,10 +1,11 @@
 import { FALLBACK_TEMPLATES, fetchTemplates, findTemplate, scaffoldTemplate } from "../bootstrap.js";
 import { detectIde, isCursorInstalled, isVSCodeInstalled } from "../detect_agent.js";
-import { agentSupportsProjectMcp, getSkillsAgentName, listMcpAgentIds, resolveAddMcpAgentId, supportsSkills, tryResolveAddMcpAgentId } from "../agents.js";
+import { installNeonMcpServer } from "../../mcp/install.js";
+import { agentSupportsProjectMcp, listMcpAgentIds, resolveAddMcpAgentId, tryResolveAddMcpAgentId } from "../../mcp/agents.js";
+import { getSkillsAgentName, supportsSkills } from "../agents.js";
 import { NEON_EXTENSION_ID, downloadVsix } from "../vsix.js";
 import { findEditorCommand } from "../extension.js";
 import { inspectProject } from "../inspect.js";
-import { installNeonMcpServer } from "../install_mcp.js";
 import { ensureNeonctl } from "../neonctl.js";
 import { ensureSkillsUpToDate } from "../skills.js";
 import { writeFileSync } from "node:fs";

package/dist/init/phases/status.js

@@ -1,5 +1,6 @@
 import { neonInitAgentCmd } from "../profile_cli.js";
-import { supportsSkills, tryResolveAddMcpAgentId } from "../agents.js";
+import { tryResolveAddMcpAgentId } from "../../mcp/agents.js";
+import { supportsSkills } from "../agents.js";
 import { isAuthenticated } from "../auth.js";
 import { inspectProject } from "../inspect.js";
 //#region src/init/phases/status.ts

package/dist/mcp/agents.js

@@ -0,0 +1,64 @@
+import { agents, detectGlobalAgents, getAgentTypes } from "add-mcp";
+//#region src/mcp/agents.ts
+const AGENT_ALIASES = {
+	cursor: "cursor",
+	copilot: "vscode",
+	"github-copilot": "vscode",
+	"vs-code": "vscode",
+	vscode: "vscode",
+	claude: "claude-code",
+	"claude-code": "claude-code",
+	"claude-desktop": "claude-desktop",
+	codex: "codex",
+	opencode: "opencode",
+	antigravity: "antigravity",
+	cline: "cline",
+	"cline-cli": "cline-cli",
+	"cline-vscode": "cline",
+	"gemini-cli": "gemini-cli",
+	gemini: "gemini-cli",
+	goose: "goose",
+	windsurf: "windsurf",
+	codeium: "windsurf",
+	cascade: "windsurf",
+	"github-copilot-cli": "github-copilot-cli",
+	mcporter: "mcporter",
+	zed: "zed",
+	grok: "grok-build",
+	"grok-build": "grok-build"
+};
+function listMcpAgentIds() {
+	return getAgentTypes();
+}
+function getAgentDisplayName(id) {
+	return agents[id].displayName;
+}
+function agentSupportsProjectMcp(id) {
+	return Boolean(agents[id].localConfigPath);
+}
+function agentSupportsHttpMcp(id) {
+	return agents[id].supportedTransports.includes("http");
+}
+function tryResolveAddMcpAgentId(rawAgent) {
+	return AGENT_ALIASES[rawAgent.toLowerCase()];
+}
+function resolveAddMcpAgentId(rawAgent) {
+	const resolved = tryResolveAddMcpAgentId(rawAgent);
+	if (!resolved) throw new Error(`Unknown agent: "${rawAgent}". Supported agents: ${listMcpAgentIds().join(", ")}`);
+	return resolved;
+}
+async function detectInstalledAgents() {
+	return detectGlobalAgents();
+}
+function uniqueAgentIds(ids) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const id of ids) {
+		if (seen.has(id)) continue;
+		seen.add(id);
+		out.push(id);
+	}
+	return out;
+}
+//#endregion
+export { agentSupportsHttpMcp, agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, listMcpAgentIds, resolveAddMcpAgentId, tryResolveAddMcpAgentId, uniqueAgentIds };

package/dist/mcp/install.js

@@ -0,0 +1,216 @@
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { agents, upsertServer } from "add-mcp";
+//#region src/mcp/install.ts
+const NEON_MCP_URL = "https://mcp.neon.tech/mcp";
+const NEON_MCP_NAME = "Neon";
+const NEON_MCP_CATEGORIES = [
+	"projects",
+	"branches",
+	"schema",
+	"querying",
+	"neon_auth",
+	"data_api",
+	"observability",
+	"docs"
+];
+function isMcpCategory(value) {
+	for (const category of NEON_MCP_CATEGORIES) if (category === value) return true;
+	return false;
+}
+function parseMcpCategories(raw) {
+	const out = [];
+	for (const value of raw) {
+		if (!isMcpCategory(value)) throw new Error(`Unknown MCP category: "${value}". Supported categories: ${NEON_MCP_CATEGORIES.join(", ")}`);
+		out.push(value);
+	}
+	return out;
+}
+function isNeonMcpUrl(value) {
+	try {
+		const url = new URL(value);
+		return url.protocol === "https:" && url.hostname === "mcp.neon.tech" && url.pathname === "/mcp";
+	} catch {
+		return false;
+	}
+}
+function neonMcpUrl(options = {}) {
+	const url = new URL(NEON_MCP_URL);
+	if (options.readOnly === true) url.searchParams.set("readonly", "true");
+	for (const category of options.categories ?? []) url.searchParams.append("category", category);
+	const projectId = options.projectId?.trim();
+	if (projectId) url.searchParams.set("projectId", projectId);
+	return url.href;
+}
+const BEARER_RE = /Bearer\s+([^\s"]+)/i;
+function nestedValue(root, key) {
+	let current = root;
+	for (const part of key.split(".")) {
+		if (!current || typeof current !== "object" || Array.isArray(current)) return;
+		current = current[part];
+	}
+	return current;
+}
+function recordOf(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	return value;
+}
+function bearerFromNeonMcpConfig(config) {
+	const record = recordOf(config);
+	if (!record || typeof record.url !== "string" || !isNeonMcpUrl(record.url)) return;
+	const headerRecord = recordOf(record.headers ?? record.http_headers);
+	if (!headerRecord) return;
+	const authorization = headerRecord.Authorization ?? headerRecord.authorization;
+	if (typeof authorization !== "string") return;
+	return BEARER_RE.exec(authorization.trim())?.[1];
+}
+function neonServers(value) {
+	const record = recordOf(value);
+	if (!record) return;
+	return record["Neon"] ?? record.neon;
+}
+function neonApiKeyFromFile(path, configKey) {
+	let raw;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+	try {
+		return bearerFromNeonMcpConfig(neonServers(nestedValue(JSON.parse(raw), configKey)));
+	} catch {
+		const neonBlock = raw.match(/\[mcp_servers\.Neon\][\s\S]*?(?=\n\[|$)/)?.[0];
+		if (!neonBlock) return;
+		const url = neonBlock.match(/^url\s*=\s*"([^"]*)"/m)?.[1];
+		if (!url || !isNeonMcpUrl(url)) return;
+		return BEARER_RE.exec(neonBlock)?.[1];
+	}
+}
+function configPathFor(agent, scope, cwd) {
+	const spec = agents[agent];
+	if (scope === "project") {
+		if (!spec.localConfigPath) return;
+		return join(cwd, spec.localConfigPath);
+	}
+	return spec.configPath;
+}
+function configKeyFor(agent, scope) {
+	const spec = agents[agent];
+	if (scope === "project" && spec.localConfigKey) return spec.localConfigKey;
+	return spec.configKey;
+}
+function existingNeonApiKey(options) {
+	for (const agent of options.agents) {
+		const path = configPathFor(agent, options.scope, options.cwd);
+		if (!path) continue;
+		const key = neonApiKeyFromFile(path, configKeyFor(agent, options.scope));
+		if (key) return key;
+	}
+}
+function isTrackedByGit(cwd, relativePath) {
+	try {
+		execFileSync("git", [
+			"-C",
+			cwd,
+			"ls-files",
+			"--error-unmatch",
+			"--",
+			relativePath
+		], { stdio: [
+			"ignore",
+			"pipe",
+			"ignore"
+		] });
+		return true;
+	} catch {
+		return false;
+	}
+}
+function trackedProjectMcpConfig(options) {
+	for (const agent of options.agents) {
+		const relativePath = agents[agent].localConfigPath;
+		if (!relativePath) continue;
+		if (isTrackedByGit(options.cwd, relativePath)) return relativePath;
+	}
+}
+function mcpUnsupportedReason(agent, scope) {
+	const spec = agents[agent];
+	if (!spec.supportedTransports.includes("http")) return spec.unsupportedTransportMessage ?? `${spec.displayName} does not support remote HTTP MCP servers.`;
+	if (scope === "project" && !spec.localConfigPath) return `${spec.displayName} does not support project-level MCP config.`;
+}
+function gitignoreProjectConfig(path) {
+	const dir = dirname(path);
+	const entry = basename(path);
+	const gitignorePath = join(dir, ".gitignore");
+	try {
+		if (!existsSync(gitignorePath)) {
+			writeFileSync(gitignorePath, `${entry}\n`);
+			return;
+		}
+		const current = readFileSync(gitignorePath, "utf8");
+		if (current.split(/\r?\n/).some((line) => line.trim() === entry)) return;
+		const needsLeadingNewline = current.length > 0 && !current.endsWith("\n");
+		writeFileSync(gitignorePath, `${current}${needsLeadingNewline ? "\n" : ""}${entry}\n`);
+		return;
+	} catch (err) {
+		return `Could not gitignore ${path}: ${err instanceof Error ? err.message : String(err)}`;
+	}
+}
+function protectWrittenConfig(path, scope) {
+	try {
+		chmodSync(path, 384);
+	} catch (err) {
+		return `Could not restrict permissions on ${path}: ${err instanceof Error ? err.message : String(err)}`;
+	}
+	if (scope === "project") return gitignoreProjectConfig(path);
+}
+function redactSecrets(text) {
+	return text.replace(/Bearer\s+\S+/gi, "Bearer [redacted]").replace(/napi_[A-Za-z0-9_]+/gi, "napi_[redacted]");
+}
+function installNeonMcpServer(options) {
+	const auth = options.auth ?? { kind: "oauth" };
+	const url = options.url ?? "https://mcp.neon.tech/mcp";
+	const unsupported = mcpUnsupportedReason(options.agent, options.scope);
+	if (unsupported) return {
+		ok: false,
+		unsupported: true,
+		error: unsupported
+	};
+	const server = auth.kind === "api-key" ? {
+		type: "http",
+		url,
+		headers: { Authorization: `Bearer ${auth.apiKey}` }
+	} : {
+		type: "http",
+		url
+	};
+	const result = upsertServer(options.agent, NEON_MCP_NAME, server, {
+		local: options.scope === "project",
+		cwd: options.cwd
+	});
+	if (result.success) {
+		if (auth.kind === "api-key") {
+			const paths = [result.path, ...result.extraPaths ?? []];
+			for (const path of paths) {
+				const error = protectWrittenConfig(path, options.scope);
+				if (error) return {
+					ok: false,
+					unsupported: false,
+					error
+				};
+			}
+		}
+		return {
+			ok: true,
+			path: result.path
+		};
+	}
+	return {
+		ok: false,
+		unsupported: false,
+		error: redactSecrets(result.error ?? "Failed to write Neon MCP server config")
+	};
+}
+//#endregion
+export { NEON_MCP_CATEGORIES, NEON_MCP_NAME, NEON_MCP_URL, existingNeonApiKey, installNeonMcpServer, isMcpCategory, isNeonMcpUrl, mcpUnsupportedReason, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig };

package/dist/mcp/mint.js

@@ -0,0 +1,46 @@
+import { log } from "../log.js";
+import { isNeonApiError } from "../api.js";
+import { getCliName } from "../utils/cli_name.js";
+import { mintedKeyName } from "../profile_keys.js";
+//#region src/mcp/mint.ts
+const cannotMintMessage = "This CLI credential cannot mint API keys. Organization and project-scoped keys cannot create other keys. Sign in with `neon auth` or pass a personal API key.";
+const withdraw = async (client, keyId) => {
+	if (!Number.isSafeInteger(keyId) || keyId === void 0 || keyId <= 0) return false;
+	try {
+		const { data } = await client.revokeApiKey(keyId);
+		return data.revoked === true && data.id === keyId;
+	} catch (err) {
+		log.error("Failed to revoke API key %d: %s", keyId, err instanceof Error ? err.message : String(err));
+		return false;
+	}
+};
+const assertUsable = async (client, data, fallbackName) => {
+	const problem = typeof data.key !== "string" || data.key.trim() === "" ? "Neon returned no key." : data.project_id !== void 0 ? `Neon returned a key scoped to ${data.project_id} rather than the whole account.` : !Number.isSafeInteger(data.id) ? "Neon returned no key id." : null;
+	if (problem) {
+		const withdrawn = await withdraw(client, data.id);
+		throw new Error(`${problem} ${withdrawn ? "The key has been revoked; nothing was issued." : `The key could NOT be revoked and may still be live${data.id === void 0 ? "" : `. Remove it with \`${getCliName()} api-keys revoke ${data.id}\``}.`}`);
+	}
+	const id = data.id;
+	const key = data.key;
+	if (id === void 0 || key === void 0) throw new Error("Neon returned no key.");
+	return {
+		id,
+		name: data.name ?? fallbackName,
+		key
+	};
+};
+async function mintMcpApiKey(options) {
+	const name = mintedKeyName("mcp");
+	try {
+		const { data } = await options.apiClient.createApiKey({ key_name: name });
+		return assertUsable(options.apiClient, data, name);
+	} catch (err) {
+		if (isNeonApiError(err) && (err.status === 403 || err.status === 404)) throw new Error(cannotMintMessage);
+		throw err;
+	}
+}
+async function withdrawMintedKey(apiClient, key) {
+	return withdraw(apiClient, key.id);
+}
+//#endregion
+export { mintMcpApiKey, withdrawMintedKey };

package/dist/mcp/plan.js

@@ -0,0 +1,43 @@
+import { tryResolveAddMcpAgentId } from "./agents.js";
+import { agentChoicesFrom, pickAgentsInteractively, resolveAgentSelection } from "../utils/agent_picker.js";
+import { detectMcpAgents, mcpInstallableAgents } from "./targets.js";
+import { pickMcpAuth, pickMcpProjectPin, pickMcpScope } from "./wizard.js";
+//#region src/mcp/plan.ts
+async function resolveMcpPlan(options) {
+	const prompt = options.interactive && !options.yes;
+	const scope = options.project ? "project" : prompt ? await (options.pickScope ?? pickMcpScope)() : "global";
+	const available = mcpInstallableAgents(scope);
+	const detected = await detectMcpAgents({
+		scope,
+		cwd: options.cwd
+	});
+	const agents = await resolveAgentSelection({
+		specified: options.agents,
+		choices: agentChoicesFrom(available, detected),
+		detected,
+		message: "Which coding agents should get the Neon MCP server? (space to toggle, enter to confirm)",
+		nonInteractiveMessage: scope === "project" ? `No coding agents detected in this project. Pass --agent <name>. Supported agents: ${available.join(", ")}` : `No coding agents detected. Pass --agent <name>. Supported agents: ${available.join(", ")}`,
+		resolveSpecified: (raw) => {
+			const id = tryResolveAddMcpAgentId(raw);
+			if (!id) throw new Error(`Unknown agent: "${raw}". Supported agents: ${available.join(", ")}`);
+			return id;
+		},
+		pick: prompt ? options.pickAgents ?? pickAgentsInteractively : void 0,
+		interactive: prompt
+	});
+	const auth = options.oauth ? "oauth" : prompt ? await (options.pickAuth ?? pickMcpAuth)() : "api-key";
+	let urlProjectId = options.projectId;
+	if (urlProjectId === void 0 && prompt && scope === "project" && options.linkedProjectId) {
+		if (await (options.pickProjectPin ?? pickMcpProjectPin)(options.linkedProjectId)) urlProjectId = options.linkedProjectId;
+	}
+	return {
+		scope,
+		agents,
+		auth,
+		readOnly: options.readOnly,
+		urlProjectId,
+		categories: options.categories
+	};
+}
+//#endregion
+export { resolveMcpPlan };

package/dist/mcp/targets.js

@@ -0,0 +1,34 @@
+import { mcpUnsupportedReason } from "./install.js";
+import { detectInstalledAgents, listMcpAgentIds, resolveAddMcpAgentId, uniqueAgentIds } from "./agents.js";
+import { detectProjectAgents } from "add-mcp";
+//#region src/mcp/targets.ts
+function mcpInstallableAgents(scope) {
+	return listMcpAgentIds().filter((id) => mcpUnsupportedReason(id, scope) === void 0);
+}
+async function detectMcpAgents(options) {
+	const detected = options.scope === "project" ? detectProjectAgents(options.cwd) : await detectInstalledAgents();
+	return uniqueAgentIds(detected).filter((id) => mcpUnsupportedReason(id, options.scope) === void 0);
+}
+function resolveInstallTargets(options) {
+	const requested = uniqueAgentIds(options.agents.map(resolveAddMcpAgentId));
+	const install = [];
+	const skipped = [];
+	for (const agent of requested) {
+		const error = mcpUnsupportedReason(agent, options.scope);
+		if (error) skipped.push({
+			agent,
+			error
+		});
+		else install.push(agent);
+	}
+	if (install.length === 0) {
+		const details = skipped.map((row) => row.error).join(" ");
+		throw new Error(details || `None of the selected agents can install the Neon MCP server. Supported agents: ${mcpInstallableAgents(options.scope).join(", ")}`);
+	}
+	return {
+		install,
+		skipped
+	};
+}
+//#endregion
+export { detectMcpAgents, mcpInstallableAgents, resolveInstallTargets };

package/dist/mcp/wizard.js

@@ -0,0 +1,91 @@
+import { getAgentDisplayName } from "./agents.js";
+import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import prompts from "prompts";
+//#region src/mcp/wizard.ts
+const restoreCursorOnAbort = (state) => {
+	if (state.aborted) {
+		process.stdout.write("\x1B[?25h");
+		process.stdout.write("\n");
+		process.exit(1);
+	}
+};
+const pickMcpScope = async () => {
+	if (!canPickAgentsInteractively()) throw new Error("No interactive terminal. Pass --project for project config, or -y for global.");
+	const { scope } = await prompts({
+		onState: restoreCursorOnAbort,
+		type: "select",
+		name: "scope",
+		message: "Where should the Neon MCP server be installed?",
+		initial: 0,
+		choices: [{
+			title: "Global",
+			value: "global",
+			description: "User-level agent config"
+		}, {
+			title: "Project",
+			value: "project",
+			description: "This directory"
+		}]
+	});
+	if (scope !== "global" && scope !== "project") throw new Error("Aborted.");
+	return scope;
+};
+const pickMcpAuth = async () => {
+	if (!canPickAgentsInteractively()) throw new Error("No interactive terminal. Pass --oauth for OAuth, or -y to mint an API key.");
+	const { auth } = await prompts({
+		onState: restoreCursorOnAbort,
+		type: "select",
+		name: "auth",
+		message: "How should agents authenticate to Neon?",
+		initial: 0,
+		choices: [{
+			title: "API key",
+			value: "api-key",
+			description: "Mint a key and write it into agent config"
+		}, {
+			title: "OAuth",
+			value: "oauth",
+			description: "The agent signs in on first use"
+		}]
+	});
+	if (auth !== "api-key" && auth !== "oauth") throw new Error("Aborted.");
+	return auth;
+};
+const pickMcpProjectPin = async (linkedProjectId) => {
+	if (!canPickAgentsInteractively()) return false;
+	const { pin } = await prompts({
+		onState: restoreCursorOnAbort,
+		type: "confirm",
+		name: "pin",
+		message: `Pin MCP tools to the linked project ${linkedProjectId}?`,
+		initial: true
+	});
+	return pin === true;
+};
+const mcpInstallSummary = (options) => {
+	const agents = options.install.map(getAgentDisplayName).join(", ");
+	const auth = options.auth === "oauth" ? "OAuth, agent signs in on first use" : options.reuse ? "reuse the API key already in agent config" : "mint an account-wide API key that reaches every organization";
+	const rows = [
+		["Config", options.scope === "project" ? "this directory" : "user-level"],
+		["Agents", agents],
+		["Auth", auth],
+		["URL", options.url]
+	];
+	if (options.skipped.length > 0) rows.push(["Skipped", options.skipped.map((row) => `${getAgentDisplayName(row.agent)} (${row.error})`).join("; ")]);
+	const labelWidth = Math.max(...rows.map(([label]) => label.length));
+	return rows.map(([label, value]) => `${label.padEnd(labelWidth)}  ${value}`).join("\n");
+};
+const confirmMcpInstall = async (options) => {
+	if (!canPickAgentsInteractively()) return true;
+	process.stdout.write(`\n${mcpInstallSummary(options)}\n\n`);
+	const { ok } = await prompts({
+		onState: restoreCursorOnAbort,
+		type: "confirm",
+		name: "ok",
+		message: "Write the Neon MCP server into these agents?",
+		initial: true
+	});
+	return ok === true;
+};
+//#endregion
+export { confirmMcpInstall, mcpInstallSummary, pickMcpAuth, pickMcpProjectPin, pickMcpScope };

package/dist/test_utils/fixtures.js

@@ -57,9 +57,8 @@ const test = test$1.extend({
 				apiHost,
 				"--output",
 				options.output ?? (options.outputTable ? "table" : "yaml"),
-				"--api-key",
-				"test-key",
 				"--no-analytics",
+				...options.apiKey === false ? [] : ["--api-key", options.apiKey ?? "test-key"],
 				...args
 			], {
 				stdio: "pipe",
@@ -84,9 +83,13 @@ const test = test$1.extend({
 				cp.on("close", (code) => {
 					try {
 						expect(code).toBe(options?.code ?? 0);
-						expect(output).toMatchSnapshot();
+						if (options.snapshot !== false) expect(output).toMatchSnapshot();
 						if (options.stderr !== void 0) expect(strip(error).replace(/\s+/g, " ").trim()).toEqual(typeof options.stderr === "string" ? options.stderr.toString().replace(/\s+/g, " ") : options.stderr);
-						resolve();
+						resolve({
+							stdout: output,
+							stderr: error,
+							code
+						});
 					} catch (err) {
 						reject(err instanceof Error ? err : new Error(String(err)));
 					}

package/dist/utils/agent_picker.js

@@ -0,0 +1,70 @@
+import { isCi } from "../env.js";
+import { getAgentDisplayName, resolveAddMcpAgentId, uniqueAgentIds } from "../mcp/agents.js";
+import prompts from "prompts";
+//#region src/utils/agent_picker.ts
+const canPickAgentsInteractively = () => !isCi() && Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
+const pickAgentsInteractively = async (options) => {
+	if (!canPickAgentsInteractively()) throw new Error("No interactive terminal. Pass --agent <name>, or run this command in a terminal to pick agents.");
+	if (options.choices.length === 0) throw new Error("No coding agents are available to pick.");
+	const selected = new Set(options.selected ?? []);
+	const { agents } = await prompts({
+		onState: (state) => {
+			if (state.aborted) {
+				process.stdout.write("\x1B[?25h");
+				process.stdout.write("\n");
+				process.exit(1);
+			}
+		},
+		type: "multiselect",
+		name: "agents",
+		message: options.message,
+		instructions: false,
+		min: 1,
+		choices: options.choices.map((choice) => ({
+			value: choice.id,
+			title: choice.title,
+			description: choice.description,
+			selected: selected.has(choice.id)
+		}))
+	});
+	if (!Array.isArray(agents)) throw new Error("Aborted: no agents selected.");
+	const picked = [];
+	for (const value of agents) {
+		const id = agentIdInChoices(value, options.choices);
+		if (id === void 0) throw new Error(`Unknown agent: "${String(value)}".`);
+		picked.push(id);
+	}
+	return uniqueAgentIds(picked);
+};
+const resolveAgentSelection = async (options) => {
+	if (options.specified.length > 0) {
+		const resolve = options.resolveSpecified ?? resolveAddMcpAgentId;
+		return uniqueAgentIds(options.specified.map(resolve));
+	}
+	const pick = options.pick ?? (options.interactive ?? canPickAgentsInteractively() ? pickAgentsInteractively : void 0);
+	if (pick) {
+		const selected = await pick({
+			message: options.message,
+			choices: options.choices,
+			selected: options.detected.filter((id) => options.choices.some((choice) => choice.id === id))
+		});
+		if (selected.length === 0) throw new Error("No agents selected. Pass --agent <name>, or pick at least one agent.");
+		return uniqueAgentIds(selected);
+	}
+	if (options.detected.length > 0) return uniqueAgentIds(options.detected);
+	throw new Error(options.nonInteractiveMessage);
+};
+const agentChoicesFrom = (available, detected) => {
+	const detectedSet = new Set(detected);
+	return [...available.filter((id) => detectedSet.has(id)), ...available.filter((id) => !detectedSet.has(id))].map((id) => ({
+		id,
+		title: getAgentDisplayName(id),
+		...detectedSet.has(id) ? { description: "detected" } : {}
+	}));
+};
+const agentIdInChoices = (value, choices) => {
+	if (typeof value !== "string") return;
+	for (const choice of choices) if (choice.id === value) return choice.id;
+};
+//#endregion
+export { agentChoicesFrom, canPickAgentsInteractively, pickAgentsInteractively, resolveAgentSelection };

package/dist/utils/inspect_queries.js

@@ -111,6 +111,57 @@ const INSPECT_QUERIES = {
 			ORDER BY now() - query_start DESC;
 		`
 	},
+	"stalled-queries": {
+		describe: "Active queries running longer than 30 seconds with parallel workers, waits, and blockers (compute-wide)",
+		scope: "compute",
+		fields: [
+			"duration",
+			"wait_event",
+			"blocking_pids",
+			"role",
+			"query_group",
+			"query"
+		],
+		emptyMessage: "No active queries running longer than 30 seconds.",
+		sql: `
+			WITH activity AS MATERIALIZED (
+				SELECT *
+				FROM pg_stat_activity
+				WHERE state = 'active'
+					AND backend_type IN ('client backend', 'parallel worker')
+					AND pid <> pg_backend_pid()
+			),
+			stalled_groups AS (
+				SELECT DISTINCT COALESCE(leader_pid, pid) AS query_group
+				FROM activity
+				WHERE query_start <= statement_timestamp() - interval '30 seconds'
+			)
+			SELECT
+				statement_timestamp() AS observed_at,
+				a.query_start,
+				g.query_group,
+				a.pid,
+				a.leader_pid,
+				CASE
+					WHEN a.leader_pid IS NULL THEN 'leader'
+					ELSE 'worker'
+				END AS role,
+				a.backend_type,
+				a.datname AS database,
+				a.application_name,
+				a.query_id::text AS query_id,
+				a.state,
+				a.wait_event_type,
+				a.wait_event,
+				array_to_string(pg_blocking_pids(a.pid), ',') AS blocking_pids,
+				(statement_timestamp() - a.query_start)::text AS duration,
+				a.query
+			FROM activity a
+			JOIN stalled_groups g
+				ON g.query_group = COALESCE(a.leader_pid, a.pid)
+			ORDER BY g.query_group, a.leader_pid NULLS FIRST, a.pid;
+		`
+	},
 	locks: {
 		describe: "Locks held with the acquiring query and its age (pg_locks + pg_stat_activity)",
 		scope: "database",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -63,8 +63,8 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config-runtime": "1.0.2",
     "@neon/config": "1.0.2",
+    "@neon/config-runtime": "1.0.2",
     "@neon/sdk": "2.2.0"
   },
   "optionalDependencies": {

package/dist/init/install_mcp.js

@@ -1,35 +0,0 @@
-import { agents, upsertServer } from "add-mcp";
-//#region src/init/install_mcp.ts
-const NEON_MCP_URL = "https://mcp.neon.tech/mcp";
-const NEON_MCP_NAME = "Neon";
-function installNeonMcpServer(options) {
-	const agent = agents[options.agent];
-	if (!agent.supportedTransports.includes("http")) return {
-		ok: false,
-		unsupported: true,
-		error: agent.unsupportedTransportMessage ?? `${agent.displayName} does not support remote HTTP MCP servers.`
-	};
-	if (options.scope === "project" && !agent.localConfigPath) return {
-		ok: false,
-		unsupported: true,
-		error: `${agent.displayName} does not support project-level MCP config.`
-	};
-	const result = upsertServer(options.agent, NEON_MCP_NAME, {
-		type: "http",
-		url: NEON_MCP_URL
-	}, {
-		local: options.scope === "project",
-		cwd: options.cwd
-	});
-	if (result.success) return {
-		ok: true,
-		path: result.path
-	};
-	return {
-		ok: false,
-		unsupported: false,
-		error: result.error ?? "Failed to write Neon MCP server config"
-	};
-}
-//#endregion
-export { NEON_MCP_NAME, NEON_MCP_URL, installNeonMcpServer };